@blueking/open-telemetry 0.0.32 → 0.0.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +20 -19
  2. package/dist/bk-rum.global.js +2 -2
  3. package/dist/bk-rum.global.js.map +1 -1
  4. package/dist/core/plugin.d.ts +3 -0
  5. package/dist/index.js +507 -356
  6. package/dist/index.js.map +1 -1
  7. package/dist/plugins/resource.d.ts +11 -0
  8. package/dist/plugins/web-vitals.d.ts +1 -1
  9. package/dist/schema/attributes.d.ts +19 -0
  10. package/dist/schema/span.d.ts +10 -0
  11. package/package.json +1 -1
  12. package/skills/bk-rum-otele/SKILL.md +1 -1
  13. package/skills/bk-rum-otele/evals/evals.json +1 -1
  14. package/skills/bk-rum-otele/references/actions.md +3 -3
  15. package/skills/bk-rum-otele/references/api.md +3 -3
  16. package/skills/bk-rum-otele/references/architecture.md +2 -2
  17. package/skills/bk-rum-otele/references/blank-screen.md +2 -2
  18. package/skills/bk-rum-otele/references/capabilities.md +17 -17
  19. package/skills/bk-rum-otele/references/configuration.md +1 -1
  20. package/skills/bk-rum-otele/references/data-model.md +3 -3
  21. package/skills/bk-rum-otele/references/errors-security.md +4 -4
  22. package/skills/bk-rum-otele/references/getting-started.md +3 -2
  23. package/skills/bk-rum-otele/references/network.md +5 -5
  24. package/skills/bk-rum-otele/references/performance.md +2 -2
  25. package/skills/bk-rum-otele/references/session-context.md +3 -3
  26. package/skills/bk-rum-otele/references/span-protocol.md +333 -239
  27. package/skills/bk-rum-otele/references/telemetry-reference.md +36 -33
  28. package/skills/bk-rum-otele/references/transport-sampling.md +2 -2
  29. package/skills/bk-rum-otele/references/troubleshooting.md +3 -3
  30. package/skills/bk-rum-otele/references/views-routing.md +4 -4
package/skills/bk-rum-otele/references/telemetry-reference.md CHANGED
@@ -32,7 +32,7 @@
32
32
  字段存在不等于 Span 一定会被导出。当前采集链路依次受以下条件约束：
33
33
 
34
34
  1. SDK 必须启用、获得采集授权，并且当前 Session 命中确定性采样。
35
- 2. 普通 Span 导出时必须同时具备有效的 `session.id` 和 `view.id`；`browser.session` 是唯一例外，它允许没有 View，但仍必须属于已采样 Session。
35
+ 2. 普通 Span 导出时必须同时具备有效的 `session.id` 和 `view.id`；`span_type=session` 是唯一例外，它允许没有 View，但仍必须属于已采样 Session。
36
36
  3. 指向 SDK Collector 自身的请求会被过滤；请求级 `tracking.request.beforeSend` 和全局 `tracking.beforeSend` 返回 `false` 时也会丢弃 Span。
37
37
 
38
38
  因此，插件已开启但没有数据时，应先检查授权、`session.sample_rate`、Session/View 是否已建立、浏览器能力和 beforeSend 过滤，而不是只检查字段解析。
@@ -53,8 +53,8 @@
53
53
  | `traceId` | 32 位十六进制字符串 | 必有 | 16 字节 Trace ID。同一条调用链上的 Span 使用同一个值。注意注入到后端的 `traceparent` 使用的是另一个独立 trace-id，不等于本字段，两者通过 `links` 关联。 |
54
54
  | `spanId` | 16 位十六进制字符串 | 必有 | 当前 Span 的 8 字节唯一 ID，与 `traceId` 一起唯一定位本次 Span。 |
55
55
  | `parentSpanId` | 16 位十六进制字符串 | 有活动父 Span 时 | 父 Span ID。没有活动父上下文的 RUM 根 Span不包含该字段；缺失不代表数据异常。 |
