@blueking/open-telemetry 0.0.13 → 0.0.15

package/skills/bk-rum-otele/references/telemetry-reference.md

@@ -9,7 +9,7 @@
 ## 命名规则
 
 - **信号名**：`browser.*` 表示内置浏览器事件（如 `browser.web_vital`）；`action.<type>`、`custom.<name>` 是运行期动态拼接；`csp.violation`、`websocket.*` 使用领域前缀。
-- **属性 key**：沿用 OpenTelemetry 语义约定的字段用点号（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`user.id`）；RUM 归一与低基数聚合维度用下划线（如 `span_type`、`result`、`browser_name`、`device_type`）。这一区分是有意为之，字段常量集中定义在 `src/schema/attributes.ts`。
+- **属性 key**：沿用 OpenTelemetry 语义约定的字段用点号（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`result`、`target_label`）。字段常量集中定义在 `src/schema/attributes.ts`。
 
 ## 公共上下文属性
 
@@ -17,44 +17,42 @@
 
 | key | 类型 | 说明 | 低基数 |
 | --- | --- | --- | --- |
-| `service.name` | string | 应用名（`app.name`） | 是 |
-| `service.version` | string | 应用版本（`app.version`，可选） | 是 |
-| `deployment.environment.name` | string | 环境（`app.environment`） | 是 |
+| `service.name` | string | 应用名（`application.name`） | 是 |
+| `service.version` | string | 应用版本（`application.version`，可选） | 是 |
+| `deployment.environment.name` | string | 环境（`application.environment`） | 是 |
 | `rum.provider` | string | 固定 `blueking` | 是 |
 | `telemetry.sdk.language` | string | 固定 `webjs` | 是 |
 | `user.id` | string | 接入方提供，原样透传 | 否 |
 | `session.id` | string | session 插件生成/轮换 | 否 |
 | `session.has_replay` | boolean | 当前固定 `false` | 是 |
-| `view.id` | string | pageView 维护的 view 实例 ID | 否 |
+| `view.id` | string | View 管理器生成的实例 ID | 否 |
+| `view.name` | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
 | `view.url` | string | 当前 view URL（已脱敏） | 否 |
 | `view.url_path_group` | string | 低基数路由模板 | 是 |
-| `view.loading_type` | string | `initial_load` / `route_change` | 是 |
-| `device_type` | string | `mobile` / `desktop` | 是 |
-| `browser_name` / `browser_version` | string | 浏览器信息 | 是 |
-| `os_name` | string | 操作系统 | 是 |
+| `view.loading_type` | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
+| `device.type` | string | `mobile` / `desktop` | 是 |
+| `browser.name` / `browser.version` | string | 浏览器信息 | 是 |
+| `os.name` | string | 操作系统 | 是 |
 | `network.effective_type` | string | 网络质量（`4g` 等） | 是 |
 
