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 クエリ、リクエストヘッダー、レスポンスヘッダーに機密情報が含まれる可能性があります。自動収集の前にネットワークプロトコルを確認してください。
現在の Cocos API には URL フィルタリングコールバックはありません。リクエストを除外する場合は、autoTrack.network をオフにし、収集を許可するリクエストに対して手動でトレースしてください。
Trace と RUM の関連付けは、初期化済みかつサンプリング対象となる RUM Session/View に依存します。