56
- | `links` | link[] | 注入或探测到 Trace Header 时 | 关联的其他 Trace。`browser.resource` Span 用它指向本次请求对应的后端 Trace，每项含 `traceId`、`spanId`、`traceFlags`。后端可按 `link.trace_id` 反查 RUM Span。 |
57
- | `name` | string | 必有 | Span 名称，例如 `browser.view`、`browser.resource`。稳定一级分类使用 `span_type`，具体类别使用各领域字段查询。 |
56
+ | `links` | link[] | 注入或探测到 Trace Header 时 | 关联的其他 Trace。Resource Span 用它指向本次请求对应的后端 Trace，每项含 `traceId`、`spanId`、`traceFlags`。后端可按 `link.trace_id` 反查 RUM Span。 |
57
+ | `name` | string | 必有 | 可读的低基数 Span 名称。SDK 根据 `span_type` 和领域字段生成，稳定一级分类仍使用 `span_type` 查询。 |
58
58
  | `kind` | enum number/string | 必有 | OpenTelemetry Span Kind。SDK 内置值为 `INTERNAL` 或 `CLIENT`；不同 OTLP JSON 实现可能编码为枚举数字或名称。 |
59
59
  | `startTimeUnixNano` | epoch ns 字符串 | 必有 | Span 开始时间。OTLP JSON 使用十进制字符串保存纳秒整数，避免 JavaScript Number 精度丢失。 |
60
60
  | `endTimeUnixNano` | epoch ns 字符串 | 必有 | Span 结束时间。瞬时生命周期事件通常与开始时间相同；Resource Span 的差值表示请求或资源加载耗时。 |
@@ -92,7 +92,7 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
92
92
  | `session.type` | string | Session 有效 | 当前固定为 `user`，为未来区分其他 Session 类型保留。 |
93
93
  | `session.has_replay` | boolean | Session 有效 | 当前固定为 `false`，表示 SDK 没有随该 Session 上报 Session Replay 数据。 |
94
94
  | `view.id` | string | View 有效 | 当前页面视图的关联 ID。首次加载、有效 SPA 路由变化、BFCache 恢复或 Session 续建都会创建新 View。 |
95
- | `view.name` | string | 显式命名后 | 业务给出的可读名称，仅在 `startView({ name })` 或 `setViewName()` 调用后存在。默认不上报，展示请用 `view.name ?? view.url_template`。 |
95
+ | `view.name` | string | View 有效期内 | 视图名称优先使用 `startView({ name })` 或 `setViewName()` 的显式值，未设置时取 `view.url_template`。 |
96
96
  | `view.url` | string | View 有效 | 创建 View 时的完整 URL，经 `redactUrl` 脱敏。与当前实时 `location.href` 不一定相同。 |
97
97
  | `view.url_template` | string | View 有效 | 低基数路由模板。默认把数字 ID、UUID 和长十六进制路径段归一为 `:id`，也可由 `getUrlTemplate` 自定义。 |
98
98
  | `view.loading_type` | string | View 有效 | View 创建类型：`initial_load` 首次文档加载、`route_change` SPA 路由、`bf_cache` BFCache 恢复、`session_renewal` Session 到期后续建。 |
@@ -121,24 +121,26 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
121
121
 
122
122
  | Span 名 | Kind | `span_type` | 领域分类字段 | 默认状态/入口 | 表达的事件 |
123
123
  | ---------------------------- | -------- | ----------- | --------------------------------- | --------------------------------- | -------------------------------------------------- |