-> span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` / `event_label` / `target_label` 等归一字段（见下方[归一字段](#归一字段)）。默认 `attributes.page` 会额外注入 `rum.page.host` / `rum.page.path`。
+> span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` / `event_label` / `target_label` 等归一字段（见下方[归一字段](#归一字段)）。接入方可通过 `context.attributes.page` 注入额外的页面属性。
 
 ## Span 清单
 
 | span 名 | span_type | 来源 | 关键属性 | 备注 |
 | --- | --- | --- | --- | --- |
-| `browser.view` | `document` / `route` | pageView 插件 | `url.previous`、`event.source`、`view.end_reason` | 有持续时间，下一次 view 或 pagehide 时结束 |
-| `browser.page_view` | `document`（初始）/ `route`（路由） | pageView 插件 | `document.referrer`（仅初始加载） | 0ms 瞬时事件 |
-| `HTTP <METHOD>` | `http` | fetch / xhr instrumentation | `http.request.method`、`http.response.status_code`、`url.full`、`target_domain`、`target_path_template`、`status_class` | span 名由官方探针决定 |
-| `documentLoad` / `documentFetch` / `resourceFetch` | `document` / `resource` | documentLoad instrumentation | `trace_scene=page_load` | span 名由官方探针决定 |
-| `browser.resource` | `resource` | resource 插件 | `url.full`、`initiator_type`、`transfer_size`、`next_hop_protocol`、`cache_hit`、`resource.encoded_body_size`、`resource.decoded_body_size` | |
+| `browser.view` | `document` / `route` | View 管理器 | `view.name`、`view.loading_time`、`view.loading_time.source`、`url.previous`、`event.source`、`view.end_reason` | 有持续时间，下一次 View 或 pagehide 时结束 |
+| `HTTP <METHOD>` | `resource` | request 采集 | `resource.type=fetch\|xhr`、`resource.url`、`resource.method`、`resource.status_code`、网络阶段 events | span kind 为 CLIENT；Fetch/XHR 共用同一实现 |
+| `browser.resource` | `resource` | resource 插件 | `resource.type`、`resource.url`、`resource.duration`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
 | `browser.web_vital` | `vital` | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
-| `browser.blank_screen` | `error` | blankScreen 插件（判定为白屏时） | `blank_screen.score`、`blank_screen.threshold`、`blank_screen.detected`、`blank_screen.root`、`blank_screen.sample_*`、`blank_screen.center_element`、`blank_screen.dom_node_count` | |
+| `browser.blank_screen` | `error` | blankScreen 插件（二次确认白屏时） | `blank_screen.empty_ratio`、`blank_screen.reason`、`blank_screen.root_selector`、`blank_screen.root_found`、`blank_screen.*_sample_count`、`blank_screen.center_element` | 每个 View 最多一条 |
 | `browser.error` | `error` | error 插件（`window.error`） | `exception.*`、`error.source=window.error`、`error.window_count`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | |
 | `browser.unhandledrejection` | `error` | error 插件（Promise 异常） | `exception.*`、`error.source=unhandledrejection` | |
 | `browser.resource_error` | `error` | error 插件（资源加载失败） | `exception.*`、`error.source=resource`、`url.full`、`html.tag` | |
-| `browser.long_task` | `longtask` | longTask 插件 | `longtask.blocking_duration`、`longtask.attribution_script`、`target_value` | |
-| `browser.route_change` | `route` | routeTiming 插件 | `url.full`、`url.previous`、`route.change.source`、`target_value`（耗时） | |
+| `browser.long_task` | `longtask` | longTask 插件 | `long_task.id`、`long_task.entry_type`、`long_task.start_time`、`long_task.duration`、`long_task.blocking_duration`、`long_task.culprit`、`long_task.script.count`、`target_value` | LoAF 脚本详情写入 `long_task.script` Span Event |
 | `csp.violation` | `error` | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_count`、`csp.original_policy`（窗口首条） | |
 | `websocket.connect` | `custom` | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`network.protocol.name=websocket`、`target_domain` | 长连接生命周期不绑定 span |
-| `action.<type>` | `action` | action 插件 & `reportAction()` | `action.type`、`target.tag`、`target.text_short`、`target_label` | 如 `action.click` |
+| `action.click` / `action.custom` | `action` | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
 | `custom.<name>` | `custom` | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时附 `exception.*` |
 
 ## Metric 清单
@@ -63,16 +61,17 @@
 | --- | --- | --- | --- | --- |
 | `browser.web_vital.cls` | Histogram | `1` | `vital.metric`、`vital.rating`、`rum.navigation.type`、`view.url_path_group` | webVitals |
 | `browser.web_vital.duration` | Histogram | `ms` | 同上（FCP/INP/LCP/TTFB 靠 `vital.metric` 区分） | webVitals |
-| `browser.blank_screen.count` | Counter | - | `view.url_path_group`、`blank_screen.root` | blankScreen |
-| `browser.long_task.count` | Counter | - | `view.url_path_group`、`longtask.attribution_script` | longTask |
+| `browser.view.loading_time` | Histogram | `ms` | `view.url_path_group`、`view.loading_type` | View 管理器，View 结束时记录最终值 |
+| `browser.blank_screen.count` | Counter | - | `view.url_path_group`、`blank_screen.root_selector`、`blank_screen.reason` | blankScreen |
+| `browser.long_task.count` | Counter | - | `view.url_path_group`、`long_task.entry_type` | longTask |
 | `browser.long_task.duration` | Histogram | `ms` | 同上 | longTask |
-| `browser.route_change.duration` | Histogram | `ms` | `view.url_path_group`、`route.change.source` | routeTiming |
+| `browser.long_task.blocking_duration` | Histogram | `ms` | 同上 | longTask，仅 LoAF |
 | `browser.websocket.message.count` | Counter | - | `server.address`、`url.scheme`、`websocket.direction`（in/out） | websocket |
 | `browser.websocket.message.bytes` | Counter | `By` | 同上 | websocket |
 | `browser.websocket.error.count` | Counter | - | `server.address`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
 | `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`url.scheme` | websocket，仅成功建连 |
 
-> 各 metric 还会合并 `attributes.metric` hook 返回的自定义低基数维度；具体附加的公共维度（如 `attributes.page`）因插件而异。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
+> 各 metric 只会合并 `context.attributes.metric` hook 返回的自定义低基数维度，不会合并 `context.attributes.page`，也不会携带 `session.id`、`view.id` 或 `action.id`。精确 View 关联请查询对应 span 或 View Snapshot Log。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
 
 ## Log 事件清单
 
@@ -80,8 +79,8 @@
 | --- | --- | --- | --- |
 | `session.start` | INFO | session 插件（首次新建） | `session.id`、`session.start_time`、`session.rotate.reason=init` |
 | `session.rotate` | INFO | session 插件（轮换） | + `session.previous_id`、`session.rotate.reason`（`inactivity` / `maxLifetime`） |
-| `HTTP request completed` | INFO | httpBody 插件（成功请求） | `http.request.method`、`http.response.status_code`、`url.full`、`http.duration` |
-| `HTTP request completed with error` | ERROR | httpBody 插件（错误路径） | + `http.request.body`、`http.response.body`、`http_body.request.truncated`、`http_body.response.truncated`、`exception.*` |
+| `browser.view` | INFO | View 管理器 | `view.snapshot.type=create\|update\|final`、`view.document_version`、`view.duration`、`view.is_active`、`view.loading_time` |
+| `browser.request.body` | ERROR（错误请求）/ INFO（`capture: 'all'` 的成功请求） | request instrumentation（仅显式配置 `request.body`） | `trace.id`、`span.id`、`request.body` / `response.body`、`*.body.content_type`、`*.body.truncated` |
 | `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_count` |
 | `websocket.close` | INFO | websocket 插件 | `websocket.close.code`、`websocket.close.reason`、`websocket.close.was_clean` |
 
@@ -95,7 +94,7 @@
 
 | key | 类型 | 说明 | 低基数 |
 | --- | --- | --- | --- |
-| `span_type` | string | `document`/`http`/`resource`/`vital`/`error`/`longtask`/`action`/`route`/`custom` | 是 |
+| `span_type` | string | `document`/`resource`/`vital`/`error`/`longtask`/`action`/`route`/`custom` | 是 |
 | `span_subtype` | string | 子类型，如 `fetch`/`xhr`/`js`/`promise`/`lcp` | 是 |
 | `result` | string | `success`/`warning`/`error`/`timeout`/`abort` | 是 |
 | `error_type` | string | 错误细分，如 `http_5xx`/`network_timeout`/`slow`/`none` | 是 |
@@ -115,15 +114,30 @@
 | `http.request.method` | string | 请求方法（大写） |
 | `http.response.status_code` | number | 响应状态码 |
 | `url.full` | string | 完整 URL（已脱敏） |
+| `resource.type` | string | `fetch`/`xhr` 或静态资源 initiator type |
+| `resource.url` | string | 资源 URL（已脱敏） |
+| `resource.method` | string | 请求方法（Fetch/XHR） |
+| `resource.status_code` | number | 请求状态码（Fetch/XHR） |
+| `resource.duration` | number | 静态资源耗时（ms）；请求耗时使用 Span 原生 duration |
+| `resource.redirect.start/duration` | number | 重定向阶段相对开始时间 / 耗时（ms） |
+| `resource.dns.start/duration` | number | DNS 阶段相对开始时间 / 耗时（ms） |
+| `resource.connect.start/duration` | number | TCP 建连阶段相对开始时间 / 耗时（ms） |
+| `resource.ssl.start/duration` | number | TLS 握手阶段相对开始时间 / 耗时（ms） |
+| `resource.first_byte.start/duration` | number | 等待首字节阶段相对开始时间 / 耗时（ms） |
+| `resource.download.start/duration` | number | 响应下载阶段相对开始时间 / 耗时（ms） |
+| `resource.worker.start/duration` | number | Service Worker 阶段相对开始时间 / 耗时（ms） |
+| `resource.delivery_type` | string | `cache` / `navigational-prefetch` 等浏览器交付类型 |
+| `resource.render_blocking_status` | string | `blocking` / `non-blocking` |
+| `resource.size` | number | 传输字节数 |
 | `url.previous` | string | 跳转前 URL |
 | `transfer_size` | number | 传输字节数 |
-| `cache_hit` | boolean | 是否命中缓存 |
-| `next_hop_protocol` | string | 协议，如 `h2` |
+| `resource.cache.hit` | boolean | 是否命中缓存 |
+| `resource.protocol` | string | 协议，如 `h2` |
 | `initiator_type` | string | 资源发起类型 |
 | `resource.encoded_body_size` / `resource.decoded_body_size` | number | 资源体积 |
-| `http.duration` | number | httpBody 插件记录的请求耗时（ms） |
-| `http.request.body` / `http.response.body` | string | 仅 httpBody 错误路径，经 `redact` 脱敏 |
-| `http_body.request.truncated` / `http_body.response.truncated` | boolean | body 是否被截断 |
+| `request.body` / `response.body` | string | 仅 `browser.request.body` Log；经过接入方 `redact` 且受长度限制 |
+| `request.body.content_type` / `response.body.content_type` | string | body Content-Type（可获取时） |
+| `request.body.truncated` / `response.body.truncated` | boolean | body 是否因长度限制而截断 |
 
 ### Web Vitals
 
@@ -157,21 +171,30 @@
 
 | key | 类型 | 说明 |
 | --- | --- | --- |
-| `device.id` | string | 设备终身标识（localStorage 持久） |
+| `device.id` | string | 匿名设备标识；默认仅当前 SDK 实例稳定，`tracking.device.persistentId=true` 时持久化 |
 | `device.memory` / `device.cpu_cores` | number | 硬件能力 |
 | `device.platform` / `device.mobile` | string/bool | UA-CH 平台信息 |
 | `browser.viewport.width` / `browser.viewport.height` | number | 视口尺寸 |
 | `browser.screen.width` / `browser.screen.height` | number | 屏幕尺寸 |
 | `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data` | mixed | 网络信息 |
-| `user_agent.name` / `user_agent.version` / `user_agent.os.name` | string | UA 解析结果 |
+| `browser.name` / `browser.version` / `os.name` | string | UA 解析结果 |
+| `device.type` | string | `mobile` / `desktop` |
 
 ### 用户动作 / 会话
 
 | key | 类型 | 说明 |
 | --- | --- | --- |
 | `action.type` | string | 动作类型 |
-| `target.tag` | string | 目标元素标签 |
-| `target.text_short` | string | 目标文本前 32 字符 |
+| `action.id` | string / string[] | action 自身 ID；关联事件上为 action ID 数组 |
+| `action.name` | string | 可读动作名称 |
+| `action.target.name` | string | 自动 action 的目标元素名称 |
+| `action.target.tag` | string | 自动 action 的目标元素标签 |
+| `action.loading_time` | number | 点击后页面活动稳定耗时（ms） |
+| `action.resource.count` | number | action 关联资源数 |
+| `action.error.count` | number | action 关联错误数 |
+| `action.long_task.count` | number | action 关联长任务数 |
+| `action.frustration.type` | string[] | `rage_click` / `dead_click` / `error_click` |
+| `action.frustration.count` | number | 当前 action 的挫败信号数量 |
 | `session.start_time` | number | 会话开始时间戳 |
 | `session.previous_id` | string | 轮换前的 session.id |
 | `session.rotate.reason` | string | `init`/`inactivity`/`maxLifetime` |
@@ -180,8 +203,15 @@
 
 | key | 类型 | 说明 |
 | --- | --- | --- |
-| `longtask.blocking_duration` | number | 长任务时长（ms） |
-| `longtask.attribution_script` | string | 归因脚本 |
+| `long_task.id` | string | 长任务或长动画帧 ID |
+| `long_task.entry_type` | string | `long-animation-frame` / `long-task` |
+| `long_task.start_time` | number | LoAF 相对 `performance.timeOrigin` 的开始时间（ms） |
+| `long_task.duration` / `long_task.blocking_duration` | number | 总耗时 / 主线程阻塞耗时（ms） |
+| `long_task.is_frozen_frame` | boolean | 总耗时是否达到 700ms |
+| `long_task.culprit` | string | 最重脚本 URL、函数或 legacy attribution |
+| `long_task.script.count` | number | LoAF 脚本数 |
+| `long_task.render_start` / `long_task.style_and_layout_start` | number | LoAF 渲染与样式布局阶段起点 |
+| `long_task.script.*` | mixed | `long_task.script` Span Event 上的脚本耗时、URL、函数、invoker 和强制布局归因 |
 
 ### CSP
 
@@ -212,17 +242,16 @@
 
 | key | 类型 | 说明 |
 | --- | --- | --- |
-| `blank_screen.score` | number | 空白样本比例 |
-| `blank_screen.threshold` | number | 判定阈值 |
-| `blank_screen.detected` | boolean | 是否判为白屏 |
-| `blank_screen.root` | string | 采样根选择器 |
-| `blank_screen.sample_total` / `blank_screen.sample_valid` / `blank_screen.sample_loading` | number | 采样统计 |
+| `blank_screen.empty_ratio` | number | 有效样本中的空白比例 |
+| `blank_screen.reason` | string | `empty_viewport` / `missing_root` |
+| `blank_screen.root_selector` / `blank_screen.root_found` | string/boolean | 根选择器与是否存在 |
+| `blank_screen.sample_count` / `blank_screen.valid_sample_count` | number | 总样本数 / 有效样本数 |
+| `blank_screen.empty_sample_count` / `blank_screen.ignored_sample_count` | number | 空白样本数 / loading 忽略样本数 |
 | `blank_screen.center_element` | string | 视口中心元素选择器 |
-| `blank_screen.dom_node_count` | number | body 下 DOM 节点总数 |
 
 ### 自定义事件
 
 | key | 类型 | 说明 |
 | --- | --- | --- |
 | `rum.custom.name` | string | `reportCustomEvent()` 的事件名 |
-| `rum.page.host` / `rum.page.path` | string | 默认 `attributes.page` 注入的页面上下文 |
+| `rum.page.host` / `rum.page.path` | string | 默认 `context.attributes.page` 页面上下文；配置自定义 page hook 后由接入方决定字段 |

package/skills/bk-rum-otele/references/troubleshooting.md

@@ -10,13 +10,16 @@
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
   debug: true,
-  spanProcessor: 'simple',
-  sampling: {
-    rate: 1,
+  session: {
+    sampleRate: 1,
   },
   transport: {
     endpoint: 'http://localhost:4318',
+    signals: {
+      traces: { processor: 'simple' },
+    },
   },
 });
 ```
@@ -24,7 +27,7 @@ new BkOpenTelemetry({
 检查点：
 
 - Collector 是否监听 `4318`。
-- 浏览器 Network 中是否有 `/rum`、`/metrics`、`/logs` 请求。
+- 浏览器 Network 中是否有 `/v1/rum`、`/v1/metrics`、`/v1/logs` 请求。
 - 是否被采样丢弃。
 - `enabled` 是否为 `false`。
 
@@ -34,10 +37,12 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
   debug: true,
-  sampling: {
-    rate: 1,
+  session: {
+    sampleRate: 1,
   },
+  transport: { endpoint: 'https://rum-collector.example.com' },
 });
 ```
 
