RUM Configuration¶

This document describes the Cocos Creator RUM initialization parameters, automatic collection scope, and Native monitoring configuration.

RUM Initialization¶

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    sampleRate: 1,
    sessionOnErrorSampleRate: 0,
    enableNativeCrash: true,
    enableNativeAnr: true,
    globalContext: {
      game_mode: 'ranked',
    },
  },
});

The Android runtime requires androidAppId, and the iOS runtime requires iosAppId. A single cross-platform TypeScript configuration can pass both values at the same time.

errorMonitorType and deviceMetricsMonitorType pass through numeric bitmasks directly and must match the definitions in the current Native SDK version. For specific combinations, see Android RUM Configuration and iOS RUM Configuration.

Cocos Automatic Collection¶

Automatic collection is enabled through the autoTrack configuration of guanceSdk.start(). All options are disabled by default:

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  logger: {
    enableCustomLog: true,
  },
  trace: {
    traceType: 'ddTrace',
  },
  autoTrack: {
    scenes: true,
    actions: true,
    errors: true,
    console: false,
    network: true,
  },
});

Calling guanceSdk.shutdown() restores the Console, Fetch, XHR, and scene/touch listeners.

Manual RUM Instrumentation¶

When automatic collection cannot cover scenarios such as custom pages, business operations, caught exceptions, and custom network stacks, report data manually through guanceSdk.rum. In standalone mode, initialize rum in guanceSdk.start() first; in native host Hybrid mode, the native side must initialize RUM first.

Attribute Types¶

The attributes parameter in the following methods is optional and supports JSON-serializable strings, numbers, booleans, null, arrays, and objects.

Action¶

Add an instant Action:

guanceSdk.rum.addAction('Use Skill', 'click', {
  skill_id: 'fireball',
});

Start an Action whose associated lifecycle is managed by the Native SDK:

guanceSdk.rum.startAction('Matchmaking', 'custom', {
  queue: 'ranked',
});

Method signatures:

guanceSdk.rum.addAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.startAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

name and type cannot be empty, and the default value of type is click.

When autoTrack.actions is enabled, global touch-end events automatically generate Actions. Do not call the manual Action APIs for the same touch.

View¶

Start a View:

guanceSdk.rum.startView('Battle', {
  map_id: 'map-001',
});

Stop the current View:

guanceSdk.rum.stopView({
  battle_result: 'victory',
});

Method signatures:

guanceSdk.rum.startView(name: string, attributes?: FTAttributes): void
guanceSdk.rum.stopView(attributes?: FTAttributes): void

name cannot be empty. The application should ensure Views are stopped in pairs; stop the old View before starting a new one.

When autoTrack.scenes is enabled, the SDK automatically manages scene Views. Do not call the View APIs manually for the same scene to avoid duplicate or nested errors.

Error¶

try {
  startBattle();
} catch (error) {
  const exception = error instanceof Error
    ? error
    : new Error(String(error));

  guanceSdk.rum.addError(
    exception.message,
    exception.stack || '',
    'game_logic_error',
    'run',
    {
      scene: 'Battle',
    },
  );
}

Method signatures:

guanceSdk.rum.addError(
  message: string,
  stack: string,
  type?: string,
  state?: 'run' | 'startup' | 'unknown',
  attributes?: FTAttributes,
): void

When autoTrack.errors is enabled, uncaught JavaScript Errors and Promise rejections are reported automatically. Exceptions already caught and reported manually by business code are not captured again by the global listeners.

LongTask¶

guanceSdk.rum.addLongTask(
  'GenerateWorld',
  850 * 1_000_000,
  {
    map_size: 'large',
  },
);

Method signatures:

guanceSdk.rum.addLongTask(
  stack: string,
  durationNs: number,
  attributes?: FTAttributes,
): void

durationNs is in nanoseconds. The Cocos JavaScript layer does not currently recognize LongTasks automatically; business code must call this API after a known long-running task completes.

Resource¶

A complete Resource consists of three phases:

1. startResource(): start timing;
2. stopResource(): stop timing;
3. addResource(): add the request content and optional performance metrics.

export async function requestMatch(): Promise<void> {
  const key = `match-${Date.now()}`;
  const url = 'https://api.example.com/match';
  const started = Date.now() * 1_000_000;

  guanceSdk.rum.startResource(key, {
    request_source: 'matchmaking',
  });

  try {
    const traceHeaders = guanceSdk.trace.getHeaders(url, key);
    const response = await fetch(url, {
      headers: traceHeaders,
    });
    const ended = Date.now() * 1_000_000;

    guanceSdk.rum.stopResource(key);
    guanceSdk.rum.addResource(
      key,
      {
        url,
        httpMethod: 'GET',
        requestHeaders: traceHeaders,
        statusCode: response.status,
        responseContentType: response.headers.get('content-type') || undefined,
      },
      {
        fetchStartTime: started,
        responseStartTime: ended,
        responseEndTime: ended,
      },
    );
  } catch (error) {
    guanceSdk.rum.stopResource(key);
    const exception = error instanceof Error
      ? error
      : new Error(String(error));
    guanceSdk.rum.addError(
      exception.message,
      exception.stack || '',
      'network_error',
    );
  }
}

Method signatures:

guanceSdk.rum.startResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.stopResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.addResource(
  key: string,
  content: FTResourceContent,
  metrics?: FTResourceMetrics,
): void

Resource Content¶

Resource Performance Metrics¶

All time fields are in nanoseconds:

key must be consistent across the three RUM methods and guanceSdk.trace.getHeaders().

Upload Behavior¶

The current Cocos API does not expose manual Flush. After events are written to the Native SDK, the Native SDK sends them based on its own caching and upload strategies. Do not rely on guanceSdk.shutdown() to force an upload before the application closes.

Cocos and Native Data Boundaries¶

• scenes, actions, errors, and network collect behavior at the Cocos JavaScript layer.
• The enableNative* options collect behavior from the Android/iOS native containers.
• Native Crashes, ANRs, UI Blocks, and device metrics are generated by the underlying Android/iOS SDK.
• Cocos Long Tasks are not collected automatically; use the manual APIs.
• Automatic network collection only covers the fetch and XMLHttpRequest actually provided by the current runtime.

When a native App uses Cocos only on some pages, complete initialization as required by the native SDK, and use enterCocos() and leaveCocos() to switch the View lifecycle while Cocos pages are visible. For the complete configuration, see Native and Cocos Hybrid Development.

Sampling¶

sampleRate and sessionOnErrorSampleRate must be finite numbers within 0–1. If out of range, the TypeScript layer throws a RangeError during initialization. When not provided, the defaults of the corresponding Native SDK are used.

Related Topics¶

• Cocos Creator Session Replay
• Application Data Collection
• Using Custom Tags
• Custom Collection Rules
• Native and Cocos Hybrid Development
• Troubleshooting