跳转至

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) 一次性返回 headerstraceIdspanId,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 返回的 headerstraceIdspanId 完成本次请求的 Header 注入与 RUM Resource 关联。

使用 getTraceContext(request) 方式自定义 Trace Header, 可一次性返回请求 HeadertraceIdspanId,确保请求 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-idx-datadog-parent-idx-datadog-originx-datadog-sampling-priority
ZIPKIN_MULTI_HEADER Zipkin Multi-Header X-B3-TraceIdX-B3-SpanIdX-B3-ParentSpanIdX-B3-Sampled
ZIPKIN_SINGLE_HEADER Zipkin Single-Header b3
JAEGER Jaeger uber-trace-id
TRACEPARENT W3C Trace Context traceparenttracestate
SKYWALKING SkyWalking sw8

文档评价

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