Skip to content

Trace Configuration

This document covers HarmonyOS Trace initialization configuration and trace link instructions.

Initialization Configuration

import { FTSDK, FTTraceConfig, TraceType } from '@guancecloud/ft_sdk/Index';

const traceConfig = new FTTraceConfig()
  .setSamplingRate(0.8)
  .setTraceType(TraceType.DDTRACE)
  .setEnableAutoTrace(true)
  .setEnableLinkRUMData(true);

FTSDK.installTraceConfig(traceConfig);
Method Type Required Description
setSamplingRate number No Sampling rate, range [0,1], default 1
setTraceType TraceType No Trace link type, default DDTRACE
setEnableLinkRUMData boolean No Whether to associate with RUM data, default false
setEnableAutoTrace boolean No Whether to enable automatic HTTP Trace, default false
setTraceHeaderHandler FTTraceHeaderHandler No Sets a global Trace Header generator for customizing request Trace Headers. Use getTraceContext(request) to return headers, traceId, and spanId at once. The SDK will use the same Trace context to complete request Header injection and RUM Resource association. Refer to the example in Custom Trace

After enabling setEnableAutoTrace(true), the SDK will automatically inject Trace Headers for requests made via RCP Session or HTTP/Axios that have the SDK interceptor mounted.

import { rcp } from '@kit.RemoteCommunicationKit';
import { createFTRCPTrackConfig } from '@guancecloud/ft_sdk/Index';

const session = rcp.createSession(createFTRCPTrackConfig({
  baseAddress: 'https://api.example.com'
}));

const request = new rcp.Request('/data', 'GET');
const response = await session.fetch(request);

Manually Obtaining Trace Headers

If your business uses other network frameworks, you can manually obtain Trace Headers and add them to requests:

Manually obtaining Trace Headers is only responsible for generating and adding request Headers. To generate and report RUM Resources, you need to use the NetworkKit/RCP/Axios interceptor provided by the SDK, or manually call the RUM Resource-related APIs to complete start/stop/addResource.

import { FTTraceManager } from '@guancecloud/ft_sdk/Index';
import http from '@ohos.net.http';

const url = 'https://api.example.com/data';
const resourceId = 'unique-resource-id';
const traceHeaders: Record<string, string> = FTTraceManager.getInstance().getTraceHeader(resourceId, url);

const httpRequest = http.createHttp();
const response = await httpRequest.request(url, {
  method: http.RequestMethod.GET,
  header: traceHeaders
});

Customizing TraceHeader via NetworkKit/RCP/Axios

After FTTraceConfig.setEnableAutoTrace(true) is enabled, the SDK will automatically inject Trace Headers in the NetworkKit/RCP/Axios interceptor chain. If FTTraceConfig.setTraceHeaderHandler(...) is also configured, the SDK will call the custom Handler when generating Trace Headers and use the headers, traceId, and spanId returned by the Handler to complete Header injection and RUM Resource association for this request.

Using the getTraceContext(request) method to customize Trace Headers allows returning request Headers, traceId, and spanId at once, ensuring that the request Headers and RUM Resource association use the same set of Trace context.

import {
  FTSDK,
  FTTraceConfig,
  FTTraceManager,
  FTTraceHeaderHandler,
  FTTraceRequestContext,
  FTTraceContext,
  TraceType
} from '@guancecloud/ft_sdk/Index';

class CustomTraceHeaderHandler implements FTTraceHeaderHandler {
  getTraceContext(request: FTTraceRequestContext): FTTraceContext {
    const traceContext = FTTraceManager.getInstance().getTraceContextDirect(request.url);
    traceContext.traceId = this.getHeaderValue(request.headers, 'x-existing-trace-id');
    traceContext.spanId = this.getHeaderValue(request.headers, 'x-existing-span-id');
    return traceContext;
  }

  private getHeaderValue(headers: Record<string, string>, key: string): string {
    const directValue = headers[key];
    if (directValue !== undefined) {
      return directValue;
    }
    const normalizedKey = key.toLowerCase();
    const headerKeys = Object.keys(headers);
    for (let i = 0; i < headerKeys.length; i++) {
      const headerKey = headerKeys[i];
      if (headerKey.toLowerCase() === normalizedKey) {
        return headers[headerKey];
      }
    }
    return '';
  }

}
Configuration: 
import { FTSDK, FTTraceConfig, TraceType } from '@guancecloud/ft_sdk/Index';

const traceConfig = new FTTraceConfig()
  .setEnableAutoTrace(true)
  .setTraceType(TraceType.TRACEPARENT)
  .setTraceHeaderHandler(new CustomTraceHeaderHandler());

FTSDK.installTraceConfig(traceConfig);

Trace Types

Trace Type Protocol Main Headers
DDTRACE DataDog Trace x-datadog-trace-id, x-datadog-parent-id, x-datadog-origin, x-datadog-sampling-priority
ZIPKIN_MULTI_HEADER Zipkin Multi-Header X-B3-TraceId, X-B3-SpanId, X-B3-ParentSpanId, X-B3-Sampled
ZIPKIN_SINGLE_HEADER Zipkin Single-Header b3
JAEGER Jaeger uber-trace-id
TRACEPARENT W3C Trace Context traceparent, tracestate
SKYWALKING SkyWalking sw8

Feedback

Is this page helpful? ×