cx-rum-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RUM Setup Skill

RUM 配置 Skill

Use this skill to onboard an application to Coralogix Real User Monitoring (RUM): get a RUM API key, install the platform SDK, add the

init

call, and verify events land in the

rum.events

dataset.

使用此 skill 将应用接入 Coralogix Real User Monitoring (RUM)：获取 RUM API key、安装平台 SDK、添加

init

调用，并验证事件是否已落入

rum.events

数据集。

CLI Commands

CLI 命令

Command	Purpose
`cx iam api-keys list -o json`	List candidate keys and the team ID (no permissions in output)
`cx iam api-keys send-data-keys -o json`	List candidate send-data keys (no permissions in output)
`cx iam api-keys get <id> -o json`	Read a key's permissions ( `keyInfo.keyPermissions` ) and value
`cx iam api-keys create --from-file <file>`	Create the RUM key (write - needs approval + `--yes` )
`cx docs search <query>` / `cx docs fetch <suffix>`	Current SDK install and init docs per platform
`cx dataprime query --source rum.events '<query>'`	Verify RUM events arrive
`cx profiles list`	Profiles and regions - pick the active one for both key and `coralogixDomain`

cx iam

and

cx dataprime

take

-p <profile>

to target a specific team.

cx profiles

and

cx docs

are local commands - they take no

-p

(

cx profiles list -p ...

is an error).

命令	用途
`cx iam api-keys list -o json`	列出候选密钥和 team ID（输出中不包含权限信息）
`cx iam api-keys send-data-keys -o json`	列出候选 send-data 密钥（输出中不包含权限信息）
`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`	Profiles 和区域——为密钥和 `coralogixDomain` 选择当前配置

cx iam

和

cx dataprime

接受

-p <profile>

，用于指定目标 team。

cx profiles

和

cx docs

是本地命令，不接受

-p

（执行

cx profiles list -p ...

会报错）。

Workflow

工作流

1. Detect the platform

1. 检测平台

Inspect the user's repo before anything else. Signals overlap (React Native apps also list

react

; Flutter and React Native repos contain

ios/

and

android/

folders), so check in this order and stop at the first match:


ios/
react
package.json
@coralogix/browser
Podfile
build.gradle(.kts)

#	Signal	Platform
1	`pubspec.yaml`	Flutter SDK - ignore its `ios/` / `android/` folders
2	`package.json` with `react-native` (or `expo` )	React Native SDK - ignore `react` and native folders
3	`package.json` with `next`	Next.js (browser SDK, client-only init)
4	`package.json` with a browser signal - `react-dom` , `vue` , `@angular/core` , `svelte` , a browser bundler ( `vite` , `webpack` , `parcel` ), or an `index.html` entry	Browser SDK ( `@coralogix/browser` )
5	`Podfile` / `Package.swift` / `*.xcodeproj`	iOS SDK
6	`build.gradle(.kts)` with Android plugin	Android SDK

package.json

alone (Node backend, tooling) is not a browser app. If nothing matches, tell the user no supported client app was found instead of guessing.

首先检查用户的代码仓库。各项信号可能相互重叠（React Native 应用也会列出

react

；Flutter 和 React Native 仓库都包含

ios/

和

android/

目录），因此请按以下顺序检查，并在第一个匹配项处停止：


ios/
react
package.json
@coralogix/browser
Podfile
build.gradle(.kts)

#	信号	平台
1	`pubspec.yaml`	Flutter SDK——忽略其中的 `ios/` / `android/` 目录
2	`package.json` 中包含 `react-native` （或 `expo` ）	React Native SDK——忽略 `react` 和原生目录
3	`package.json` 中包含 `next`	Next.js（Browser SDK，仅在客户端初始化）
4	`package.json` 中包含 browser 信号—— `react-dom` 、 `vue` 、 `@angular/core` 、 `svelte` 、browser bundler（ `vite` 、 `webpack` 、 `parcel` ），或存在 `index.html` 入口	Browser SDK（ `@coralogix/browser` ）
5	`Podfile` / `Package.swift` / `*.xcodeproj`	iOS SDK
6	包含 Android plugin 的 `build.gradle(.kts)`	Android SDK

仅存在

package.json

（Node 后端、工具链）并不代表这是一个 browser 应用。如果没有任何匹配项，请告知用户未找到受支持的客户端应用，不要自行猜测。

2. Pick the profile - before any key operation

2. 选择 profile——在执行任何密钥操作之前

The key and the SDK domain must come from one profile, so settle it before touching keys. The active profile is

-p <name>

if given, else

$CX_PROFILE

if set, else the

DEFAULT

row of

cx profiles list

- don't just read the

DEFAULT

row. If there are several profiles and none was named, ask the user which team the app belongs to now, then pass

-p <name>

to every

cx iam

and

cx dataprime

call that follows.

coralogixDomain

is that profile's

REGION

in upper case:

EU1

EU2

US1

US2

US3

AP1

AP2

AP3

密钥和 SDK domain 必须来自同一个 profile，因此在操作密钥前先确定 profile。如果指定了

-p <name>

，则使用该 profile；否则，如果设置了

