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。