@@ -47,7 +52,9 @@ new BkOpenTelemetry({
 
 ```ts
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
   autoStart: false,
+  transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
 bkOT.use(myPlugin);
@@ -61,7 +68,9 @@ SPA 应用应配置 `rootSelector` 和 loading/skeleton 忽略选择器。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     blankScreen: {
       rootSelector: '#app',
       ignoreSelectors: ['.bk-loading', '.skeleton'],
@@ -73,13 +82,16 @@ new BkOpenTelemetry({
 
 ## 接口 span 太多
 
-先确认是否有多个 SDK 实例重复初始化，尤其是微前端场景。其次可以关闭不需要的 instrumentation。
+先确认是否有多个 SDK 实例重复初始化，尤其是微前端场景。其次用 `excludedUrls` 排除探活或高频无价值请求。
 
 ```ts
 new BkOpenTelemetry({
-  instrumentations: {
-    fetch: true,
-    xhr: false,
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    request: {
+      excludedUrls: [/\/health(?:\?|$)/, /\/polling\//],
+    },
   },
 });
 ```
@@ -90,6 +102,8 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
   privacy: {
     redactUrl: url => url.replace(/([?&]token=)[^&]+/g, '$1***'),
     redactAttributes: attributes => {
@@ -107,7 +121,9 @@ Long Task API 并非所有浏览器都支持。Firefox 不支持时插件会跳
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     longTask: {
       threshold: 50,
     },
@@ -117,26 +133,36 @@ new BkOpenTelemetry({
 
 ## HTTP body 没有数据
 
-`httpBody` 只在错误路径采集，且默认关闭。
+请求/响应 body 默认关闭。需要采集时配置 `tracking.request.body`，并提供必填的 `redact`：
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    httpBody: {
-      maxBodySize: 4096,
-      redact: ({ body }) => body,
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    request: {
+      body: {
+        capture: 'errors',
+        allowedContentTypes: ['application/json'],
+        maxSize: 10 * 1024,
+        redact: ({ body }) => body.replace(/"password"\s*:\s*"[^"]+"/g, '"password":"***"'),
+      },
     },
   },
 });
 ```
 
+`capture` 默认就是 `errors`，成功请求不会产生 body Log；要采集成功请求需显式设为 `all`。如果仍然没有数据，依次检查 Content-Type 是否命中 `allowedContentTypes`、body 是否为支持的文本类型，以及 `redact` 是否返回了 `undefined`。FormData、ArrayBuffer 和二进制响应会跳过。
+
 ## WebSocket 采集异常
 
 WebSocket 插件会 Proxy 全局 `WebSocket`。如果应用或第三方库也 patch 了 WebSocket，应避免重复 patch。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     websocket: true,
   },
 });