124
- | `browser.session` | INTERNAL | `session` | `session.phase` | 始终随 SDK 启动 | Session 创建、轮换和结束生命周期。 |
125
- | `browser.view` | INTERNAL | `view` | `view.phase` | 自动；可切为手动 View | 初始页面或 SPA View 的 start/update/end 快照。 |
126
- | `browser.resource` | CLIENT | `resource` | `resource.type` | 请求、静态资源默认开启 | Fetch、XHR 或静态资源加载。 |
127
- | `browser.error` | INTERNAL | `error` | `error.source=window.error` | 错误采集默认开启 | `window.error` 捕获的 JavaScript 运行时错误。 |
128
- | `browser.unhandledrejection` | INTERNAL | `error` | `error.source=unhandledrejection` | 错误采集默认开启 | 未处理的 Promise rejection。 |
129
- | `browser.resource_error` | INTERNAL | `error` | `error.source=resource` | 错误采集默认开启 | script、img、link、media 等元素资源加载失败。 |
130
- | `browser.web_vital` | INTERNAL | `vital` | `vital.metric` | 默认开启 | 单项用户体验指标及归因。 |
131
- | `action.click` | INTERNAL | `action` | `action.type=click` | 自动 Action 默认开启 | 自动点击 Action 及其页面活动、错误和挫败归因。 |
132
- | `action.<name>` | INTERNAL | `action` | `action.type=custom` | `reportAction({ name })` | 主动上报的业务 Action；Span 名是 `action.` 加上业务 name。 |
133
- | `browser.blank_screen` | INTERNAL | `error` | `blank_screen.reason` | 默认开启 | 视口九宫格连续检测确认的白屏。 |
134
- | `browser.long_task` | INTERNAL | `long_task` | `long_task.entry_type` | `tracking.longTask`，默认关闭 | Long Animation Frame，或不支持时回退的 Long Task。 |
135
- | `csp.violation` | INTERNAL | `error` | `error.source=csp` | `tracking.cspViolation`，默认关闭 | 浏览器 `securitypolicyviolation` 事件。 |
136
- | `browser.websocket` | CLIENT | `websocket` | `websocket.phase` | `tracking.websocket`，默认关闭 | 同一 WebSocket 连接的四类生命周期事件。 |
124
+ | `session.<phase>` | INTERNAL | `session` | `session.phase` | 始终随 SDK 启动 | Session 创建、轮换和结束生命周期。 |
125
+ | `<view.name>` | INTERNAL | `view` | `view.phase` | 自动；可切为手动 View | 初始页面或 SPA View 的 start/update/end 快照。 |
126
+ | `<method> <url.template>` | CLIENT | `resource` | `resource.type` | 请求、静态资源默认开启 | Fetch、XHR 或静态资源加载。 |
127
+ | `<exception.type>` | INTERNAL | `error` | `error.source=window.error` | 错误采集默认开启 | `window.error` 捕获的 JavaScript 运行时错误。 |
128
+ | `<exception.type>` | INTERNAL | `error` | `error.source=unhandledrejection` | 错误采集默认开启 | 未处理的 Promise rejection。 |
129
+ | `ResourceError` | INTERNAL | `error` | `error.source=resource` | 错误采集默认开启 | script、img、link、media 等元素资源加载失败。 |
130
+ | `<VITAL_METRIC>` | INTERNAL | `vital` | `vital.metric` | 默认开启 | 单项用户体验指标及归因。 |
131
+ | `click <target>` | INTERNAL | `action` | `action.type=click` | 自动 Action 默认开启 | 自动点击 Action 及其页面活动、错误和挫败归因。 |
132
+ | `<action.name>` | INTERNAL | `action` | `action.type=custom` | `reportAction({ name })` | 主动上报的业务 Action；Span 名使用业务提供的 `action.name`。 |
133
+ | `blank_screen.<reason>` | INTERNAL | `error` | `blank_screen.reason` | 默认开启 | 视口九宫格连续检测确认的白屏。 |
134
+ | `<long_task.entry_type>` | INTERNAL | `long_task` | `long_task.entry_type` | `tracking.longTask`，默认关闭 | Long Animation Frame，或不支持时回退的 Long Task。 |
135
+ | `csp.<effective_directive>` | INTERNAL | `error` | `error.source=csp` | `tracking.cspViolation`，默认关闭 | 浏览器 `securitypolicyviolation` 事件。 |
136
+ | `websocket.<phase>` | CLIENT | `websocket` | `websocket.phase` | `tracking.websocket`，默认关闭 | 同一 WebSocket 连接的四类生命周期事件。 |
137
137
  | `custom.<name>` | INTERNAL | `custom` | Span 名 | `reportCustomEvent` | 主动上报的业务事件。 |
138
138
 
139
+ Span 名只使用领域分类字段和业务提供的稳定名称。唯一 ID、完整 URL、错误消息、时间戳和数值不参与命名。
140
+
139
141
  ## Session 字段
140
142
 
