Skip to content

Log Configuration

This document describes Cocos Creator custom logging, Console auto-collection, and RUM link configuration.

Log Initialization

Note

The ... in the code examples on this page indicates that the sdk base configuration (such as datakitUrl) has been omitted. Please refer to SDK Initialization first to complete the common configuration; this page only shows Log-related configuration.

truewatchSdk.start({
  ...,
  logger: {
    sampleRate: 1,
    enableCustomLog: true,
    enableLinkRumData: true,
    printCustomLogToConsole: false,
    discardStrategy: 'discard',
    logLevelFilters: ['info', 'warning', 'error', 'critical', 'ok'],
    logCacheLimitCount: 5000,
    globalContext: {
      game_channel: 'app-store',
    },
  },
});
Field Type Required Description
sampleRate number No Log sampling rate, range 0–1
enableLinkRumData boolean No Whether to link the current RUM Session, View, and other context into logs
enableCustomLog boolean No Whether to allow writing custom logs through the Cocos API
printCustomLogToConsole boolean No Whether to also print custom logs to the native console
discardStrategy discard / discardOldest No Discard new data or oldest data after reaching the cache limit
logLevelFilters string[] No Log levels allowed for collection
logCacheLimitCount number No Maximum number of logs cached locally by the Native SDK
globalContext Record<string, string> No Static tags added to all logs

If sampleRate falls outside 0–1, initialization throws a RangeError. Fields that are not passed in use the corresponding Native SDK default values.

Logger Logging

Before using truewatchSdk.logger.log(), you need to enable enableCustomLog: true in the logger configuration under standalone mode; in native host Hybrid mode, custom logging must be enabled on the native side.

truewatchSdk.logger.log(
  'battle started',
  'info',
  {
    battle_id: 'battle-001',
    player_count: 10,
  },
);

Method signature:

truewatchSdk.logger.log(
  content: string,
  level?: string,
  attributes?: FTAttributes,
): void

The default value of level is info. To ensure consistent behavior between Android and iOS, it is recommended to use the following levels:

Level Description
info Informational
warning Warning
error Error
critical Critical
ok Recovery

Although the TypeScript types allow custom strings, the iOS Bridge converts unknown levels to info, so cross-platform projects should not rely on custom levels.

Console Auto-Collection

truewatchSdk.start({
  ...,
  logger: {
    enableCustomLog: true,
    enableLinkRumData: true,
  },
  autoTrack: {
    console: true,
  },
});

When enabled, the following methods are wrapped, and Logs are written while preserving the original console output:

Console Method Log Level
console.log info
console.info info
console.warn warning
console.error error

Object arguments are first converted to text using JSON.stringify(); if serialization fails, String() is used.

Collection Boundary

console: true may collect debug information, accounts, tokens, or business objects. Review the Console content before going to production; if necessary, keep it disabled and only use a filtered truewatchSdk.logger.log().

After calling truewatchSdk.shutdown(), the SDK restores the original Console methods.

To establish a link between logs and the current RUM View, the following must all be true:

  1. RUM has been initialized;
  2. A valid View currently exists;
  3. enableLinkRumData is true.

If logs are generated before the first View, or RUM does not hit sampling, the link fields may be empty.

Attributes and Cache

  • globalContext is suitable for string tags shared by all logs.
  • attributes is suitable for individual logs and can contain strings, numbers, booleans, arrays, and JSON objects.
  • The current Cocos API does not expose a manual Flush; caching, batching, and upload timing are managed by the Native SDK.
  • Log content and attributes must not contain passwords, tokens, or complete personally sensitive information. See Data and Privacy.