콘텐츠로 이동

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

문서 평가

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