141
- 适用于 `browser.session`。Session 默认在 15 分钟无活动后过期，并受 4 小时最大生命周期限制。
143
+ 适用于 `span_type=session`。Session 默认在 15 分钟无活动后过期，并受 4 小时最大生命周期限制。
142
144
 
143
145
  | 字段 | 类型 | 条件/取值 | 来源与详细说明 |
144
146
  | -------------------- | ------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
@@ -151,7 +153,7 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
151
153
 
152
154
  ## View 字段
153
155
 
154
- 适用于 `browser.view`。同一 View 会产生多条版本递增的生命周期快照，而不是一条持续到页面离开的长 Span。
156
+ 适用于 `span_type=view`。同一 View 会产生多条版本递增的生命周期快照，而不是一条持续到页面离开的长 Span。
155
157
 
156
158
  | 字段 | 类型 | 条件/单位 | 来源与详细说明 |
157
159
  | -------------------------- | ------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
@@ -159,7 +161,7 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
159
161
  | `view.id` | string | 所有阶段 | View 关联 ID。同一 View 的 start/update/end 使用相同值，可与该 View 内其他 Span 关联。 |
160
162
  | `view.version` | number | 从 1 递增 | 每次 `emitViewEvent` 递增；用于恢复同一 View 生命周期快照的先后顺序。 |
161
163
  | `view.started_at` | number | epoch ms | View 开始时间。初始 View 使用 `performance.timeOrigin`，路由/BFCache/续建 View 使用创建时刻。 |
162
- | `view.name` | string | 显式命名后 | 业务可读名称，仅 `startView({ name })` 或 `setViewName()` 后存在；未命名的 View 不带该字段。 |
164
+ | `view.name` | string | View 有效期内 | 优先使用 `startView({ name })` 或 `setViewName()` 的显式值，未设置时取 `view.url_template`。 |
163
165
  | `view.url` | string | 所有阶段 | 创建 View 时的 URL，经 `redactUrl` 脱敏；在该 View 生命周期内保持不变。 |
164
166
  | `view.url_template` | string | 所有阶段 | 当前 URL 的低基数路由模板。数字 ID、UUID、长十六进制段默认折叠为 `:id`，用于稳定聚合动态路由。 |
165
167
  | `view.previous_url_template` | string | 所有阶段 | 前序 URL 的低基数路由模板；使用 `tracking.view.getUrlTemplate` 生成，初始 View 为空字符串。 |
@@ -179,7 +181,7 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
179
181
 
180
182
  ## 请求与静态资源字段
181
183
 
182
- 适用于 `browser.resource`。Fetch/XHR 由请求插件建 Span，再合并匹配的 Resource Timing；静态资源由 Resource Observer 直接建 Span。
184
+ 适用于 `span_type=resource`。Fetch/XHR 由请求插件建 Span，再合并匹配的 Resource Timing；静态资源由 Resource Observer 直接建 Span。
183
185
 
184
186
  | 字段 | 类型 | 条件/单位 | 来源与详细说明 |
185
187
  | --------------------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -188,7 +190,7 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
188
190
  | `server.address` | string | URL 可解析 | URL 的 `hostname`，不含端口。相对 URL 会基于当前页面地址解析。模板不含 host，跨域同路径会聚到一起，需要区分来源时配合该字段。 |
189
191
  | `server.port` | number | URL 显式包含端口 | URL 的显式端口号。使用协议默认端口且 URL 未写端口时缺失。 |
190
192
  | `resource.type` | string | 必有 | Fetch/XHR 为 `fetch`/`xhr`；静态资源使用 `PerformanceResourceTiming.initiatorType`，为空时为 `other`，常见还有 `script`、`link`、`img`、`css`。 |
191
- | `http.request.method` | string | Fetch/XHR | 归一为大写的 HTTP 方法，例如 `GET`、`POST`。静态资源通常没有可用的请求方法，因此缺失。 |
193
+ | `http.request.method` | string | 所有 Resource | Fetch/XHR 归一为实际的大写 HTTP 方法；其他 Resource 固定为 `GET`。 |
192
194
  | `http.response.status_code` | number | 获得真实 HTTP Response | HTTP 响应状态，只写大于 `0` 的有效状态码。abort、timeout、网络失败和 opaque Response 没有可用状态码时缺失，不使用 `0` 代替。 |
