Trace 구성¶
이 문서는 HarmonyOS Trace 초기화 구성과 분산 추적 설명을 다룹니다.
샘플링 필드 마이그레이션(
ft_sdk >= 0.1.18):setTraceSamplingRate는 0~100의 부동 소수점 백분율을 사용합니다. 기존setSamplingRate는 0~1 단위를 유지하며, 마이그레이션 시 값에 100을 곱합니다. 새 필드는 명시적으로 설정한 경우에만 기존 필드보다 우선하며, 유효하지 않은 값은 예외를 발생시키고 이전의 유효한 값을 변경하지 않습니다. 이 버전 미만에서는 기존 메서드를 계속 사용합니다. 폐기는 제거를 의미하지 않으며, 기존 메서드는 원래 단위와 동작을 유지합니다.
초기화 구성¶
import { FTSDK, FTTraceConfig, TraceType } from '@guancecloud/ft_sdk/Index';
const traceConfig = new FTTraceConfig()
.setTraceSamplingRate(80)
.setTraceType(TraceType.DDTRACE)
.setEnableAutoTrace(true)
.setEnableLinkRUMData(true);
FTSDK.installTraceConfig(traceConfig);
| 메서드 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
setTraceSamplingRate |
number |
아니요 | 수집률을 설정합니다. 값 범위는 [0,100]이며, 0은 수집하지 않음, 100은 전체 수집을 의미하고 기본값은 100이며 소수를 지원합니다. ft_sdk 0.1.18 이상 버전에서 지원됩니다. |
setSamplingRate |
number |
아니요 | 폐기된 호환 API로, 값 범위는 [0,1]이며 기본값은 1입니다. setTraceSamplingRate를 대신 사용하세요. |
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 |