Trace Configurations¶

This document is used to carry the HarmonyOS Trace initialization configuration and link tracing descriptions.

Initialization Configurations¶

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	Descriptions
`setSamplingRate`	`number`	No	Sampling rate, range `[0,1]`, default `1`
`setTraceType`	`TraceType`	No	Trace 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	Set the global Trace Header generator for customizing request Trace Headers. Returns `headers`, `traceId`, and `spanId` at once via `getTraceContext(request)`. The SDK uses the same Trace context to complete request Header injection and RUM Resource association. For examples, refer to Custom Trace

Automatic Tracing¶

After enabling setEnableAutoTrace(true), the SDK automatically injects Trace Headers into requests that go through RCP Session or HTTP/Axios with the SDK interceptor attached.

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 the business uses other network frameworks, you can manually obtain Trace Headers and add them to the request:

Manually obtaining Trace Headers is only responsible for generating and adding request Headers; if you need to generate and report RUM Resources, you need to use the NetworkKit/RCP/Axios interceptors provided by the SDK, or call the RUM Resource related APIs (start/stop/addResource) yourself.

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 Trace Headers via NetworkKit/RCP/Axios¶

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

Use the getTraceContext(request) method to customize Trace Headers, which can return the request Header, traceId, and spanId at once, ensuring that the request Header 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 '';
  }

}

Configurations:

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`