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 |