跳转至

Trace 配置

本文用于承载 HarmonyOS Trace 初始化配置与链路追踪说明。

初始化配置

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);
方法 类型 必须 说明
setSamplingRate number 否 采样率,范围 [0,1],默认 1
setTraceType TraceType 否 链路追踪类型,默认 DDTRACE
setEnableLinkRUMData boolean 否 是否与 RUM 数据关联,默认 false
setEnableAutoTrace boolean 否 是否开启自动 HTTP Trace,默认 false
setTraceHeaderHandler FTTraceHeaderHandler 否 设置全局 Trace Header 生成器,用于自定义请求 Trace Header。通过 getTraceContext(request) 一次性返回 headers、traceId 和 spanId,SDK 会使用同一个 Trace 上下文完成请求 Header 注入和 RUM Resource 关联,示例参考自定义 Trace

自动追踪

开启 setEnableAutoTrace(true) 后,SDK 会自动为通过 RCP Session 或 HTTP/Axios 且挂载了 SDK 拦截器的请求注入 Trace Headers。

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);

手动获取 Trace Header

如果业务使用其他网络框架,可以手动获取 Trace Header 并添加到请求中:

手动获取 Trace Header 只负责生成并添加请求 Header;如需生成并上报 RUM Resource,需要使用 SDK 提供的 NetworkKit/RCP/Axios 拦截器,或自行调用 RUM Resource 相关 API 完成 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
});

通过 NetworkKit/RCP/Axios 自定义 TraceHeader

FTTraceConfig.setEnableAutoTrace(true)开启后,SDK 会在 NetworkKit/RCP/Axios 拦截器链中自动注入 Trace Header。若同时配置 FTTraceConfig.setTraceHeaderHandler(...),SDK 会在生成 Trace Header 时调用自定义 Handler,并使用 Handler 返回的 headers、traceId、spanId 完成本次请求的 Header 注入与 RUM Resource 关联。

使用 getTraceContext(request) 方式自定义 Trace Header, 可一次性返回请求 Header、traceId 和 spanId,确保请求 Header 与 RUM Resource 关联使用同一组 Trace 上下文。

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 '';
  }

}
配置:
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 类型

Trace 类型 协议 主要 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

文档评价

文档内容是否对您有帮助?