193
195
  | `resource.size` | number | 有 Resource Timing 详情 | `decodedBodySize`，解压后响应体大小，单位 bytes，不含响应头；缓存命中也能反映真实体积。Fetch/XHR 合并 Resource Timing 后同样会带上。 |
194
196
  | `resource.protocol` | string | 浏览器提供 `nextHopProtocol` | 实际传输协议，例如 `h2`、`h3`、`http/1.1`；浏览器无法判断时可能返回空字符串。 |
@@ -243,14 +245,14 @@ Link 的 `trace_id` / `span_id` 优先取自解析结果；`sw8` 这类无法映
243
245
  | `error.message` | string | 三类自动错误 | 归一后的错误消息。Error 使用 `message`，字符串直接使用，其他值优先 JSON 序列化，失败时转为字符串。资源加载错误消息会包含资源原始 URL，应使用 `redactAttributes` 做额外脱敏。 |
244
246
  | `error.handled` | boolean | 三类自动错误 | 当前自动采集固定为 `false`，表示该错误来自未处理的全局错误入口；不代表业务代码完全没有 try/catch。 |
245
247
  | `error.source` | string | 三类自动错误/CSP | `window.error`、`unhandledrejection`、`resource`；CSP Span 固定为 `csp`。用于区分采集入口。 |
246
- | `code.filepath` | string | `browser.error` | `ErrorEvent.filename`，即浏览器报告的脚本文件地址。浏览器未提供或跨域屏蔽时可能为空。 |
247
- | `code.lineno` | number | `browser.error` | `ErrorEvent.lineno`，错误在脚本中的 1-based 行号；浏览器无法定位时可能为 `0`。 |
248
- | `code.column` | number | `browser.error` | `ErrorEvent.colno`，错误列号；具体是否 0-based 由浏览器实现决定。 |
249
- | `url.full` | string | `browser.resource_error` | 加载失败元素的 `src`、`href` 或 `currentSrc`，经 `redactUrl` 脱敏。浏览器拿不到资源地址时可能为空字符串。 |
248
+ | `code.filepath` | string | `error.source=window.error` | `ErrorEvent.filename`，即浏览器报告的脚本文件地址。浏览器未提供或跨域屏蔽时可能为空。 |
249
+ | `code.lineno` | number | `error.source=window.error` | `ErrorEvent.lineno`，错误在脚本中的 1-based 行号；浏览器无法定位时可能为 `0`。 |
250
+ | `code.column` | number | `error.source=window.error` | `ErrorEvent.colno`，错误列号；具体是否 0-based 由浏览器实现决定。 |
251
+ | `url.full` | string | `error.source=resource` | 加载失败元素的 `src`、`href` 或 `currentSrc`，经 `redactUrl` 脱敏。浏览器拿不到资源地址时可能为空字符串。 |
250
252
 
251
253
  当前 **不上报** `error.cross_origin` 或 `html.tag`。跨域脚本错误只能通过 `error.message` 为 `Script error.`、且 `code.filepath` 为空来识别。资源加载失败的元素标签只出现在 `error.message` 里（格式 `Resource load failed: <tag> <原始 URL>`），需要按标签聚合时应在服务端解析该文本。
252
254
 
253
- 注意 `browser.resource_error` 的 `error.message` 携带的是 **未脱敏** 的资源 URL（`url.full` 才是脱敏后的值）。有敏感 URL 风险时用 `redactAttributes` 重写 `error.message`。
255
+ 注意 `error.source=resource` 的 `error.message` 携带的是 **未脱敏** 的资源 URL（`url.full` 才是脱敏后的值）。有敏感 URL 风险时用 `redactAttributes` 重写 `error.message`。
254
256
 
255
257
  `context.attributes.error()` 返回的任意业务 Attribute 会合并到三类自动错误 Span，并统一经过 `redactAttributes`。字段命名和类型由接入方负责。
256
258
 
@@ -268,11 +270,11 @@ Link 的 `trace_id` / `span_id` 优先取自解析结果；`sw8` 这类无法映
268
270
 
269
271
  ## Web Vitals 字段
270
272
 
