@blueking/open-telemetry 0.0.21 → 0.0.22

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

@@ -2,285 +2,55 @@
 
 # 遥测参考
 
-本页是 SDK **实际产出**的 span 名、metric 名、log 事件名和属性字段的权威速查表，供数据看板、告警规则、后端建模对齐。所有名称都与 SDK 源码保持一致，随版本更新。
-
-> 概念与设计边界见[数据模型](./data-model.md)；本页只做「叫什么名字、带哪些字段」的查询。
-
-## 命名规则
-
-- **信号名**：`browser.*` 表示内置浏览器事件（如 `browser.web_vital`）；`action.<type>`、`custom.<name>` 是运行期动态拼接；`csp.violation`、`websocket.*` 使用领域前缀。
-- **属性 key**：标准字段与 RUM 领域字段均使用点号命名空间（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。公共与跨插件字段常量集中定义在 `src/schema/attributes.ts`，插件私有字段在对应插件内定义。
-
-## 公共 Resource 与运行时上下文属性
-
-Resource 属性由三类信号共享；运行时上下文属性自动挂到**几乎所有** span / log 上（metric 视插件而定）。后续各清单不再重复列出：
-
-| key | 归属 | 类型 | 说明 | 低基数 |
-| --- | --- | --- | --- | --- |
-| `service.name` | Resource | string | 应用名（`application.name`） | 是 |
-| `service.version` | Resource | string | 应用版本（`application.version`，可选） | 是 |
-| `deployment.environment.name` | Resource | string | 环境（`application.environment`） | 是 |
-| `rum.schema.version` | Resource | string | 当前固定 `2` | 是 |
-| `telemetry.sdk.name` / `telemetry.sdk.language` / `telemetry.sdk.version` | Resource | string | SDK 名、语言和包版本 | 是 |
-| `device.type` | Resource | string | `mobile` / `desktop` | 是 |
-| `browser.name` / `browser.version` | Resource | string | 归一化浏览器信息 | 是 |
-| `os.name` | Resource | string | 操作系统 | 是 |
-| `device.memory_gib` | Resource | number | 浏览器暴露的近似设备内存（GiB） | 是 |
-| `device.logical_processor_count` | Resource | number | 浏览器暴露的逻辑处理器数量 | 是 |
-| `user.id` | Runtime | string | 接入方提供，原样透传 | 否 |
-| `session.id` | Runtime | string | session 插件生成/轮换 | 否 |
-| `session.has_replay` | Runtime | boolean | 当前固定 `false` | 是 |
-| `view.id` | Runtime | string | View 管理器生成的实例 ID | 否 |
-| `view.name` | Runtime | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
-| `view.url` | Runtime | string | 当前 view URL（已脱敏） | 否 |
-| `view.url_path_group` | Runtime | string | 低基数路由模板 | 是 |
-| `view.loading_type` | Runtime | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
-| `device.id` | Runtime | string | 当前实例或持久化匿名设备 ID | 否 |
-| `network.effective_type` | Runtime | string | 网络质量（`4g` 等） | 是 |
-
-> span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` 等归一字段（见下方[归一字段](#归一字段)）。接入方可通过 `context.attributes.page` 注入额外的页面属性。
+SDK 只产出 RUM Span，不产出 OpenTelemetry Metric 或 Log。计数、直方图、分位数和错误分组由服务端从原始 Span 派生。
+
+## 公共字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `event.id` | string | 每条原始事件的唯一 ID，服务端去重键 |
+| `event.type` | string | `session`、`view`、`resource`、`error`、`vital`、`action`、`websocket` 等 |
+| `event.phase` | string | 生命周期事件阶段；非生命周期事件可不带 |
+| `event.timestamp` | number | 浏览器事件发生的 epoch ms |
+| `session.id` | string | Session 关联 ID |
+| `session.start_time` | number | Session 开始时间 |
+| `session.type` | string | 当前为 `user` |
+| `session.sample_rate` | number | Resource 字段，范围 `0..1` |
+| `view.id` | string | View 关联 ID |
+| `view.name` | string | View 名称 |
+| `view.url` | string | 脱敏后的 URL |
+| `view.url_path_group` | string | 服务端聚合用路由模板 |
+| `action.id` | string/string[] | Action 关联 ID |
+| `span_type` / `span_subtype` | string | RUM 分类 |
+| `result` / `error_type` | string | 单事件结果分类 |
 
 ## Span 清单
 
-| span 名 | span_type | kind | 来源 | 关键属性 | 备注 |
-| --- | --- | --- | --- | --- | --- |
-| `browser.view` | `document` / `route` | INTERNAL | View 管理器 | `view.name`、`view.loading_time`、`view.loading_time.source`、`url.previous`、`event.source`、`view.end_reason` | 有持续时间，由下一次 View、pagehide、Session 过期或 SDK shutdown 结束 |
-| `browser.resource` | `resource` | CLIENT | Fetch/XHR request 采集 | `resource.type=fetch\|xhr`、`url.full`、`http.request.method`、`http.response.status_code`、网络阶段属性 | Fetch/XHR 共用同一实现 |
-| `browser.resource` | `resource` | CLIENT | resource 插件 | `resource.type`、`url.full`、`resource.size`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
-| `browser.web_vital` | `vital` | INTERNAL | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
-| `browser.blank_screen` | `error` | INTERNAL | 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` | INTERNAL | error 插件（`window.error`） | `exception.fingerprint`、`exception.message_short`、`exception.stack_top_frame`、`error.source=window.error`、`error.window_occurrence_index`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | 完整异常写入标准 `exception` Span Event |
-| `browser.unhandledrejection` | `error` | INTERNAL | error 插件（Promise 异常） | `exception.fingerprint`、`error.source=unhandledrejection` | 完整异常写入标准 `exception` Span Event |
-| `browser.resource_error` | `error` | INTERNAL | error 插件（资源加载失败） | `exception.fingerprint`、`error.source=resource`、`url.full`、`html.tag` | 完整异常写入标准 `exception` Span Event |
-| `browser.long_task` | `longtask` | INTERNAL | 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` | LoAF 脚本详情写入 `long_task.script` Span Event |
-| `csp.violation` | `error` | INTERNAL | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_occurrence_index`、`csp.original_policy`（窗口首条） | |
-| `websocket.connect` | `custom` | CLIENT | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`server.port`、`network.protocol.name=websocket` | 长连接生命周期不绑定 span |
-| `action.click` / `action.custom` | `action` | INTERNAL | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
-| `custom.<name>` | `custom` | INTERNAL | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时记录 exception、设置错误 Status/Result，`span_type` 仍为 `custom` |
-
-## Metric 清单
-
-| 名称 | 类型 | 单位 | 主要维度 | 来源 |
-| --- | --- | --- | --- | --- |
-| `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.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.error.count` | Counter | - | `view.url_path_group`、`error.source`、`error.subtype` | error，span 节流前精确累计 |
-| `browser.csp_violation.count` | Counter | - | `view.url_path_group`、`csp.disposition`、`csp.effective_directive` | cspViolation，span 节流前精确累计 |
-| `browser.long_task.count` | Counter | - | `view.url_path_group`、`long_task.entry_type` | longTask |
-| `browser.long_task.duration` | Histogram | `ms` | 同上 | longTask |
-| `browser.long_task.blocking_duration` | Histogram | `ms` | 同上 | longTask，仅 LoAF |
-| `browser.websocket.message.count` | Counter | - | `server.address`、`server.port`、`url.scheme`、`websocket.direction`（in/out） | websocket |
-| `browser.websocket.message.bytes` | Counter | `By` | 同上 | websocket |
-| `browser.websocket.error.count` | Counter | - | `server.address`、`server.port`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
-| `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`server.port`、`url.scheme` | websocket，仅成功建连 |
-
-> 各 metric 只会合并 `context.attributes.metric` hook 返回的自定义低基数维度，不会合并 `context.attributes.page`，也不会携带 `session.id`、`view.id` 或 `action.id`。`view.url_path_group` 中明显的数字 ID、UUID、长十六进制段会归一为 `:id`。精确 View 关联请查询对应 span 或 View Snapshot Log。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
-
-## Log 事件清单
-
-| eventName / body | severity | 来源 | 关键属性 |
-| --- | --- | --- | --- |
-| `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`） |
-| `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'` 的成功请求） | Fetch/XHR request patch（仅显式配置 `request.body`） | 通过 OTel Log Context 关联 Trace/Span；属性含 `request.body` / `response.body`、`*.body.content_type`、`*.body.truncated` |
-| `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_occurrence_index` |
-| `websocket.close` | INFO | websocket 插件 | `websocket.close.code`、`websocket.close.reason`、`websocket.close.was_clean` |
-
-> 内置 Log 的 `eventName` 与 `body` 当前使用同一个事件名；查询与 `tracking.beforeSend` 应优先使用 `eventName`。
-
-> 错误主数据统一走 `error` span（见 Span 清单），SDK **不再**为同一个错误额外 emit error log，避免重复计数。
-
-## 属性字典
-
-### 归一字段
-
-由 `buildRumSpanAttributes` 等构造器写入，用于跨事件类型统一检索。
-
-| key | 类型 | 说明 | 低基数 |
-| --- | --- | --- | --- |
-| `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` | 是 |
-
-### View / Navigation
-
-| key | 类型 | 出现位置 | 说明 |
-| --- | --- | --- | --- |
-| `view.id` / `view.name` / `view.url` / `view.url_path_group` | string | Span / Log | View 标识、名称、脱敏 URL 与低基数路由模板 |
-| `view.loading_type` | string | Span / Log / Metric | `initial_load` / `route_change` / `session_renewal` / `bf_cache` |
-| `view.loading_time` | number | Span / Log；同时作为 Metric 值 | View 从开始到页面活动稳定的耗时（ms） |
-| `view.loading_time.source` | string | Span / Log | `auto` / `manual` |
-| `view.first_byte` | number | 初始 View Span / Log | Navigation Timing 的 `responseStart`（相对 `performance.timeOrigin`，ms） |
-| `view.dom_interactive` / `view.dom_content_loaded` | number | 初始 View Span / Log | DOM interactive / DOMContentLoaded 时间（相对 `performance.timeOrigin`，ms） |
-| `view.dom_complete` / `view.load_event` | number | 初始 View Span / Log | DOM complete / load event 时间（相对 `performance.timeOrigin`，ms） |
-| `url.previous` | string | Span / Log | 前一个 View URL（已脱敏） |
-| `document.referrer` | string | 初始 View Span / Log | 页面 referrer（已脱敏） |
-| `event.source` | string | Span / Log | View 创建触发源，如 `load`、`pushState`、`popstate`、`manual`、`bfCache`、`sessionRenewal` |
-| `view.end_reason` | string | Span / final Log | 下一 View 的触发源，或 `pagehide` / `session_expired` / `shutdown` |
-| `event.type` | string | Log | 固定 `view` |
-| `view.snapshot.type` | string | Log | `create` / `update` / `final` |
-| `view.document_version` | number | Log | 当前 View Snapshot 的递增版本号 |
-| `view.duration` | number | Log | 从 View 开始到 Snapshot 的耗时（ms） |
-| `view.is_active` | boolean | Log | 非 final Snapshot 为 `true` |
-
-### HTTP / Resource
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `http.request.method` | string | 请求方法（大写） |
-| `http.response.status_code` | number | 响应状态码 |
-| `url.full` | string | 完整 URL（已脱敏） |
-| `server.address` | string | 目标主机名 |
-| `server.port` | number | 目标显式端口（存在时） |
-| `resource.type` | string | `fetch`/`xhr` 或静态资源 initiator type |
-| `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 |
-| `resource.cache.hit` | boolean | 是否命中缓存 |
-| `resource.protocol` | string | 协议，如 `h2` |
-| `resource.encoded_body_size` / `resource.decoded_body_size` | number | 资源体积 |
-| `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
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `vital.metric` | string | `cls`/`fcp`/`inp`/`lcp`/`ttfb` |
-| `vital.value` | number | 指标值 |
-| `vital.rating` | string | `good`/`needs-improvement`/`poor` |
-| `vital.id` | string | 单条度量唯一 ID（仅 span） |
-| `rum.navigation.type` | string | 导航类型，含 `back-forward-cache` 等 |
-| `vital.lcp.*` / `vital.cls.*` / `vital.inp.*` / `vital.fcp.*` / `vital.ttfb.*` | mixed | attribution 归因明细（仅 span） |
-
-### 错误 / 异常
-
-以下字段位于 Error Span 顶层属性：
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `exception.message_short` | string | 消息前 80 字符 |
-| `exception.stack_top_frame` | string | 栈顶帧 |
-| `exception.fingerprint` | string | 节流分组指纹（djb2 hash） |
-| `error.source` | string | `window.error`/`unhandledrejection`/`resource`/`csp` |
-| `error.handled` | boolean | 是否被业务捕获（自动采集恒为 `false`） |
-| `error.window_occurrence_index` | number | 当前节流窗口内该已上报 span 的触发序号；总量查询 `browser.error.count` |
-| `error.cross_origin` | boolean | 跨域脚本错误（`Script error.`） |
-| `code.filepath` / `code.lineno` / `code.column` | string/number | JS 错误位置 |
-| `html.tag` | string | 资源错误的元素标签 |
-
-`error.subtype` 仅作为 `browser.error.count` Metric 维度，取值为 `js` / `promise` / `resource_load`，不写入 Error Span 顶层属性。
-
-完整异常由 `recordException()` 写入名为 `exception` 的标准 Span Event，不在 Span 顶层属性中：
-
-| Event 属性 | 类型 | 说明 |
-| --- | --- | --- |
-| `exception.type` | string | 异常类型/名称 |
-| `exception.message` | string | 异常消息 |
-| `exception.stacktrace` | string | 堆栈（存在时） |
-
-### 设备 / 浏览器 / 网络
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `device.id` | string | 匿名设备标识；默认仅当前 SDK 实例稳定，`tracking.device.persistentId=true` 时持久化 |
-| `device.memory_gib` | number | Resource 中的近似设备内存（GiB） |
-| `device.logical_processor_count` | number | Resource 中的逻辑处理器数量 |
-| `browser.viewport.width` / `browser.viewport.height` | number | 视口尺寸 |
-| `browser.screen.width` / `browser.screen.height` | number | 屏幕尺寸 |
-| `network.effective_type` | string | 网络质量，如 `4g` |
-| `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data` | mixed | 网络信息 |
-| `browser.name` / `browser.version` / `os.name` | string | Resource 中的 UA 解析结果 |
-| `device.type` | string | Resource 中的 `mobile` / `desktop` |
-
-### 用户动作 / 会话
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `action.type` | string | 动作类型 |
-| `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` |
-
-### Long Task
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `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.first_ui_event_timestamp` | number | LoAF 首个 UI Event 时间戳 |
-| `long_task.render_start` / `long_task.style_and_layout_start` | number | LoAF 渲染与样式布局阶段起点 |
-| `long_task.culprit.*` | mixed | 最重脚本的耗时、强制布局耗时、函数名与 invoker 类型 |
-| `long_task.script.*` | mixed | `long_task.script` Span Event 上的脚本耗时、URL、函数、invoker 和强制布局归因 |
-
-### CSP
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `csp.blocked_uri` | string | 被拦截资源（URL 类值已脱敏） |
-| `csp.violated_directive` / `csp.effective_directive` | string | 违反的指令 |
-| `csp.disposition` | string | `enforce` / `report` |
-| `csp.source_file` | string | 触发脚本（已脱敏） |
-| `csp.line_number` / `csp.column_number` | number | 位置 |
-| `csp.status_code` | number | 状态码 |
-| `csp.fingerprint` / `csp.window_occurrence_index` | string/number | 节流指纹与该已上报 span 的窗口触发序号 |
-| `csp.original_policy` | string | 完整策略，仅窗口首条携带 |
-
-### WebSocket
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `url.scheme` | string | `ws` / `wss` |
-| `server.address` | string | 目标 hostname，不包含端口 |
-| `server.port` | number | 目标显式端口（存在时） |
-| `network.protocol.name` | string | 固定 `websocket` |
-| `websocket.direction` | string | `in` / `out`（仅 metric） |
-| `websocket.error.phase` | string | `connect` / `runtime` |
-| `websocket.error.window_occurrence_index` | number | 该已上报错误日志在节流窗口内的触发序号；总量查询 `browser.websocket.error.count` |
-| `websocket.close.code` / `websocket.close.reason` / `websocket.close.was_clean` | mixed | 关闭事件详情 |
-
-### 白屏
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `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 | 视口中心元素选择器 |
-
-### 自定义事件
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `rum.custom.name` | string | `reportCustomEvent()` 的事件名 |
-| `rum.page.host` / `rum.page.path` | string | 默认 `context.attributes.page` 页面上下文；配置自定义 page hook 后由接入方决定字段 |
+| Span 名 | `event.type` | 关键字段 |
+| --- | --- | --- |
+| `browser.session` | `session` | `event.phase=start\|rotate\|end`、`session.lifecycle.reason`、`session.previous_id` |
+| `browser.view` | `view` | `event.phase=start\|update\|end`、`view.version`、`view.started_at`、`view.loading_type`、`view.loading_time`、`view.end_reason` |
+| `browser.resource` | `resource` | `url.full`、`resource.type`、HTTP 状态、体积和 Resource Timing 阶段 |
+| `browser.error` | `error` | `error.source=window.error`、`error.message`、代码位置；完整异常写入标准 exception event |
+| `browser.unhandledrejection` | `error` | `error.source=unhandledrejection`、`error.message`、标准 exception event |
+| `browser.resource_error` | `error` | `error.source=resource`、`url.full`、`html.tag` |
+| `browser.web_vital` | `vital` | `vital.metric`、`vital.value`、`vital.rating`、`vital.id` 和 attribution |
+| `action.click` | `action` | `action.loading_time`、目标和 `action.frustration.type`；不含资源/错误/长任务计数 |
+| `action.custom` | `action` | 手动 Action 名称和属性 |
+| `browser.blank_screen` | `error` | 白屏采样点、比例、根节点和原因 |
+| `browser.long_task` | `long_task` | Long Task/LoAF 原始耗时；LoAF 脚本和旧 API attribution span event；仅 LoAF 带原生 blocking duration |
+| `csp.violation` | `error` | CSP violation 原始字段；不做指纹或客户端节流 |
+| `browser.websocket` | `websocket` | `event.phase=connect\|open\|error\|close`、`websocket.connection.id`、关闭码；不采集消息 |
+| `custom.<name>` | `custom` | 手动自定义事件属性和可选异常 |
+
+## View 本地语义
+
+`view.loading_time`、CLS、INP、Action Loading Time、挫败信号和白屏必须依赖浏览器活动窗口或 DOM/Performance API，在 SDK 本地计算后作为事件语义上报。View 的每次 start/update/end 都增加 `view.version`；服务端应按 `view.id + view.version` 幂等合并，并容忍乱序到达。
+
+## 服务端派生要求
+
+- 使用 `event.id` 去重。
+- 通过 `session.id`、`view.id`、`action.id` 关联事件。
+- 从原始事件计算 View/Session 时长、资源/错误/Action 数量和错误率。
+- 从 `vital.value`、资源/长任务耗时计算 Histogram 与分位数。
+- 在服务端生成错误指纹、错误组和风暴控制，不在浏览器丢弃原始错误。

package/skills/bk-rum-otele/references/transport-sampling.md

@@ -2,9 +2,9 @@
 
 # 传输与采样
 
-## Endpoint
+## 单一 Endpoint
 
-`transport.endpoint` 是可选根地址。未配置独立地址的已开启信号会基于它生成 `/v1/rum`、`/v1/metrics`、`/v1/logs`；单信号 `endpoint` 是完整 URL，不再拼接路径。
+`transport.endpoint` 是必填根地址，SDK 去掉末尾斜杠后拼接 `/v1/rum`。没有 `/v1/metrics`、`/v1/logs` 或独立信号开关。
 
 ```ts
 new BkOpenTelemetry({
@@ -12,54 +12,20 @@ new BkOpenTelemetry({
   transport: {
     endpoint: 'https://collector.example.com',
     token: 'report-token',
-    signals: {
-      traces: {
-        endpoint: 'https://trace.example.com/v1/rum',
-        processor: 'batch',
-        batch: {
-          maxQueueSize: 2048,
-          maxExportBatchSize: 512,
-          scheduledDelayMillis: 5000,
-          exportTimeoutMillis: 30000,
-        },
-      },
-      metrics: { endpoint: 'https://metric.example.com/v1/metrics', intervalMillis: 60_000 },
-      logs: { endpoint: 'https://log.example.com/v1/logs' },
+    processor: 'batch',
+    batch: {
+      maxQueueSize: 2048,
+      maxExportBatchSize: 512,
+      scheduledDelayMillis: 5000,
+      exportTimeoutMillis: 30000,
     },
+    timeoutMillis: 10_000,
+    concurrencyLimit: 10,
   },
 });
 ```
 
-## 独立信号开关
-
-三类信号默认全部开启。设为 `false` 时，不创建对应 exporter、processor 或 metric reader：
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'trace-only-demo' },
-  transport: {
-    signals: {
-      traces: { endpoint: 'https://trace.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
-    },
-  },
-});
-```
-
-校验规则：
-
-- 至少开启一种信号，三类不能全部为 `false`。
-- 每个开启信号必须有独立 endpoint，或能回退到根 `transport.endpoint`。
-- 关闭 Trace 后不记录 Span，也不会向 `allowedTracingUrls` 注入 `traceparent`。
-- 关闭 Metric 后不启动周期导出定时器。
-- 关闭 Log 不影响 Session/View 上下文维护，但不会产生 Session、View Snapshot、HTTP body 等 Log。
-
-只开启 Metric 时没有精确 `view.id` 下钻链路；需要从指标定位具体 View 时，至少开启 Trace。
-
-请求头优先级：`token` 生成的 Authorization < `transport.headers` < 单 signal `headers`。
-
-浏览器 OTLP HTTP exporter 负责实际传输，SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。`shutdown()` 会先结束 View 和插件，再 flush final Snapshot，最后关闭 provider。
+`token` 生成默认 `Authorization: Bearer <token>`，显式 `headers` 可覆盖它。SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。
 
 ## Session 级确定性采样
 
@@ -72,8 +38,7 @@ new BkOpenTelemetry({
 ```
 
 - `1` 表示全量，`0` 表示全部丢弃。
-- 决定由 `application.name + session.id` 的稳定 hash 得出。
-- 采样决定不写额外 storage；同一 Session 内 span/log/metric 决定一致。
-- Session 续期后使用新 ID 重新计算。
-
-Metric exporter 只接受带内部采样标记的数据点，并在传输前移除该标记。Metric 只保留低基数 `view.url_path_group`，精确 View 关联由 span/log/View Snapshot 的 `view.id` 提供。
+- 采样由 `application.name + session.id` 的稳定 hash 决定。
+- Session 轮换后使用新 ID 重新计算。
+- `session.sample_rate` 写入 Resource，供后端做采样率修正。
+- 未采样 Session 不创建可导出的 RUM Span。

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

@@ -17,9 +17,7 @@ new BkOpenTelemetry({
   },
   transport: {
     endpoint: 'http://localhost:4318',
-    signals: {
-      traces: { processor: 'simple' },
-    },
+    processor: 'simple',
   },
 });
 ```
@@ -27,7 +25,7 @@ new BkOpenTelemetry({
 检查点：
 
 - Collector 是否监听 `4318`。
-- 浏览器 Network 中是否有 `/v1/rum`、`/v1/metrics`、`/v1/logs` 请求。
+- 浏览器 Network 中是否有 `/v1/rum` 请求。
 - 是否被采样丢弃。
 - `enabled` 是否为 `false`。
 
@@ -131,28 +129,9 @@ new BkOpenTelemetry({
 });
 ```
 
-## HTTP body 没有数据
-
-请求/响应 body 默认关闭。需要采集时配置 `tracking.request.body`，并提供必填的 `redact`：
-
-```ts
-new BkOpenTelemetry({
-  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":"***"'),
-      },
-    },
-  },
-});
-```
+## HTTP Body 没有数据
 
-`capture` 默认就是 `errors`，成功请求不会产生 body Log；要采集成功请求需显式设为 `all`。如果仍然没有数据，依次检查 Content-Type 是否命中 `allowedContentTypes`、body 是否为支持的文本类型，以及 `redact` 是否返回了 `undefined`。FormData、ArrayBuffer 和二进制响应会跳过。
+这是预期行为：SDK 不读取或上报请求/响应 Body。
 
 ## WebSocket 采集异常
 
@@ -231,22 +210,16 @@ bkOT.reportAction({
 
 ## 可以只上报 traces，不上报 metrics/logs 吗？
 
-可以。将不需要的信号设为 `false`；根 endpoint 在所有已开启信号都配置独立地址时可以省略。
+SDK 固定只上报 RUM Trace，不创建 Metrics/Logs Provider，无需配置开关。
 
 ```ts
 new BkOpenTelemetry({
   application: { name: 'demo' },
-  transport: {
-    signals: {
-      traces: { endpoint: 'https://trace-gateway.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
-    },
-  },
+  transport: { endpoint: 'https://trace-gateway.example.com' },
 });
 ```
 
-三类信号不能全部关闭。关闭 Trace 后也不会注入 `traceparent`。
+Endpoint 会解析为 `https://trace-gateway.example.com/v1/rum`。
 
 ## 为什么不建议多个实例同时运行？
 

package/dist/core/metric.d.ts

@@ -1,2 +0,0 @@
-export declare const CLS_HISTOGRAM_BOUNDARIES: number[];
-export declare const DURATION_HISTOGRAM_BOUNDARIES: number[];

package/dist/core/signal.d.ts

@@ -1,3 +0,0 @@
-import type { BkOTRuntimeContext } from './plugin';
-export type BkOTSignal = 'logs' | 'metrics' | 'traces';
-export declare const shouldRecordSignal: (context: BkOTRuntimeContext, signal: BkOTSignal) => boolean;

package/dist/core/throttle.d.ts

@@ -1,20 +0,0 @@
-/**
- * 简易 djb2 字符串 hash。结果稳定、短（base36），足以区分常见 fingerprint 字符串组合。
- * 不是密码学安全 hash，仅用于事件聚合分组场景。
- */
-export declare const hashString: (input: string) => string;
-export interface ThrottleResult {
-    /** 是否允许本次上报 */
-    allowed: boolean;
-    /** 当前窗口内同 fingerprint 的触发序号（含本次） */
-    count: number;
-}
-/**
- * 时间窗节流：同一 key 在 windowMs 窗口内最多允许 maxPerWindow 次通过；
- * 超出则被拦截，但 `count` 仍累加，供调用方维护内部统计。
- *
- * 长会话场景下避免 records 无限累积——按窗口长度节奏轻量清理一次过期 entry。
- */
-export declare const createThrottle: (windowMs: number, maxPerWindow: number) => {
-    allow(key: string): ThrottleResult;
-};

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

@@ -1,15 +0,0 @@
-import type { BkOTRequestBodyConfig, BkOTRequestContext, BkOTRequestEvent } from '../core/config';
-import type { BkOTRuntimeContext } from '../core/plugin';
-import type { Span } from '@opentelemetry/api';
-interface CaptureRequestBodyLogOptions {
-    bodyConfig: BkOTRequestBodyConfig;
-    domainContext: BkOTRequestContext;
-    event: BkOTRequestEvent;
-    fetchRequest?: Request | RequestInit;
-    occurredAt?: number;
-    runtimeContext: Pick<BkOTRuntimeContext, 'emitLog'>;
-    span: Span;
-}
-export declare const prepareFetchRequestBodySource: (request: Request | RequestInit) => Request | RequestInit | undefined;
-export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, occurredAt, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
-export {};