Trace Configuration¶

This document describes Cocos Creator Trace Headers, Cocos network auto-tracing, and Native network auto-tracing.

Trace Initialization¶

Note

In the code examples on this page, ... indicates that the basic sdk configuration (for example, datakitUrl) has been omitted. Complete the common configuration first by referring to SDK Initialization; this page only shows Trace-related configuration.

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

Field	Type	Required	Description
`sampleRate`	`number`	No	Trace sampling rate, range `0–1`
`traceType`	`string`	No	Trace Header propagation format, defaults to `ddTrace`
`enableLinkRumData`	`boolean`	No	Whether to associate the Trace with the current RUM context
`enableNativeAutoTrace`	`boolean`	No	Whether to enable Android/iOS Native SDK network auto-tracing

The following traceType values are supported:

ddTrace
zipkinMultiHeader
zipkinSingleHeader
traceparent
skywalking
jaeger

Initialization throws a RangeError if sampleRate is outside the 0–1 range.

Cocos Network Auto-Tracing¶

When autoTrack.network: true is set, the SDK wraps the fetch and XMLHttpRequest provided by the runtime:

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

For each request, the SDK:

Generates a Resource Key;
Retrieves Trace Headers based on the URL and Resource Key;
Injects the headers into the request;
Records the RUM Resource start, end, URL, method, request headers, response headers, and status code;
Records network_error when fetch throws an exception.

Automatic collection does not read the response Body.

Native Network Auto-Tracing¶

enableNativeAutoTrace uses the network interception capability of the Android/iOS Native SDK and applies to scenarios where requests are ultimately sent by supported native network libraries.

Avoid Duplicate Trace

Cocos autoTrack.network and enableNativeAutoTrace may process the same request at the same time. When integrating, choose one auto-tracing method based on your actual network stack, and check whether request headers and RUM Resources are duplicated.

Manually Retrieving Trace Headers¶

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',
  },
});

Method signature:

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

url cannot be empty.
If you also manually collect Resources, pass the same resourceKey to startResource(), stopResource(), addResource(), and getHeaders().
If the platform is unsupported or the Native SDK does not return headers, the method returns an empty object.
After enabling autoTrack.network, you do not need to manually inject headers for fetch or XMLHttpRequest.

For a complete example of manual Resource collection, see RUM Manual Instrumentation.

Security Boundaries¶

Inject Trace Headers only into trusted business domains.
URL queries, request headers, and response headers may contain sensitive information. Review the network protocol before enabling automatic collection.
The current Cocos API does not provide a URL filtering callback. To exclude requests, disable autoTrack.network and manually trace the requests you allow to collect.
Trace-RUM association depends on an initialized RUM Session/View that has been sampled.