271
- `browser.web_vital` 上报 CLS、FCP、INP、LCP 和 TTFB。FCP/LCP/TTFB 由 `web-vitals/attribution` 采集导航级指标；CLS/INP 按 SDK View 边界汇总，View 结束时上报。
273
+ `span_type=vital` 上报 CLS、FCP、INP、LCP 和 TTFB。FCP/LCP/TTFB 由 `web-vitals/attribution` 采集导航级指标；CLS/INP 按 SDK View 边界汇总，View 结束时上报。
272
274
 
273
275
  | 字段 | 类型 | 条件/单位 | 来源与详细说明 |
274
276
  | -------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------- |
275
- | `vital.metric` | string | 必有 | 指标名的小写值：`cls`、`fcp`、`inp`、`lcp`、`ttfb`。用于同一 Span 名下区分指标。 |
277
+ | `vital.metric` | string | 必有 | 指标名的小写值：`cls`、`fcp`、`inp`、`lcp`、`ttfb`。Span 名使用对应的大写值。 |
276
278
  | `vital.value` | number | 必有 | 指标值。CLS 是无量纲分数；FCP、INP、LCP、TTFB 单位均为 ms。非有限值不会上报。 |
277
279
  | `vital.id` | string | 必有 | 单条 Vital 的唯一 ID。FCP/LCP/TTFB 沿用 `web-vitals` ID；按 View 汇总的 CLS/INP 由 SDK 生成。 |
278
280
 
@@ -332,15 +334,16 @@ Attribution 字段受浏览器能力和指标实现影响，缺失不代表指
332
334
  | ------------------------- | -------- | ------------------------ | -------------- | --------------------------------------------------------------------------------------------------------- |
333
335
  | `action.id` | string | 必有 | 必有 | 当前 Action 的唯一 ID。自动 Action 活动期间，其他 Span 上的同名运行时字段也是单个 string。 |
334
336
  | `action.type` | string | 固定 `click` | 固定 `custom` | 区分自动点击和 `reportAction` 主动上报。 |
337
+ | `action.name` | string | `click <target>` | payload `name` | 可读的低基数名称，也是 Span 名。自动点击目标名默认来自显式 `data-bk-action-name`，启用文本采集后才会回退到可访问名称/DOM 文本。 |
335
338
  | `action.target.name` | string | 必有 | 不写 | 自动点击提取的目标名称，最多 100 字符；默认隐私模式下未显式命名时通常为小写 tag 名。 |
336
339
  | `action.target.tag` | string | 必有 | 不写 | 实际点击目标的原始 `tagName`，SDK 转为小写。 |
337
340
  | `action.frustration.type` | string[] | 检出挫败信号时 | 不写 | 可包含 `rage_click`、`dead_click`、`error_click`；一次 Action 可同时命中多个值。 |
338
341
 
339
- 自动 Action 的可读名称不单独写成 `action.name` Attribute，而是体现在目标字段和 Span 名 `action.click` 上。手动 Action 的 Span 名为 `action.<payload.name>`，`action.type=custom`。点击后若有可观察页面活动，SDK 用 Span 的 `startTimeUnixNano`/`endTimeUnixNano` 表达持续时间，**不上报** `action.loading_time` 属性。无页面副作用时 Span 起止时间相同。
342
+ 点击后若有可观察页面活动，SDK 用 Span 的 `startTimeUnixNano`/`endTimeUnixNano` 表达持续时间，**不上报** `action.loading_time` 属性。无页面副作用时 Span 起止时间相同。
340
343
 
341
344
  `rage_click` 表示 1 秒内、100px 范围内连续至少三次点击；`dead_click` 表示点击后没有页面活动、输入、滚动或选择等反馈（链接、表单输入等会排除）；`error_click` 表示 Action 生命周期内出现错误。有错误或任一挫败信号时为 `outcome.type=warning`，具体类型只由 `action.frustration.type` 表达。
342
345
 
343
- `reportAction({ attributes })` 的业务 Attribute 会合并到该 Span，但固定分类和事件字段由 SDK 写入。业务应避免复用本页保留字段名。
346
+ `reportAction({ attributes })` 的业务 Attribute 会合并到手动 Action Span，但固定分类和事件字段由 SDK 写入。业务应避免复用本页保留字段名。
344
347
 
