@blueking/open-telemetry 0.0.14 → 0.0.16

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

@@ -2,7 +2,9 @@
 
 # 隐私与公共属性
 
-RUM 数据常包含 URL、用户标识、接口路径、错误信息和业务属性。SDK 不会替接入方猜测哪些字段敏感，因此提供 `privacy` 和 `attributes` 两类入口，由业务显式控制。
+RUM 数据常包含 URL、用户标识、接口路径、错误信息和业务属性。SDK 不会替接入方猜测哪些字段敏感，因此提供 `privacy` 和 `context` 两类入口，由业务显式控制。
+
+以下片段聚焦对应配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
 
 ## URL 脱敏
 
@@ -22,7 +24,7 @@ new BkOpenTelemetry({
 
 ## 属性脱敏
 
-`privacy.redactAttributes` 会在 SDK 自定义插件 emit 前过滤属性，适合删除 authorization、手机号、邮箱等字段。
+`privacy.redactAttributes` 会处理通过 SDK `startSpan()`、`emitLog()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。
 
 ```ts
 new BkOpenTelemetry({
@@ -38,9 +40,13 @@ new BkOpenTelemetry({
 });
 ```
 
+第三方 OpenTelemetry instrumentation 自己生成的 Span 属性不保证经过这一构造路径。需要统一清理第三方 Span 时，在 `tracking.beforeSend` 做最终兜底；该 Hook 作用于 Span/Log，不作用于 Metric。
+
+`redactAttributes` 应返回完整可用的属性对象，不要只返回被修改的单个字段。
+
 ## 公共属性
 
-`attributes` 提供四类 hook：
+`context.attributes` 提供四类 hook：
 
 - `page`：页面、动作、错误等需要页面上下文的事件。
 - `metric`：metric 维度，必须避免高基数字段。
@@ -49,20 +55,22 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  attributes: {
-    page: () => ({
-      'biz.space_id': window.__BK_SPACE_ID__,
-      'biz.project_id': window.__BK_PROJECT_ID__,
-    }),
-    metric: () => ({
-      'biz.app_code': 'bk-monitor',
-    }),
-    error: () => ({
-      'biz.release_channel': window.__BK_RELEASE_CHANNEL__,
-    }),
-    custom: () => ({
-      'biz.scene': 'checkout',
-    }),
+  context: {
+    attributes: {
+      page: () => ({
+        'biz.space_id': window.__BK_SPACE_ID__,
+        'biz.project_id': window.__BK_PROJECT_ID__,
+      }),
+      metric: () => ({
+        'biz.app_code': 'bk-monitor',
+      }),
+      error: () => ({
+        'biz.release_channel': window.__BK_RELEASE_CHANNEL__,
+      }),
+      custom: () => ({
+        'biz.scene': 'checkout',
+      }),
+    },
   },
 });
 ```
@@ -73,26 +81,29 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  user: {
-    id: hashUserId(window.__BK_USER__?.id),
+  context: {
+    user: {
+      id: hashUserId(window.__BK_USER__?.id),
+    },
   },
 });
 ```
 
-## HTTP body 脱敏
+## 请求数据边界
 
-`httpBody` 默认关闭。开启后只在错误路径采集请求/响应 body，并支持 `redact`。
+SDK 默认不采集请求/响应 body。显式开启 `request.body` 时必须提供 `redact`，建议保持默认的 `capture: 'errors'`，并限制 Content-Type 和最大长度。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    httpBody: {
-      maxBodySize: 4096,
-      redact: ({ body, contentType, type }) => {
-        if (contentType?.includes('application/json')) {
+  tracking: {
+    request: {
+      body: {
+        capture: 'errors',
+        maxSize: 4096,
+        allowedContentTypes: ['application/json'],
+        redact: ({ body }) => {
           return body.replace(/"password"\s*:\s*"[^"]+"/g, '"password":"***"');
-        }
-        return type === 'request' ? '[request body redacted]' : body;
+        },
       },
     },
   },
@@ -105,12 +116,14 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  route: {
-    getPathGroup: url => {
-      const { pathname } = new URL(url, window.location.href);
-      return pathname
-        .replace(/\/\d+/g, '/:id')
-        .replace(/\/[0-9a-f]{24}/g, '/:objectId');
+  tracking: {
+    view: {
+      getPathGroup: url => {
+        const { pathname } = new URL(url, window.location.href);
+        return pathname
+          .replace(/\/\d+/g, '/:id')
+          .replace(/\/[0-9a-f]{24}/g, '/:objectId');
+      },
     },
   },
 });

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,45 +17,43 @@
 
 | 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 时结束 |
+| `browser.resource` | `resource` | Fetch/XHR request 采集 | `resource.type=fetch\|xhr`、`resource.url`、`resource.method`、`resource.status_code`、网络阶段属性 | 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` |
-| `custom.<name>` | `custom` | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时附 `exception.*` |
+| `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、设置错误 Status/Result，`span_type` 仍为 `custom` |
 
 ## 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'` 的成功请求） | Fetch/XHR request patch（仅显式配置 `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/transport-sampling.md

@@ -0,0 +1,79 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 传输与采样
+
+## Endpoint
+
+`transport.endpoint` 是可选根地址。未配置独立地址的已开启信号会基于它生成 `/v1/rum`、`/v1/metrics`、`/v1/logs`；单信号 `endpoint` 是完整 URL，不再拼接路径。
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'demo' },
+  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' },
+    },
+  },
+});
+```
+
+## 独立信号开关
+
+三类信号默认全部开启。设为 `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。
+
+## Session 级确定性采样
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  session: { sampleRate: 0.05 },
+});
+```
+
+- `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` 提供。