Trace 구성¶

이 문서에서는 Cocos Creator Trace Header, Cocos 네트워크 자동 추적 및 Native 네트워크 자동 추적에 대해 설명합니다.

Trace 초기화¶

설명

이 페이지의 코드 예제에서 ...는 sdk 기본 구성(예: datakitUrl)이 생략되었음을 나타냅니다. 먼저 SDK 초기화를 참조하여 공통 구성을 완료하세요. 이 페이지에서는 Trace 관련 구성만 다룹니다.

guanceSdk.start({
  ...,
  trace: {
    sampleRate: 1,
    traceType: 'ddTrace',
    enableLinkRumData: true,
    enableNativeAutoTrace: false,
  },
});

필드	타입	필수	설명
`sampleRate`	`number`	아니요	Trace 샘플링 비율, 범위 `0–1`
`traceType`	`string`	아니요	Trace Header 전파 형식, 기본값은 `ddTrace`로 대체됨
`enableLinkRumData`	`boolean`	아니요	Trace를 현재 RUM 컨텍스트와 연결할지 여부
`enableNativeAutoTrace`	`boolean`	아니요	Android/iOS Native SDK 네트워크 자동 추적을 활성화할지 여부

지원되는 traceType은 다음과 같습니다.

ddTrace
zipkinMultiHeader
zipkinSingleHeader
traceparent
skywalking
jaeger

sampleRate가 0–1 범위를 벗어나면 초기화 시 RangeError가 발생합니다.

Cocos 네트워크 자동 추적¶

autoTrack.network: true를 설정하면 SDK는 런타임에서 제공되는 fetch 및 XMLHttpRequest를 래핑합니다.

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  trace: {
    traceType: 'traceparent',
    enableLinkRumData: true,
  },
  autoTrack: {
    network: true,
  },
});

각 요청은 다음을 수행합니다.

Resource Key 생성
URL과 Resource Key를 기반으로 Trace Header를 가져옵니다.
요청에 Header를 주입합니다.
RUM Resource의 시작, 종료, URL, 메서드, 요청 헤더, 응답 헤더 및 상태 코드를 기록합니다.
fetch가 예외를 발생시키면 network_error를 기록합니다.

자동 수집은 응답 Body를 읽지 않습니다.

Native 네트워크 자동 추적¶

enableNativeAutoTrace는 Android/iOS Native SDK의 네트워크 차단 기능을 사용하며, 요청이 최종적으로 지원되는 네이티브 네트워크 라이브러리를 통해 전송되는 시나리오에 적합합니다.

중복 Trace 방지

Cocos autoTrack.network와 enableNativeAutoTrace는 동일한 요청을 동시에 처리할 수 있습니다. 연동 시 실제 네트워크 스택에 따라 한 가지 자동 방식을 선택하고 요청 헤더와 RUM Resource가 중복되지 않는지 확인하세요.

Trace Header 수동 가져오기¶

const url = 'https://api.example.com/match';
const resourceKey = 'match-request-001';
const traceHeaders = guanceSdk.trace.getHeaders(url, resourceKey);

const response = await fetch(url, {
  headers: {
    ...traceHeaders,
    Accept: 'application/json',
  },
});

메서드 시그니처:

guanceSdk.trace.getHeaders(
  url: string,
  resourceKey?: string,
): Record<string, string>

url은 비어 있을 수 없습니다.
Resource를 수동으로도 수집하는 경우 동일한 resourceKey를 startResource(), stopResource(), addResource(), getHeaders()에 전달해야 합니다.
지원되지 않는 플랫폼이거나 Native SDK가 Header를 반환하지 않으면 메서드는 빈 객체를 반환합니다.
autoTrack.network를 활성화한 경우 fetch 또는 XMLHttpRequest에 다시 수동으로 주입할 필요가 없습니다.

전체 Resource 수동 수집 예시는 RUM 수동 계측을 참조하세요.

보안 경계¶

신뢰할 수 있는 비즈니스 도메인에만 Trace Header를 주입하세요.
URL Query, 요청 헤더, 응답 헤더에는 민감한 정보가 포함될 수 있으므로 자동 수집 전에 네트워크 프로토콜을 검토해야 합니다.
현재 Cocos API는 URL 필터링 콜백을 제공하지 않습니다. 요청을 제외해야 하는 경우 autoTrack.network를 끄고 수집을 허용할 요청에 대해 수동 추적을 수행하세요.
Trace와 RUM 연결은 초기화되고 샘플링에 포함된 RUM Session/View가 있어야 합니다.