345
348
  ## 白屏字段
346
349
 
@@ -407,7 +410,7 @@ Legacy Long Task 的每个 attribution 条目生成一个 Event，Event 时间
407
410
 
408
411
  ## CSP 字段
409
412
 
410
- 适用于 `csp.violation`，来自浏览器 `SecurityPolicyViolationEvent`。该 Span 固定为 `span_type=error`、`outcome.type=error`、`error.source=csp`，不写 `outcome.reason`，也不设置 OTLP Status ERROR。
413
+ 适用于 `error.source=csp`，来自浏览器 `SecurityPolicyViolationEvent`。该 Span 固定为 `span_type=error`、`outcome.type=error`、`error.source=csp`，不写 `outcome.reason`，也不设置 OTLP Status ERROR。
411
414
 
412
415
  | 字段 | 类型 | 条件 | 来源与详细说明 |
413
416
  | ------------------------- | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -476,7 +479,7 @@ Legacy Long Task 的每个 attribution 条目生成一个 Event，Event 时间
476
479
  - `session.duration`、`view.duration`、`session.start_time`、`session.lifecycle.reason`、`session.previous_id`。
477
480
  - `outcome.reason`；失败细分由领域字段表达。
478
481
  - `vital.rating`、`vital.cls.*` 归因、`vital.fcp.*` 归因、`vital.lcp.time_to_first_byte`。
479
- - `action.name`、`action.loading_time`；手动 Action 的 name 只进入 Span 名 `action.<name>`。
482
+ - `action.loading_time`；持续时间由 Span 起止时间表达。
480
483
  - `blank_screen.sample_count`、`valid_sample_count`、`ignored_sample_count`、`root_selector`、`root_found`、`center_element`。
481
484
  - `long_task.duration`、`long_task.start_time`。
482
485
  - `error.cross_origin`、`html.tag`。
