コンテンツにスキップ

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 いいえ ネイティブ UI のブロッキングまたはフリーズを収集するかどうか
nativeUiBlockDurationMs number いいえ ネイティブ 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 はこれらのリスナーを登録します。

ランタイムが上記の 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

startAction と addAction の使い分け
  • startAction は内部で自動的に Action の所要時間を計算し、その間に近くで発生した Resource、LongTask、Error データと可能な限り関連付けます。また、100 ms の頻繁なトリガー保護もあり、ユーザー操作タイプのデータに推奨されます。
  • 頻繁に呼び出す必要がある場合は、addAction を使用してください。addAction で報告された Action は startAction と競合せず、現在の Resource、LongTask、Error データとも関連付けられません。

即時 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 のみを対象とします。

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

サンプリング

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

関連トピック

フィードバック

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