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	包含浏览器信号的 package.json——react-dom、vue、@angular/core、svelte、浏览器打包工具（vite、webpack、parcel）或 index.html 入口文件	浏览器 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，并且是独立的：切勿添加其他预设或权限。（直接授予 rum-ingress:SendData 也可行，但在 UI 中会显示为 CUSTOM 密钥，因此最好使用该预设。）在“设置 → API 密钥”中，RUM 密钥的类型显示为“发送您的数据”，预设为 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 步配置文件中的 cached_team_id 读取，文件路径为 ~/.cx/profiles/<profile>.toml（由 cx init 写入）；也可以从 cx iam api-keys list -o json 中任意一个密钥的 owner.teamId 读取，或询问用户。

• Permission denied：RUM 密钥属于“发送您的数据”（数据摄取）密钥，因此需要 DATA-INGEST-API-KEYS 权限，而不是团队自定义密钥的权限：

  • 执行 send-data-keys 时 → 角色缺少 DATA-INGEST-API-KEYS:READCONFIG（查看密钥）；
  • 执行 get 或 create 时 → 角色缺少 DATA-INGEST-API-KEYS:MANAGE（get 也需要该权限，因为它会返回密钥值）。

  不要尝试使用其他载荷重试。告知用户缺少哪项权限，并请他们获取该权限；或者请他们在设置 → API 密钥中创建密钥——密钥类型为发送您的数据密钥，角色预设仅选择 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>',
});

注意事项：

• 只初始化一次，并尽可能早地初始化——在应用入口点（main.ts、index.tsx、根布局）进行。
• **Next.js：**仅在客户端初始化——使用一个调用 init 的 'use client' 组件，并在 useEffect 中调用，然后从根布局中渲染。绝不要在服务器组件中初始化。
• **环境变量：**将密钥保存在环境配置中（NEXT_PUBLIC_*、VITE_*、REACT_APP_*），不要硬编码。密钥是公开的，但使用环境配置便于轮换。
• version 应与发布版本一致——源代码映射和版本对比依赖它。
• 源代码映射（可选）通过 coralogix-rum-cli 上传，并且需要单独的密钥——在 UI 中，密钥类型为团队密钥，角色预设为 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
• 按平台获取 SDK 文档，使用 cx docs——不要凭记忆硬编码版本或选项
• 仅在客户端初始化，并且只在应用入口点初始化一次
• 完成 = 密钥 + 已就位的 init——提供 rum.events 查询，以便稍后检查数据

---

相关技能

• cx-platform-admin——通用 API 密钥管理
• coralogix-docs——获取特定平台的 SDK 文档
• cx-telemetry-querying——数据开始流动后查询 RUM 数据