cx-rum-setup

RUM セットアップスキル

このスキルを使って、アプリケーションを Coralogix Real User Monitoring（RUM）にオンボーディングします。RUM API キーを取得し、プラットフォーム SDK をインストールして、init 呼び出しを追加し、イベントが rum.events データセットに到達することを確認します。

---

CLI コマンド

コマンド	目的
cx iam api-keys list -o json	候補となるキーとチーム ID を一覧表示します（出力に権限は含まれません）
cx iam api-keys send-data-keys -o json	候補となる送信データキーを一覧表示します（出力に権限は含まれません）
cx iam api-keys get <id> -o json	キーの権限（keyInfo.keyPermissions）と値を読み取ります
cx iam api-keys create --from-file <file>	RUM キーを作成します（書き込み操作のため、承認と --yes が必要です）
cx docs search <query> / cx docs fetch <suffix>	プラットフォームごとの最新の SDK インストールおよび初期化ドキュメントを取得します
cx dataprime query --source rum.events '<query>'	RUM イベントの到着を確認します
cx profiles list	プロファイルとリージョンを表示します。キーと coralogixDomain の両方に使用するアクティブなプロファイルを選びます

cx iam と cx dataprime では、特定のチームを対象にするために -p <profile> を指定します。cx profiles と cx docs はローカルコマンドであり、-p は指定しません（cx profiles list -p ... はエラーです）。

---

ワークフロー

1. プラットフォームを検出する

何よりも先に、ユーザーのリポジトリを調べます。判定材料が重複することがあります（React Native アプリにも react が含まれ、Flutter と React Native のリポジトリには ios/ および android/ フォルダーが含まれます）。そのため、次の順序で確認し、最初に一致した時点で止めます。

#	判定材料	プラットフォーム
1	pubspec.yaml	Flutter SDK。ios/ / android/ フォルダーは無視します
2	react-native（または expo）を含む package.json	React Native SDK。react とネイティブフォルダーは無視します
3	next を含む package.json	Next.js（ブラウザー SDK、クライアント専用の初期化）
4	ブラウザーを示す情報（react-dom、vue、@angular/core、svelte、ブラウザーバンドラー（vite、webpack、parcel）、または index.html エントリ）を含む package.json	ブラウザー SDK（@coralogix/browser）
5	Podfile / Package.swift / *.xcodeproj	iOS SDK
6	Android プラグインを含む build.gradle(.kts)	Android SDK

package.json があるだけ（Node バックエンドやツールなど）では、ブラウザーアプリとは見なせません。どの条件にも一致しない場合は、推測せず、対応するクライアントアプリが見つからなかったことをユーザーに伝えます。

2. プロファイルを選ぶ — キー操作を行う前に

キーと SDK のドメインは、同じプロファイルから取得する必要があるため、キーを扱う前にプロファイルを決めます。アクティブなプロファイルは、-p <name> が指定されていればその値、そうでなければ $CX_PROFILE が設定されている場合はその値、どちらもなければ cx profiles list の DEFAULT 行です。DEFAULT 行だけを読んで決めつけないでください。プロファイルが複数あり、名前が指定されていない場合は、アプリがどのチームに属するかを今すぐユーザーに確認してから、以降のすべての cx iam および cx dataprime の呼び出しに -p <name> を指定します。

coralogixDomain は、そのプロファイルの REGION を大文字にした値です。EU1、EU2、US1、US2、US3、AP1、AP2、AP3 のいずれかです。

3. RUM API キーを取得する

RUM キーは設計上、公開キーです。クライアントコードに含めて配布します。SendRUMData プリセットを使って作成してください。これは UI の RUM フローで作成されるキーと同じです。このプリセットが付与する権限は rum-ingress:SendData の 1 つだけで、単独で使用するものです。他のプリセットや権限は追加しないでください。（rum-ingress:SendData を直接付与しても動作しますが、UI では CUSTOM キーと表示されるため、プリセットの使用を推奨します。）Settings → API Keys では、RUM キーの種類が「Send Your Data」、プリセットが SendRUMData と表示されます。SendData プリセットは選ばないでください。ログ／メトリクス／スパンの取り込み権限は付与されますが、RUM の権限は付与されず、キーが公開キーではなくシークレットになります。

まず既存のキーを再利用します。 既存の RUM キーを確認してください。

cx iam api-keys list -p <profile> -o json
cx iam api-keys send-data-keys -p <profile> -o json

これらの一覧には権限が含まれないため、各行は候補にすぎません。名前だけを根拠にキーを再利用しないでください。候補ごとに cx iam api-keys get <id> -p <profile> -o json を実行し、有効（keyInfo.active: true）であり、keyInfo.keyPermissions に SendRUMData だけが含まれ、他の権限がない（または rum-ingress:SendData だけが権限として含まれる）場合に限って再利用します。無効なキーはスキップしてください。SDK からデータを送信できません。値は keyInfo.value にあります（ハッシュ化されていないキーで返されます。ハッシュ化されたキーは再利用できないため、新しいキーを作成してください）。

