kubesense-rum

KubeSense RUM

需要 KubeSense MCP 服务；有关连接、身份验证和通用 WHERE 子句参考，请参阅 kubesense-mcp。RUM 查询会针对 RUM 模块解析 RBAC（rbac(rum)）。没有此权限的密钥会报错：rbac(rum): this API key does not have access to this resource；请申请 RUM 权限，而不是重试。search-rum 也需要相同的权限。它读取的 RUM 列表路由也需要此权限（POST /rum/explorer/{sessions,views,actions,errors,resources,longtasks}），这些路由同样会保护 RUM 页面。

信号

RUM 有六种信号，每种对应一种事件类型。每种信号读取自己的表。

信号	每一行代表	常见问题
rum_session	一个用户会话	会话数是多少，有多少会话发生了错误
rum_view	一个已结束的页面或屏幕视图	LCP、加载时间、每个页面的视图数
rum_action	一次点击、轻触或滚动	哪些操作缓慢或令人沮丧
rum_error	一条捕获到的错误或崩溃记录	有哪些错误，发生了多少次崩溃
rum_resource	一次 HTTP 或资源请求	按主机查看缓慢或失败的请求
rum_long_task	一个主线程长任务	哪些因素阻塞了 UI

rum_view 只统计非系统会话中已结束的视图。每一行都根据自身的 start_timestamp 确定时间，因此，长会话会计入其开始的时间窗口。

工具

工具	适用场景	说明
get-fields（signal: "rum_view"，…）	始终先调用	获取该事件类型的字段目录
analyze-telemetry	计数、比率、百分位数、趋势	每种信号使用一个子查询，通过 selectedMode 设置
search-rum	读取单个会话、错误、请求	获取单种信号的原始行；参见 search-rum

没有 analyze-rum。analyze-logs 和 analyze-traces 不接受 RUM 信号。若要将 RUM 与日志或追踪进行比较，或计算比率，请在一次 analyze-telemetry 调用中加入多个子查询并添加公式；参见 multi-query。

先探索

使用要查询的信号调用 get-fields。不同事件类型的字段集合各不相同：lcp 仅存在于 rum_view 中，error_type 仅存在于 rum_error 中；view_name 在 rum_view 中支持 LIKE，但在其他类型中不支持。每种事件类型的完整目录见 references/field-catalog.md；调用前可用它检查字段名称，并以 get-fields 返回的结果为准，确认你所连接的部署支持哪些字段。

RUM 的 get-fields 只返回静态目录，格式与通常一样，为 TSV：

• 表头行是 # signal=rum_view total_count=<N> truncated=<bool> note=RUM has no attribute-key scan; ...。没有 attribute_scan_error。备注说明自定义属性应写作 @key（属性不支持 LIKE），功能标志应写作 feature_flag.<key>。
• 运算符以集合形式返回（# ops.o1=EQ|NEQ|IN|NIN|LT|GT|LTE|GTE）。支持 LIKE 的字段，其集合包含 LIKE / ILIKE；user_email 等精确匹配字段则不包含。请以运算符集合为准，不要凭对字段的假设判断。
• 当某些字段带有备注时，会出现末尾的 notes 列。例如，lcp_ms 的备注为 filter-only: use it in WHERE only (milliseconds); aggregate the base field lcp instead; platform: browser，lcp_target_selector 的备注为 filter-only: not groupable; platform: browser。
• enum_values 中包含 severity 的 crash 和 error。
• 传入 search 可缩小列表范围（search=lcp 会返回 lcp、lcp_ms、lcp_s 和 lcp_target_selector）。

无法发现属性键。当用户需要自定义属性时，请询问其键名，或从其埋点中推断，并使用 @ 前缀书写。错误的键名不会匹配任何内容，结果为空，而不会报错。

search-rum

search-rum 会读取单个信号的原始行：也就是 Data Explorer List 面板显示的同一批行。可用它查看单个事件（哪些会话发生了崩溃、哪些请求最慢、错误文本是什么）。对于任何数值类问题，请使用 analyze-telemetry：计数、比率、百分位数和趋势。读取行来计算计数速度较慢，且会受页面上限限制。

先使用相同的 signal 调用 get-fields。where 和 required_fields 使用目录标签、属性使用 @key，标记使用 feature_flag.<key>（仅适用于 views 和 errors）。from_time、to_time 和 signal 为必填参数。没有 clusters 参数；传入该参数会被拒绝。使用 application_id = "<id>" 或 env = production 将范围限定到某个应用。