$CX_PROFILE

，则使用该环境变量；否则，使用

cx profiles list

输出中的

DEFAULT

行——不要直接读取

DEFAULT

行。如果存在多个 profile 且未指定任何名称，现在询问用户该应用属于哪个 team，然后在后续每次调用

cx iam

和

cx dataprime

时都传入

-p <name>

。

coralogixDomain

是该 profile 的

REGION

，并转换为大写：

EU1

、

EU2

、

US1

、

US2

、

US3

、

AP1

、

AP2

、

AP3

。

3. Get a RUM API key

3. 获取 RUM API key

RUM keys are public by design - they ship inside client code. Create it with the SendRUMData
preset - the same key the UI's RUM flow creates. That preset grants exactly one permission,

rum-ingress:SendData

, and is standalone: never add other presets or permissions. (Granting

rum-ingress:SendData

directly also works but shows as a

CUSTOM

key in the UI, so prefer the preset.) In Settings → API Keys a RUM key shows type "Send Your Data" with preset

SendRUMData

. Do not pick the

SendData

preset - it grants logs/metrics/spans ingest but not RUM, and makes the key secret, not public.

Reuse first. Check for an existing RUM key:

bash

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

These listings don't include permissions, so treat every row as a candidate only - never reuse a key based on its name. For each candidate run

cx iam api-keys get <id> -p <profile> -o json

and reuse it only if it is active (

keyInfo.active: true

) and

keyInfo.keyPermissions

has

SendRUMData

as its only preset and no other permissions (or

rum-ingress:SendData

as its only permission). Skip inactive keys - the SDK can't send with them. The value is in

keyInfo.value