該当するキーがない場合は新しく作成します。 これは書き込み操作です。--yes を渡す前に、その内容をユーザーに説明して承認を得てください（cx-platform-admin と同じルールです）。

cat > rum-key.json <<'EOF'
{
  "name": "<app-name> RUM",
  "owner": { "teamId": <team-id> },
  "keyPermissions": { "presets": ["SendRUMData"], "permissions": [] },
  "hashed": false
}
EOF
cx iam api-keys create --from-file rum-key.json -p <profile> --yes -o json

• teamId：ステップ 2 のプロファイルファイル ~/.cx/profiles/<profile>.toml（cx init が書き込みます）から cached_team_id を読み取るか、cx iam api-keys list -o json の任意のキーの owner.teamId を使うか、ユーザーに確認してください。

• Permission denied：RUM キーは Send-Your-Data（データ取り込み）キーなので、チームのカスタムキー用の権限ではなく、DATA-INGEST-API-KEYS の権限が必要です。

  • send-data-keys の実行時：ロールに DATA-INGEST-API-KEYS:READCONFIG（キーの表示）がありません。
  • get または create の実行時：ロールに DATA-INGEST-API-KEYS:MANAGE がありません（キーの値を返すため、get にも必要です）。

  他のペイロードで再試行しないでください。不足している権限をユーザーに伝えて取得を依頼するか、Settings → API Keys でキーの種類を Send Your Data Key、ロールプリセットを SendRUMData のみにして作成してもらってください（管理者に依頼してもかまいません）。その後、キーの値を使ってステップ 4 から続行してください。

• hashed: false にすると、後からキーの値を取得できます。公開 RUM キーでは問題ありません。

• レスポンスには value が含まれます。これが SDK 用の public_key です。

4. 最新の SDK ドキュメントを取得する

SDK のパッケージ名、バージョン、オプションは変更されるため、推測せずに取得してください（coralogix-docs を参照）。

cx docs search "RUM SDK installation <platform>" --limit 5
cx docs fetch <suffix-from-search>

5. インストールして初期化する

ステップ 2 のプロファイルと coralogixDomain を使用してください。

ブラウザーの例（取得したドキュメントと照合してください）：

npm install @coralogix/browser

import { CoralogixRum } from '@coralogix/browser';

CoralogixRum.init({
  application: '<app-name>',
  environment: 'production',
  public_key: process.env.NEXT_PUBLIC_CX_RUM_KEY!, // or import.meta.env.VITE_CX_RUM_KEY
  coralogixDomain: 'EU1',
  version: '<app-version>',
});

注意点：

• できるだけ早く、1 回だけ初期化してください。 アプリケーションのエントリーポイント（main.ts、index.tsx、ルートレイアウト）で行います。
• Next.js： 初期化はクライアント側でのみ行います。useEffect で init を呼び出す 'use client' コンポーネントを作成し、ルートレイアウトからレンダリングしてください。サーバーコンポーネントでは決して初期化しないでください。
• 環境変数： キーはハードコードせず、環境設定（NEXT_PUBLIC_*、VITE_*、REACT_APP_*）に保存してください。キーは公開されていますが、環境設定を使うと簡単にローテーションできます。
• version はリリースと一致させてください。ソースマップとリリースの比較に使用されます。
• ソースマップ（任意）は coralogix-rum-cli でアップロードし、別のキーが必要です。UI でキーの種類を Team Key、ロールプリセットを SourceMapping（source-mapping:ReadMapping + UploadMapping）にしてください。RUM キーを再利用しないでください。また、このキーはシークレットとして保持し、CI でのみ使用してください（クライアントコードに含めないでください）。cx docs fetch user-guides/rum/cli/rum-cli.md を参照してください（検索結果には表示されません）。

6. データの到着を確認する（任意）

キーが作成され、init が設定されれば準備は完了です。データはアプリの実行後、ユーザーがアプリを利用して初めて送信され、SDK はデータをバッチで送信します。後で実行するクエリをユーザーに渡すか、アプリを読み込んでいる場合は今すぐ実行します。

cx dataprime query --source rum.events \
  "filter \$d.version_metadata.app_name == '<app-name>' | limit 10" -p <profile> -o json

行が表示されない場合は、ブラウザーのネットワークタブで RUM のイングレスエンドポイントへのリクエストを確認してください。一般的な原因として、広告ブロッカー、誤った coralogixDomain、追加の権限が付与されたキーが挙げられます。

---

主な原則

• RUM キーには SendRUMData プリセットのみを設定します — キーにほかの権限は設定しません
• 作成する前に再利用を検討し、ユーザーの承認なしに --yes を渡さないでください
• プラットフォームごとに cx docs で SDK ドキュメントを取得します — バージョンやオプションを記憶に頼ってハードコードしないでください
• クライアント側で一度だけ初期化します。アプリのエントリポイントで行ってください
• 完了条件は、キーと init の設定です — 後でデータを確認できるよう、rum.events クエリを渡してください

---

関連スキル

• cx-platform-admin — 一般的な API キー管理
• coralogix-docs — プラットフォーム固有の SDK ドキュメントを取得
• cx-telemetry-querying — データが流れ始めた後に RUM データをクエリ