过去一小时内失败请求中最慢的 20 个，每页显示 20 个

{
  "signal": "rum_resource",
  "from_time": "2026-10-20T10:00:00Z",
  "to_time": "2026-10-20T11:00:00Z",
  "where": "status_code >= 500",
  "sort_by": "duration_ms",
  "sort_order": "desc",
  "page_size": 20
}

除通用搜索参数外，可用的参数还有：sort_by（目录标签；默认为 start_timestamp）、sort_order（asc 或 desc，默认为 desc）和 cursor。required_fields 用于选择列；留空时使用对应类型的默认列。

信号	默认列
rum_session	start_timestamp、session_type、time_spent_ms、view_count、error_count、action_count、frustration_count、first_view_name、last_view_name
rum_view	start_timestamp、view_name、frustration_count、loading_type、loading_time_ms、view_time_spent_ms、country、browser_name
rum_action	start_timestamp、action_type、action_name、frustration_type、view_name
rum_error	start_timestamp、view_name、error_source、error_message
rum_resource	start_timestamp、view_name、resource_url、duration_ms、response_size、status_code、resource_type
rum_long_task	start_timestamp、duration_ms、view_name

默认列使用 _ms 对应字段。按名称请求原始时长（duration）时，返回值的单位是纳秒；请改为请求 duration_ms 或 duration_s。

输出为 TSV。第一行是 # total_count=unknown returned_rows=<N> truncated=<bool> next_cursor=<c> window_clamped=<bool> ...， 随后是需要说明情况时出现的 # notice=<n> 行、表头，以及每行一条记录。每条记录还包含 application_id、session_id、row_id（事件自身的 ID）、timestamp、has_replay（会话有已存储的回放时设置）和 severity（错误记录为 error 或 crash）。无论你请求哪些 required_fields，每条记录都会包含用于标识该记录的列，这些列始终存在：sessions 包含 application_id、session_id、session_start、session_has_replay；views 还包含 view_id、view_start；actions 还包含 action_id、action_start；errors 还包含 error_id、error_start、is_crash；resources 还包含 resource_id、resource_start；long tasks 还包含 task_id、task_start（除 sessions 外，每种类型都包含 view_id）。

分页。 没有总数（total_count=unknown）。只要 next_cursor 非空，就使用相同的 from_time、to_time、where、sort_by、sort_order、page_size 和 required_fields 再次调用，并设置 cursor=<next_cursor>。cursor 是绑定到查询的页面令牌，因此在不同查询中重放 cursor 会被拒绝。

• 分页按页进行，所有 sort_by 都没有深度限制。没有 keyset。
• page_size 默认为 10，最大为 200。Data Explorer List 面板每页加载 50 条记录。

一条记录代表什么

• 行与 RUM 页面表格一致。会话和视图已去重。会列出仍处于打开状态的实时视图。
• 操作、错误、资源和长任务按 ID 分组：每个 ID 一行，开始时间为首次出现时间，资源时长为中位数，长任务时长为平均值。
• rum_error 仅列出错误（type = 3）。
• Blob 字段无法列出或排序：error_stack、handling_stack、threads、graphql、display、tags。
• 数组字段（service、state、city、network_connectivity、ip、action_id）无法排序。
• TSV 输出中的每个单元格最多截取 2048 字节。列表 API 本身不会截断字符串。

时间窗口。 时间窗口会根据 RUM 数据窗口进行限制并对齐。若 from_time 早于原始数据保留期限（会话和视图为 30 天，其余数据为 7 天），则会将其移至保留期限的起点，并将时间窗口扩展到 RUM 数据的时间桶边界。窗口发生变化时，标头会显示 window_clamped=true。完全早于保留期限的窗口将按请求保持不变。

无读取预算错误。 列表读取不受读取预算限制。读取仍可能超时；请缩短时间窗口，或按 application_id、env 或 session_id 筛选。

WHERE 语法

适用 kubesense-mcp 中的通用语法，字段名称使用 RUM 目录中的名称。

env = production AND browser_name = Chrome
severity = crash AND country IN (US, DE)
view_name ILIKE "%checkout%"                    (rum_view only)
lcp_ms > 2500 AND browser_name = Chrome         (rum_view)
status_code >= 500 AND resource_host = api.example.com   (rum_resource)
error_count > 0                                 (rum_session)
feature_flag.new_checkout = true                (any event type)
@checkout.step = payment                        (attribute)

