Log 設定¶

このドキュメントでは、Cocos Creator のカスタムログ、Console の自動収集、および RUM 関連付けの設定について説明します。

Log の初期化¶

説明

このページのコード例の ... は、sdk の基本設定（例: datakitUrl）を省略していることを示します。先に SDK 初期化を参照して共通設定を完了してください。このページでは Log 関連の設定のみを説明します。

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

フィールド	型	必須	説明
`sampleRate`	`number`	いいえ	ログサンプリングレート、範囲 `0–1`
`enableLinkRumData`	`boolean`	いいえ	ログに現在の RUM セッションやビューなどのコンテキストを関連付けるかどうか
`enableCustomLog`	`boolean`	いいえ	Cocos API によるカスタムログの書き込みを許可するかどうか
`printCustomLogToConsole`	`boolean`	いいえ	カスタムログをネイティブコンソールにも出力するかどうか
`discardStrategy`	`discard` / `discardOldest`	いいえ	キャッシュ上限に達したときに新しいデータまたは最も古いデータを破棄する
`logLevelFilters`	`string[]`	いいえ	収集を許可するログレベル
`logCacheLimitCount`	`number`	いいえ	Native SDK のローカルログキャッシュ件数の上限
`globalContext`	`Record<string, string>`	いいえ	すべてのログに追加される静的タグ

sampleRate が 0–1 を超える場合、初期化時に RangeError がスローされます。未指定のフィールドは、対応する Native SDK のデフォルト値が使用されます。

Logger によるログ出力¶

guanceSdk.logger.log() を使用する前に、単独実行モードの logger 設定で enableCustomLog: true を有効にする必要があります。ネイティブホストの Hybrid モードでは、ネイティブ側でカスタムログを有効にする必要があります。

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

メソッドシグネチャ:

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

level のデフォルト値は info です。Android と iOS の動作を統一するため、以下のレベルを使用することを推奨します。

レベル	説明
`info`	情報
`warning`	警告
`error`	エラー
`critical`	重大
`ok`	回復

TypeScript の型ではカスタム文字列も許可されていますが、iOS Bridge は未知のレベルを info に変換するため、クロスプラットフォームプロジェクトではカスタムレベルに依存しないでください。

Console の自動収集¶

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

有効にすると以下のメソッドがラップされ、元のコンソール出力を保持したまま Log にも書き込まれます。

Console メソッド	ログレベル
`console.log`	`info`
`console.info`	`info`
`console.warn`	`warning`
`console.error`	`error`

オブジェクトの引数は優先的に JSON.stringify() でテキスト化され、シリアライズできない場合は String() が使用されます。

収集の境界

console: true は、デバッグ情報、アカウント、トークン、ビジネスオブジェクトを収集する可能性があります。本番環境では事前に Console の内容を確認し、必要に応じて無効のままにし、フィルタリング済みの guanceSdk.logger.log() のみを使用してください。

guanceSdk.shutdown() を呼び出すと、SDK は元の Console メソッドを復元します。

RUM 関連付け¶

ログと現在の RUM ビューの関連付けを確立するには、次の条件をすべて満たす必要があります。

RUM が初期化されていること
有効なビューが存在していること
enableLinkRumData が true であること

ログが最初のビューより先に生成された場合、または RUM がサンプリング対象外の場合、関連付けフィールドは空になる可能性があります。

属性とキャッシュ¶

globalContext は、すべてのログで共有する文字列タグに適しています。
attributes は個別のログ向けで、文字列、数値、ブール値、配列、JSON オブジェクトを使用できます。
現在の Cocos API では手動 Flush は公開されていません。キャッシュ、バッチ処理、アップロードのタイミングは Native SDK によって管理されます。
ログの内容と属性に、パスワード、トークン、完全な個人の機密情報を含めてはなりません。詳細はデータとプライバシーを参照してください。