@@ -146,14 +172,15 @@ new BkOpenTelemetry({
 
 ## SDK 会采集哪些数据？
 
-默认采集页面访问、资源加载、fetch/xhr、JavaScript 错误、Web Vitals、空白屏、设备信息和会话信息。动作、HTTP body、Long Task、路由耗时、CSP、WebSocket 默认关闭。
+默认采集页面访问与稳定耗时、用户动作、资源加载、fetch/xhr、JavaScript 错误、Web Vitals、空白屏、设备信息和会话信息。HTTP body、Long Task、CSP、WebSocket 默认关闭。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     action: true,
     longTask: true,
-    routeTiming: true,
     websocket: true,
   },
 });
@@ -165,32 +192,37 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  user: {
-    id: hashUserId(rawUserId),
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  context: {
+    user: {
+      id: hashUserId(rawUserId),
+    },
   },
 });
 ```
 
-## `sampling.rate` 是 trace 级采样吗？
+## `session.sampleRate` 是 trace 级采样吗？
 
-不是。它是会话级 sticky 采样，同一会话内保持一致。
+不是。它是会话级确定性采样，同一会话内保持一致。
 
 ```ts
 new BkOpenTelemetry({
-  sampling: {
-    rate: 0.2,
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  session: {
+    sampleRate: 0.2,
   },
 });
 ```
 
-## 为什么开启了 userInteraction 还需要 action 插件？
+## 为什么不使用 OpenTelemetry userInteraction instrumentation？
 
-`userInteraction` 是 OpenTelemetry 官方 instrumentation，产生的是官方用户交互 span；`action` 插件和 `reportAction()` 会写入 SDK 的 RUM action 归一字段。需要稳定的业务动作模型时，推荐使用 `action` 或 `reportAction()`。
+官方 userInteraction instrumentation 主要用于把交互回调中的异步任务组织成 trace，但没有稳定的 RUM action 语义、动作命名、页面活动窗口和关联计数。本 SDK 统一使用 `action` 插件，避免同一次点击重复上报；内置 request 采集统一负责 Fetch/XHR 网络 trace。
 
 ```ts
 bkOT.reportAction({
-  type: 'click',
-  targetText: '确认提交',
+  name: '确认提交',
   attributes: {
     'biz.scene': 'strategy-create',
   },
@@ -199,29 +231,31 @@ bkOT.reportAction({
 
 ## 可以只上报 traces，不上报 metrics/logs 吗？
 
-当前 SDK 会初始化三类 provider。可以在 Collector 或网关层按信号丢弃，也可以为不同信号配置不同 endpoint。
+可以。将不需要的信号设为 `false`；根 endpoint 在所有已开启信号都配置独立地址时可以省略。
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'demo' },
   transport: {
     signals: {
-      endpoints: {
-        traces: 'https://trace-gateway.example.com/v1/rum',
-        metrics: 'https://metric-gateway.example.com/v1/metrics',
-        logs: 'https://log-gateway.example.com/v1/logs',
-      },
+      traces: { endpoint: 'https://trace-gateway.example.com/v1/rum' },
+      metrics: false,
+      logs: false,
     },
   },
 });
 ```
 
+三类信号不能全部关闭。关闭 Trace 后也不会注入 `traceparent`。
+
 ## 为什么不建议多个实例同时运行？
 
-fetch、xhr、userInteraction、websocket 等能力会 patch 全局 API。多个实例可能重复 patch、重复上报或互相影响。
+fetch、xhr、action、websocket 等能力会监听或 patch 全局 API。多个实例可能重复采集、重复上报或互相影响。
 
 ```ts
 if (!window.__BK_RUM_INSTANCE__) {
   window.__BK_RUM_INSTANCE__ = new BkOpenTelemetry({
+    application: { name: 'demo' },
     transport: {
       endpoint: 'https://rum-collector.example.com',
     },

package/dist/plugins/http-body.d.ts

@@ -1,3 +0,0 @@
-import type { BkOTHttpBodyConfig } from '../core/config';
-import type { BkOTPlugin } from '../core/plugin';
-export declare const createHttpBodyPlugin: (options?: BkOTHttpBodyConfig) => BkOTPlugin;

package/dist/plugins/route-timing.d.ts

@@ -1,2 +0,0 @@
-import type { BkOTPlugin } from '../core/plugin';
-export declare const createRouteTimingPlugin: () => BkOTPlugin;