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 유형 | 프로토콜 | 주요 헤더 |
|---|---|---|
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 |