包含 /、:、% 或空格的值需加引号。请写成 NOT (x IN (...))，而不要写成 x NOT IN (...)。

规则

1. 仅当目录中字段的 LIKE 列标为 yes 时，才可对其使用 LIKE 和 ILIKE。 这些是低基数列（env、country、error_type、action_name、 rum_view 上的 view_name）。其他所有字段（user_id、view_url、resource_url、 error_message、其他事件类型上的 view_name）都使用 = 和 IN。对这些字段使用 LIKE 会被拒绝，并提示 LIKE is not supported on <field>; use = or IN。
2. 不得对 @attribute 字段使用 LIKE。 属性支持 =、!=、IN、<、>、<= 和 >=。比较时需要数字。使用 @plan LIKE ... 会被拒绝，并提示 operator "LIKE" not allowed for rum_view attribute field "plan"。
3. 数组字段只能用于筛选。 rum_session 上的 service、state、city、 network_connectivity 和 ip，rum_view 上的 ip，以及 rum_error、 rum_resource 和 rum_long_task 上的 action_id 都存储列表。= 和 IN 用于测试成员关系。 这些字段不能用于分组或度量。
4. 时长的单位是纳秒。 原始列（lcp、duration、loading_time、time_spent 等） 以纳秒存储并返回，且不能用作分组字段。每个字段都有对应的 _ms 和 _s 版本 （lcp_ms、duration_s），但它们只能用于筛选：在 where 中使用 （lcp_ms > 2500 会筛选出 2.5 秒的时长），绝不能用作聚合字段、分组字段或列表列。 要聚合时长，请使用基础字段（例如对 lcp 使用 p75）；结果单位为纳秒。
5. 自由搜索 ID 和文本的 group-by 为 no（session_id、view_id、 trace_id 等）。请改用低基数字段分组。以下 5 个字段可用于分组，并返回前 N 个分组（页大小）： error_message（按其前 200 个字符分组）、fingerprint、issue_id， 以及 view_url / resource_url（按路径分组，不含查询字符串或片段）。筛选仍会读取完整值， 因此 URL 分组标签是路径，而 view_url = "<path>" 只会匹配不含查询字符串的 URL。
6. feature_flag.<key> 可用于所有事件类型的筛选。它仅可用于 rum_view 和 rum_error 的分组或度量，因为标志值存储在对应的数据行上。其他 4 种事件类型的标志值按会话存储， 因此在这些事件类型上使用分组会被拒绝。键区分大小写，值为文本（true、dark、5）。 已在 rum_view 上确认可按标志键（feature_flag.new-checkout）分组。where 形式遵循引擎源码， 尚未在实际运行的服务上测试。
7. 在 where 中使用属性时需要加 @（@checkout.step）；在 group_by_fields / fields 中使用时则通过 is_attribute: true 标记，不加 @。没有用于发现属性键的机制。
8. rum_error 上的 severity 值为小写的 crash 或 error。它是 is_crash 的标签； 应使用类型 severity，不要将 is_crash 当作字符串。
9. 布尔字段（session_is_active、slow_rendered）接受 true 或 false。
10. 不强制执行平台专属字段限制。 lcp 仅适用于浏览器，battery_level 仅适用于移动设备。 对错误应用类型筛选这些字段时不会匹配任何内容，也不会报错。
11. value_operation 可取 row_count、unique_count、avg、sum、min、max、 p50、p75、p90、p95 或 p99。row_count 不接受字段。其他操作都必须且只能有一个 fields 条目。数值操作需要数值字段或属性；unique_count 可接受任意非列表字段。
12. RUM 不支持 alert_mode、group_by_present_only 和 lookback_seconds。

analyze-telemetry

将 selectedMode 设为信号类型。省略该参数时，子查询默认为指标查询。

每个页面的 p90 LCP，仅限 Chrome，单位为毫秒

{
  "from_time": "2026-10-20T10:00:00Z",
  "to_time": "2026-10-20T11:00:00Z",
  "query_type": "instant",
  "queries": {
    "A": {
      "selectedMode": "rum_view",
      "where": "browser_name = Chrome",
      "group_by_fields": [ { "field": "view_name", "is_attribute": false } ],
      "value_operation": "p90",
      "fields": [ { "field": "lcp", "is_attribute": false } ],
      "sort_direction": "DESC",
      "limit": 10
    }
  }
}

