콘텐츠로 이동

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

문서 평가

이 페이지가 도움이 되었나요?