(returned for unhashed keys - a hashed key can't be reused, create a new one).

Create one if none exists. This is a write - describe it to the user and get approval before passing

--yes

(same rules as

cx-platform-admin

bash

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

: read

cached_team_id

from the step-2 profile's file

~/.cx/profiles/<profile>.toml

(written by

cx init

), or the

owner.teamId

of any key in

cx iam api-keys list -o json

, or ask the user.

```
Permission denied
```
: RUM keys are Send-Your-Data (data-ingest) keys, so they need the
```
DATA-INGEST-API-KEYS
```
permissions, not the team custom-key ones:
- on
```
send-data-keys
```
  → the role lacks
```
DATA-INGEST-API-KEYS:READCONFIG
```
  (view keys);
- on
```
get
```
  or
```
create
```
  → the role lacks
```
DATA-INGEST-API-KEYS:MANAGE
```
  (
```
get
```
  needs it too, since it returns the key value).
Don't retry with other payloads. Tell the user which permission is missing and ask them to get it, or to create it in Settings → API Keys - key type Send Your Data Key, role preset SendRUMData
only (or have an admin do it), then continue from step 4 with the key value.
```
hashed: false
```
keeps the key value retrievable later - fine for a public RUM key.
The response contains
```
value
```
- that is the
```
public_key
```
for the SDK.

RUM 密钥按设计就是公开的——它们会随客户端代码一同分发。请使用 SendRUMData
preset 创建它——这与 UI 中 RUM 流程创建的密钥相同。该 preset 仅授予一项权限

rum-ingress:SendData

，并且是独立预设：不要添加其他 preset 或权限。（也可以直接授予

rum-ingress:SendData

，但在 UI 中会显示为

CUSTOM

密钥，因此优先使用该 preset。）在 Settings → API Keys 中，RUM 密钥的类型显示为 "Send Your Data"，preset 为

SendRUMData

。不要选择
SendData
preset——它授予 logs、metrics 和 spans 摄取权限，但不包括 RUM，而且会使密钥成为 secret，而不是 public。

**优先复用。**检查是否已有 RUM 密钥：

bash

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

作为唯一 preset 且不包含其他权限（或仅包含

rum-ingress:SendData

权限）时，才可以复用。跳过未启用的密钥——SDK 无法使用它们发送数据。密钥值位于

keyInfo.value

中（仅未哈希的密钥会返回该值；哈希密钥无法复用，需要创建新密钥）。

**如果不存在，则创建一个。**这是一项写入操作——请向用户说明，并在传入

--yes

之前获得批准（规则与

cx-platform-admin

相同）。

bash

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 中 profile 的文件
```
~/.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）密钥，因此需要
```
DATA-INGEST-API-KEYS
```
权限，而不是 team custom-key 权限：
- 执行
```
send-data-keys
```
  时，表示角色缺少
```
DATA-INGEST-API-KEYS:READCONFIG
```
  （查看密钥）；
- 执行
```
get
```
  或
```
create
```
  时，表示角色缺少
```
DATA-INGEST-API-KEYS:MANAGE
```
  （
```
get
```
  也需要该权限，因为它会返回密钥值）。
不要使用其他 payload 重试。告知用户缺少哪项权限，并请其获取相应权限，或在 Settings → API Keys 中创建密钥——密钥类型为 Send Your Data Key，role preset 仅设置为 SendRUMData
（也可以让管理员创建），然后使用密钥值从步骤 4 继续操作。
```
hashed: false
```
会让密钥值以后仍可检索——对于 public RUM 密钥，这是可接受的。
响应中包含
```
value
```
——这就是 SDK 使用的
```
public_key
```
。

4. Fetch the current SDK docs

4. 获取当前 SDK 文档

SDK package names, versions, and options change - fetch them instead of guessing (see

coralogix-docs

bash

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

SDK 包名、版本和选项会发生变化——请获取最新文档，不要凭记忆猜测（参见

coralogix-docs

）：

bash

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

5. Install and initialize

5. 安装并初始化

Use the profile and

coralogixDomain

from step 2.

Browser example (confirm against the fetched docs):

bash

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

Gotchas:

Init once, as early as possible - the app entry point (
```
main.ts
```
,
```
index.tsx
```
, root layout).
Next.js: init only on the client - a
```
'use client'
```
component that calls
```
init
```
in
```
useEffect
```
, rendered from the root layout. Never in server components.
Env vars: keep the key in env config (
```
NEXT_PUBLIC_*
```
,
```
VITE_*
```
,
```
REACT_APP_*
```
), not hard-coded. It is public, but env config makes rotation easy.
version
should match the release - source maps and release comparison rely on it.
Source maps (optional) are uploaded with
```
coralogix-rum-cli
```
and need a separate key - in the UI, key type Team Key with role preset SourceMapping
(
```
source-mapping:ReadMapping
```
+
```
UploadMapping
```
) - never reuse the RUM key, and keep this one secret (CI only, not in client code). See
```
cx docs fetch user-guides/rum/cli/rum-cli.md
```
(search doesn't surface it).

使用步骤 2 中确定的 profile 和

coralogixDomain

。

Browser 示例（请根据获取到的文档进行确认）：

bash

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

注意事项：

仅初始化一次，并尽早执行——应在应用入口处调用（
```
main.ts
```
、
```
index.tsx
```
、根布局）。
**Next.js：**仅在客户端初始化——使用带有
```
'use client'
```
的组件，在
```
useEffect
```
中调用
```
init
```
，并从根布局渲染该组件。绝不要在 Server Component 中调用。
**环境变量：**将密钥保存在环境配置中（
```
NEXT_PUBLIC_*
```
、
```
VITE_*
```
、
```
REACT_APP_*
```
），不要硬编码。虽然该密钥是 public，但环境配置便于轮换。
version
应与发布版本一致——Source maps 和版本对比都依赖它。
Source maps（可选）通过
```
coralogix-rum-cli
```
上传，并且需要一个单独的密钥——在 UI 中，密钥类型为 Team Key，role preset 为 SourceMapping
（
```
source-mapping:ReadMapping
```
+
```
UploadMapping
```
）——绝不要复用 RUM 密钥，并且该密钥必须保密（仅用于 CI，不能放入客户端代码）。参见
```
cx docs fetch user-guides/rum/cli/rum-cli.md
```
（搜索无法找到此文档）。

6. Verify data arrives (optional)

6. 验证数据到达（可选）

Setup is done once the key exists and

init

is in place - data only flows after the app runs and users hit it, and the SDK sends in batches. Give the user this query to run later, or run it now if they load the app:

bash

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

No rows? Check the browser network tab for requests to the RUM ingress endpoint. Ad blockers, a wrong

coralogixDomain

, or a key with extra permissions are the usual causes.

密钥存在且

init

已正确放置后，配置即告完成——只有在应用运行且用户访问后，数据才会开始流动，并且 SDK 会批量发送。可以将以下查询留给用户稍后运行，也可以在用户加载应用时立即运行：

bash

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

没有数据行？检查 browser 网络面板中是否有发往 RUM ingress endpoint 的请求。广告拦截器、错误的

coralogixDomain

，或包含额外权限的密钥通常会导致此问题。

Key Principles

关键原则

RUM key =
SendRUMData
preset only - nothing else on the key
Reuse before create, and never pass
```
--yes
```
without user approval
Fetch SDK docs per platform with
```
cx docs
```
- don't hard-code versions or options from memory
Client-side init only, once, at the app entry point
Done = key + init in place - hand over the
```
rum.events
```
query for checking data later

RUM 密钥只能使用
SendRUMData
preset——不要添加任何其他内容
先复用，再创建，未经用户批准绝不传入
```
--yes
```
使用
```
cx docs
```
按平台获取 SDK 文档——不要凭记忆硬编码版本或选项
仅在客户端初始化，只执行一次，并放在应用入口处
完成标准 = 密钥已就绪 +
init
已就位——交付
```
rum.events
```
查询，供用户稍后检查数据

cx-rum-setup

Original

Translation

RUM Setup Skill

RUM 配置 Skill

CLI Commands

CLI 命令

Workflow

工作流

1. Detect the platform

1. 检测平台

2. Pick the profile - before any key operation

2. 选择 profile——在执行任何密钥操作之前

3. Get a RUM API key

3. 获取 RUM API key

4. Fetch the current SDK docs

4. 获取当前 SDK 文档

5. Install and initialize

5. 安装并初始化

6. Verify data arrives (optional)

6. 验证数据到达（可选）

Key Principles

关键原则

Related Skills

相关 Skills