コンテンツにスキップ

RUM 設定

本ページでは、Cocos Creator RUM の初期化パラメータ、自動収集範囲、および Native モニタリング設定について説明します。

RUM 初期化

説明

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

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',
    },
  },
});
フィールド 型 必須 説明
androidAppId string Android 必須 Android RUM アプリ ID
iosAppId string iOS 必須 iOS RUM アプリ ID
sampleRate number 任意 セッションサンプリングレート。範囲は 0–1
sessionOnErrorSampleRate number 任意 通常のサンプリングで選択されなかったエラーセッションの補完サンプリングレート。範囲は 0–1
enableNativeUserAction boolean 任意 ネイティブ UI Action を収集するかどうか
enableNativeUserView boolean 任意 ネイティブページの View を収集するかどうか
enableNativeUserResource boolean 任意 ネイティブネットワークの Resource を自動収集するかどうか
enableNativeCrash boolean 任意 Native Crash を収集するかどうか
enableNativeAnr boolean 任意 Native ANR を収集するかどうか
enableNativeUiBlock boolean 任意 Native UI のカクつきまたは Freeze を収集するかどうか
nativeUiBlockDurationMs number 任意 Native UI のカクつきしきい値。単位はミリ秒。enableNativeUiBlock を有効にした場合のみ有効
errorMonitorType number 任意 エラーイベントに付加するモニタリング項目の Native SDK ビットマスク
deviceMetricsMonitorType number 任意 View のデバイスメトリクスモニタリング項目の Native SDK ビットマスク
detectFrequency normal / frequent / rare 任意 デバイスメトリクスの検出頻度
globalContext Record<string, string> 任意 RUM データに追加される静的グローバルタグ

Android の実行時には androidAppId、iOS の実行時には iosAppId が必要です。同じクロスプラットフォームの TypeScript 設定に両方の値を渡すことができます。

errorMonitorType と deviceMetricsMonitorType は数値ビットマスクをそのまま透過的に渡します。現在の Native SDK バージョンの定義と一致させる必要があります。具体的な組み合わせについては、Android RUM 設定 と iOS RUM 設定 を参照してください。

Cocos の自動収集

自動収集は guanceSdk.start() の autoTrack 設定で有効になります。すべてのオプションはデフォルトで無効です：

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,
  },
});
フィールド 収集動作 依存関係
scenes シーン起動時に前の View を終了し、シーン名で新しい View を開始する RUM
actions グローバルな TOUCH_END を Action に変換する。イベントターゲットのノード名を優先し、タッチ座標を付加する RUM
errors 未処理の JavaScript Error と Promise rejection を監視する RUM。実行時には globalThis.addEventListener と globalThis.removeEventListener の両方が必要
console console.log/info/warn/error をラップしてカスタムログに変換する Log。詳細は Log 設定 を参照
network fetch と XMLHttpRequest をラップし、Resource を収集して Trace Header を注入する RUM。Trace Header の注入には Trace の初期化も必要

guanceSdk.shutdown() を呼び出すと、Console、Fetch、XHR、およびシーン/タッチリスナーが復元されます。

JavaScript エラー自動収集の実行時前提

autoTrack.errors を有効にすると、SDK はグローバルな error および unhandledrejection イベントを通じて、未処理の JavaScript 例外と未処理の Promise rejection を収集します。現在の Cocos JavaScript ランタイムが globalThis.addEventListener と globalThis.removeEventListener の両方を提供する場合にのみ、SDK はこれら 2 つのリスナーを登録します。

ランタイムが上記の API を提供しない場合、errors: true はエラーリスナーをインストールせず、初期化エラーもスローしません。ビジネスコードで捕捉済みの例外はグローバルイベントをトリガーしないため、guanceSdk.rum.addError() を呼び出して手動で報告する必要があります。

重複収集を避ける

autoTrack.actions と enableNativeUserAction、autoTrack.network と enableNativeUserResource は、同じ操作やリクエストをカバーする可能性があります。実際のリクエストスタックに応じて、Cocos レイヤーまたは Native レイヤーのいずれかの自動収集方法を選択し、テスト環境で重複データが発生していないか確認してください。

Android では autoTrack.network を有効にし、ネイティブの setEnableHttpURLConnectionResource(false) を維持して、同じ XHR が 2 つのレイヤーで収集されるのを防ぐことを推奨します。Android のネットワーク収集に関する推奨事項 を参照してください。

RUM 手動トラッキング

自動収集で対応できないカスタムページ、ビジネス操作、捕捉済み例外、カスタムネットワークスタックなどのケースでは、guanceSdk.rum を使用して手動で報告できます。スタンドアロン実行モードでは、先に guanceSdk.start() で rum を初期化する必要があります。ネイティブホストの Hybrid モードでは、ネイティブ側で先に RUM を初期化する必要があります。

属性タイプ

以下のメソッドの attributes はすべてオプションのパラメータであり、JSON でシリアライズ可能な文字列、数値、ブール値、null、配列、オブジェクトをサポートします。