按错误类型统计每小时崩溃次数

{
  "from_time": "2026-10-20T00:00:00Z",
  "to_time": "2026-10-21T00:00:00Z",
  "query_type": "range",
  "queries": {
    "A": {
      "selectedMode": "rum_error",
      "where": "severity = crash AND env = production",
      "group_by_fields": [ { "field": "error_type", "is_attribute": false } ],
      "value_operation": "row_count"
    }
  }
}

发生错误的会话占比 — 两个查询和一个公式，均不分组：

{
  "from_time": "2026-10-20T10:00:00Z",
  "to_time": "2026-10-20T11:00:00Z",
  "query_type": "instant",
  "queries": {
    "A": { "selectedMode": "rum_session", "value_operation": "row_count" },
    "B": { "selectedMode": "rum_session", "where": "error_count > 0", "value_operation": "row_count" },
    "C": { "query_type": "formula", "expression": "(B/A)*100" }
  }
}

按 p95 请求耗时排列的最慢主机，仅统计失败请求 selectedMode: rum_resource、where: "status_code >= 500"、 group_by_fields: [{"field":"resource_host"}]、value_operation: p95、 fields: [{"field":"duration"}]（纳秒）

按功能标志值统计错误 selectedMode: rum_error、group_by_fields: [{"field":"feature_flag.new_checkout"}]、 value_operation: row_count

按自定义属性统计会话数 selectedMode: rum_session、group_by_fields: [{"field":"checkout.step","is_attribute":true}]、 where: "@checkout.step IN (cart, payment)"

仪表板面板

存储的面板查询和 analyze 调用对事件类型的命名方式不同：

	字段	值
analyze-telemetry 子查询	selectedMode	rum_view
仪表板面板查询	selectedMode + rumEventType	"rum" + "view"

设置为 selectedMode: "rum_view" 的面板无法通过验证，而不带 rumEventType 的 "rum" 会在保存时被拒绝。面板结构以及带 _ms 的度量值和对应单位，见 kubesense-dashboards。先用 analyze-telemetry 测试查询，再将其转换为面板查询。

常见 RUM 问题的面板配置示例（独立用户数、无崩溃用户数、Web Vitals 良好/较差占比、Apdex、热门错误和 URL、ANR 率）见 references/dashboard-recipes.md。

限制

• 数据保留期限。 默认情况下，原始 RUM 行数据的保留期限为：rum_action、 rum_error、rum_resource 和 rum_long_task 为 7 天；rum_session 和 rum_view 为 30 天。查询更长时间范围时，只会返回仍然存储的数据（search-rum 会报告 window_clamped=true）；部署可以更改数据保留期限。
• 每次调用的行读取数量有限。 search-rum 每次调用最多返回 200 行，且不提供总数。 分页没有深度限制。对于答案为数字的问题，请改用聚合查询。
• 不支持告警、SQL 或 SPL。 RUM 不能作为告警规则、execute-sql 或 execute-spl 的数据源。请如实说明，而不要尝试用日志近似替代。
• 无法发现属性键。 参见“先发现”。

错误消息

从运行中的服务观察到：

消息	原因
unknown field "services" for signal=rum_session ...	使用了存储名称；请使用目录名称（service）
analysis failed: cannot group by lcp_ms	规则 4：_ms / _s 双字段仅可用于筛选；请聚合基础字段
analysis failed: LIKE is not supported on user_email; use = or IN	规则 1
operator "LIKE" not allowed for rum_view attribute field "plan" — use one of: EQ, NEQ, ...	规则 2
rbac(rum): this API key does not have access to this resource	此密钥没有 RUM 模块的访问权限

根据 kubeapi 源代码措辞，未在运行中观察到：

消息	原因
<field> is not a filterable field for <type>	该字段属于其他事件类型，或处于隐藏状态
<field> holds a list and cannot be grouped or measured; filter on it instead	规则 3
cannot group by <field>; it is a duration in nanoseconds	规则 4，适用于 lcp 等原始列
cannot group by <field>	规则 5
feature flags are stored per session for <type>; filter on them instead	规则 6
<op> needs a numeric field; <field> is not numeric	对字符串或布尔值进行度量
rum is not configured	此部署没有 RUM 数据库