package/skills/bk-rum-otele/references/transport-sampling.md CHANGED
@@ -50,7 +50,7 @@ https://rum.example.com/collector/v1/rum
50
50
  {
51
51
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
52
52
  "spanId": "00f067aa0ba902b7",
53
- "name": "browser.resource",
53
+ "name": "GET /api/orders/:id",
54
54
  "kind": 3,
55
55
  "startTimeUnixNano": "1784592000123000000",
56
56
  "endTimeUnixNano": "1784592000248000000",
@@ -300,7 +300,7 @@ session: {
300
300
  **第二层 · `FilteringSpanProcessor`（Span 结束时）。** 已结束的 recording Span 还要通过它才进入 simple/batch processor。以下会被丢弃：
301
301
 
302
302
  - 没有关联有效 `session.id`；
303
- - 除 `browser.session` 外，没有关联有效 `view.id`；
303
+ - 除 `span_type=session` 外，没有关联有效 `view.id`；
304
304
  - 属性里的 `url.full` 或 `http.url` 命中 SDK 自身的 `/v1/rum` 上报地址（后者用于识别第三方 HTTP Instrumentation 产生的自上报请求）；
305
305
  - 被请求插件的 `request.beforeSend` 标记为丢弃；
306
306
  - 被全局 `tracking.beforeSend` 返回 `false` 拒绝。
package/skills/bk-rum-otele/references/troubleshooting.md CHANGED
@@ -81,7 +81,7 @@ console.log({
81
81
  - 有 `session.id`；
82
82
  - 有 `view.id`。
83
83
 
84
- `browser.session` 是唯一可以没有 `view.id` 的内置 Span。
84
+ `span_type=session` 是唯一可以没有 `view.id` 的内置 Span。
85
85
 
86
86
  manual View 模式下，必须在 Session 建立后调用 `startView()`：
87
87
 
@@ -281,7 +281,7 @@ tracking: {
281
281
 
282
282
  ## 后端按 `traceparent` 的 trace-id 查不到 RUM Span
283
283
 
284
- 注入的 trace-id 与 RUM Span 自身的 `traceId` **不是同一个值**，两者通过 Span Link 关联。后端应按 `browser.resource` Span 的 `link.trace_id` 反查，而不是直接用 `traceId` 匹配。
284
+ 注入的 trace-id 与 RUM Span 自身的 `traceId` **不是同一个值**，两者通过 Span Link 关联。后端应按 `span_type=resource` Span 的 `link.trace_id` 反查，而不是直接用 `traceId` 匹配。
285
285
 
286
286
  如果 Link 的 `attributes.injected` 为 `false` 且 `attributes.format` 不是 `traceparent`，说明业务用的是 `b3` / `sw8` / Datadog 等格式。后端只解析 W3C `traceparent`，这种情况下后端不会生成 Trace，Link 里的 trace-id 自然查不到。
287
287
 
@@ -317,7 +317,7 @@ tracking: {
317
317
  - Resource Timing buffer 已满；
318
318
  - 条目时间顺序异常，SDK 会省略无效阶段而不是上报负值。
319
319
 
320
- 先判断 `browser.resource` 是否存在，再判断单个可选字段，不要把“字段缺失”当成“插件未工作”。
320
+ 先判断 `span_type=resource` 的 Span 是否存在，再判断单个可选字段，不要把“字段缺失”当成“插件未工作”。
321
321
 
322
322
  ## Web Vitals 缺失或值不同
323
323
 
package/skills/bk-rum-otele/references/views-routing.md CHANGED
@@ -13,7 +13,7 @@ View 表示一次可独立分析的页面体验。初始文档加载、SPA 路
13
13
  | `bf_cache` | 从 Back/Forward Cache 恢复 | `view` |
14
14
  | `session_renewal` | Session 过期后新 Session 接管当前页面 | `view` |
15
15
 
16
- 每个 View 都生成新的 `view.id`。View 的 URL、路由模板和自定义属性作为运行时上下文挂到其间发生的普通 Span；名称只在业务显式命名后才带上。
16
+ 每个 View 都生成新的 `view.id`。View 的 URL、路由模板、名称和自定义属性作为运行时上下文挂到其间发生的普通 Span。
17
17
 
18
18
  ## 自动路由模式
19
19
 
@@ -56,7 +56,7 @@ bkOT.startView({
56
56
 
57
57
  默认 `view.url_template` 取 URL pathname 并把数字 ID、UUID、长十六进制段折叠为 `:id`。请求和静态资源 Span 的 `url.template` 复用同一套折叠规则，但走独立的 `tracking.request.getUrlTemplate`。静态资源先通过 `redactUrl` 脱敏，再生成模板。
58
58
 
59
- `view.name` 与 `view.url_template` 是两个不同维度：前者是业务给出的可读标签（「订单详情」），后者是路由模板（`/orders/:id`）。**只有显式调用 `startView({ name })` 或 `setViewName()` 时才会上报 `view.name`**，未命名的 View 不带该字段，后端展示时用 `view.name ?? view.url_template` 兜底即可。这样 `view.name` 的存在本身就表示"业务命名过"，也不会在每条 Span 上重复一份模板字符串。
59
+ `view.name` 是视图名称，`view.url_template` 是路由模板（如 `/orders/:id`）。SDK 优先使用 `startView({ name })` 或 `setViewName()` 设置的名称；未显式设置时，`view.name` 默认取 `view.url_template`。
60
60
 
61
61
  ```ts
62
62
  tracking: {
@@ -78,7 +78,7 @@ tracking: {
78
78
  bkOT.setViewName('订单详情-只读');
79
79
  ```
80
80
 
81
- 名称变化不会创建新 View，但会更新运行时上下文并发送 `browser.view` update。传入与当前相同名称时不发送更新。首次调用会让此后的 Span 开始带上 `view.name`。
81
+ 名称变化不会创建新 View，但会更新运行时上下文并发送 View update Span。传入与当前相同名称时不发送更新，此后的 Span 使用新名称。
82
82
 
83
83
  ## URL 与前序页面
84
84
 
@@ -92,7 +92,7 @@ bkOT.setViewName('订单详情-只读');
92
92
 
93
93
  ## View 生命周期 Span
94
94
 
95
- Span 名固定为 `browser.view`：
95
+ Span 名使用 `view.name`：
96
96
 
97
97
  | phase | 触发 |
98
98
  | --- | --- |