Action

即時 Action を追加します：

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

ライフサイクルを Native SDK が管理する Action を開始します：

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

メソッドシグネチャ：

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

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

name と type は空にできません。type のデフォルト値は click です。

autoTrack.actions を有効にすると、グローバルなタッチ終了イベントから Action が自動的に生成されます。同じタッチに対して、手動の Action API を同時に呼び出さないでください。

View

View を開始します：

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

現在の View を終了します：

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

メソッドシグネチャ：

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

name は空にできません。アプリでは View がペアで終了するようにしてください。新しい View を開始する前に、古い View を終了してください。

autoTrack.scenes を有効にすると、SDK がシーンの View を自動的に管理します。同じシーンに対して View API を手動で呼び出さないでください。重複またはネストされたエラーが発生しないようにしてください。

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

メソッドシグネチャ：

guanceSdk.rum.addError(
  message: string,
  stack: string,
  type?: string,
  state?: 'run' | 'startup' | 'unknown',
  attributes?: FTAttributes,
): void
パラメータ デフォルト値 説明
message なし エラーメッセージ
stack なし エラースタック
type cocos_error ビジネスエラーの種類
state run 発生フェーズ：実行中、起動中、または不明
attributes なし 現在のエラーに付加する属性

autoTrack.errors を有効にすると、未処理の JavaScript Error と Promise rejection が自動的に報告されます。ビジネスコードで捕捉済みで手動報告された例外が、グローバルリスナーによって再度捕捉されることはありません。

LongTask

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

メソッドシグネチャ：

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

durationNs の単位はナノ秒です。Cocos JavaScript レイヤーでは現在 LongTask を自動認識しないため、ビジネス側で既知の時間のかかるタスクの終了後に呼び出す必要があります。

Resource

完全な Resource は 3 つの段階で構成されます：

  1. startResource()：タイマーを開始します。
  2. stopResource()：タイマーを終了します。
  3. addResource()：リクエストの内容と任意のパフォーマンス指標を追加します。
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',
    );
  }
}

メソッドシグネチャ：

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 の内容

フィールド 型 必須 説明
url string 必須 完全なリクエスト URL
httpMethod string 必須 HTTP メソッド
requestHeaders Record<string, string> 任意 リクエストヘッダー
responseHeaders Record<string, string> 任意 レスポンスヘッダー
responseBody string 任意 レスポンス Body。機密データが含まれる可能性があるため、慎重に収集してください
statusCode number 任意 HTTP ステータスコード
responseContentType string 任意 レスポンスの Content-Type
responseContentEncoding string 任意 レスポンスの Content-Encoding

Resource のパフォーマンス指標

すべての時間フィールドの単位はナノ秒です：

フィールド 説明
fetchStartTime リクエスト開始時間
tcpStartTime TCP 接続の開始時間
tcpEndTime TCP 接続の終了時間
dnsStartTime DNS 解決の開始時間
dnsEndTime DNS 解決の終了時間
responseStartTime レスポンス開始時間
responseEndTime レスポンス終了時間
sslStartTime TLS 接続の開始時間
sslEndTime TLS 接続の終了時間

key は 3 つの RUM メソッドと guanceSdk.trace.getHeaders() で一致している必要があります。

自動と手動はどちらかを選択

autoTrack.network を有効にすると、fetch と XMLHttpRequest は自動的に収集されます。同じリクエストに対して上記の手動 Resource フローを実行しないでください。

アップロード動作

現在の Cocos API では手動の Flush は公開されていません。イベントは Native SDK に書き込まれた後、Native SDK のキャッシュおよびアップロードポリシーに従って送信されます。アプリケーションを閉じる前に、guanceSdk.shutdown() による強制アップロードに依存しないでください。

Cocos と Native のデータ境界

  • scenes、actions、errors、network は Cocos JavaScript レイヤーの動作を収集します。
  • enableNative* オプションは Android/iOS のネイティブコンテナの動作を収集します。
  • Native Crash、ANR、UI Block、およびデバイス指標は、基盤となる Android/iOS SDK によって生成されます。
  • Cocos Long Task は現在自動収集されないため、手動 API を呼び出す必要があります。
  • 自動ネットワーク収集は、現在のランタイムが実際に提供する fetch と XMLHttpRequest のみをカバーします。

ネイティブ App が一部のページでのみ Cocos を使用する場合は、ネイティブ SDK の要件に従って初期化を完了し、enterCocos() と leaveCocos() を使用して Cocos ページが表示されている間に View のライフサイクルを切り替えてください。完全な設定については、ネイティブと Cocos のハイブリッド開発 を参照してください。

サンプリング

sampleRate と sessionOnErrorSampleRate は有限の数値であり、0–1 の範囲内である必要があります。範囲外の場合、TypeScript レイヤーは初期化フェーズで RangeError をスローします。値が渡されない場合は、対応する Native SDK のデフォルト値が使用されます。

関連トピック

フィードバック

このページは役に立ちましたか？