@blueking/open-telemetry 0.0.21 → 0.0.22

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

@@ -6,43 +6,43 @@
 
 ## 总览
 
-| 能力 | 配置入口 | 默认 | 浏览器入口 | Trace | Metric | Log |
-| --- | --- | --- | --- | --- | --- | --- |
-| Session | `session` | 必选基础能力 | `localStorage`、用户活动、页面可见性 | — | — | `session.start` / `session.rotate` |
-| View | `tracking.view` | 自动模式 | Navigation Timing、History、hash、BFCache、DOM Mutation | `browser.view` | `browser.view.loading_time` | `browser.view` Snapshot |
-| Fetch/XHR | `tracking.request` | 开 | `fetch`、`XMLHttpRequest`、Resource Timing | `browser.resource` | — | 可选 `browser.request.body` |
-| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` | — | — |
-| JS / Promise / 资源错误 | `tracking.error` | 开 | `error`、`unhandledrejection` | 三类 `browser.*error` | — | — |
-| Web Vitals | `tracking.webVitals` | 开 | `web-vitals`、Layout Shift、Event Timing | `browser.web_vital` | 两个 Histogram | — |
-| Action | `tracking.action` | 开 | click、DOM、请求与活动总线 | `action.click` | — | — |
-| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` | — | — |
-| 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | — | — |
-| 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` | `browser.blank_screen.count` | — |
-| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | Resource 与运行时公共属性 | — | Resource 与运行时公共属性 |
-| Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` | 三个聚合指标 | — |
-| WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `websocket.connect` | 四个聚合指标 | error / close |
-| CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` | — | — |
-| 自定义插件 | `extensions.plugins` / `use()` | 无 | 由插件决定 | 支持 | 无稳定公共辅助 API | 推荐 `emitLog()` |
-| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | 由 instrumentation 决定 | 支持 | 无稳定支持 | 取决于实现 |
-
-“默认开”表示获得 Consent 且 SDK 已启动后启用。是否真正导出还受 `enabled`、Session 采样、Session/View 有效性和单信号开关控制。
+| 能力 | 配置入口 | 默认 | 浏览器入口 | 原始 RUM Span |
+| --- | --- | --- | --- | --- |
+| Session | `session` | 必选基础能力 | `localStorage`、用户活动、页面可见性 | `browser.session` start/rotate/end |
+| View | `tracking.view` | 自动模式 | Navigation Timing、History、hash、BFCache、DOM Mutation | `browser.view` start/update/end |
+| Fetch/XHR | `tracking.request` | 开 | `fetch`、`XMLHttpRequest`、Resource Timing | `browser.resource` |
+| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` |
+| JS / Promise / 资源错误 | `tracking.error` | 开 | `error`、`unhandledrejection` | 三类 `browser.*error` |
+| Web Vitals | `tracking.webVitals` | 开 | `web-vitals`、Layout Shift、Event Timing | `browser.web_vital` |
+| Action | `tracking.action` | 开 | click、DOM、请求与活动总线 | `action.click` |
+| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` |
+| 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` |
+| 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` |
+| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | Resource 与运行时公共属性 |
+| Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` |
+| WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `browser.websocket` connect/open/error/close |
+| CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` |
+| 自定义插件 | `extensions.plugins` / `use()` | 无 | 由插件决定 | `context.startSpan()` |
+| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | 由 instrumentation 决定 | 支持 |
+
+“默认开”表示获得 Consent 且 SDK 已启动后启用。是否真正导出还受 `enabled`、Session 采样和 Session/View 有效性控制。
 
 ## 能力边界
 
 ### SDK 直接负责
 
 - 创建和轮换 Session，划分初始加载、SPA、BFCache、手动和 Session 续期 View。
-- 统一 patch Fetch/XHR；请求 span、活动计数、Trace Header、Resource Timing 和 Body 采集共用同一生命周期。
+- 统一 patch Fetch/XHR；请求 span、活动追踪、Trace Header 和 Resource Timing 共用同一生命周期。
 - 把浏览器事件归一为 `span_type`、`span_subtype`、`result`、`error_type` 等字段。
-- 自动为 Span/Log 关联 `session.id`、`view.id`，为 Metric 保留低基数 `view.url_path_group`。
+- 自动为 Span 关联 `session.id`、`view.id` 和 `action.id`。
 - 在 exporter 前执行采样、有效上下文、自上报请求和 `tracking.beforeSend` 过滤。
 
 ### SDK 不负责
 
 - 不聚合 `session.duration`、影响用户数、地理信息、Trace 关键路径等后端指标。
 - 不自动判断业务字段是否敏感，也不 hash `user.id`。
-- 不默认采集 HTTP 请求/响应 Body。
-- 不把唯一的 `session.id`、`view.id`、`action.id` 放入 Metric labels。
+- 不采集 HTTP 请求/响应 Body。
+- 不在浏览器生成 Counter、Histogram、分位数、错误指纹或跨事件计数。
 - 不保证浏览器未暴露的数据，例如缺少 `Timing-Allow-Origin` 的跨域资源网络阶段。
 
 ## 默认开启与关闭
@@ -84,13 +84,11 @@ Session 与 View 是导出有效性边界，不提供关闭开关。`tracking.vi
 
 | 能力 | 主要成本/风险 | 建议 |
 | --- | --- | --- |
-| `session.sampleRate` | 决定三类信号总体数据量 | 按应用容量设置；排障临时设为 `1` |
-| Metric 自定义维度 | 高基数会放大时序数量 | 只放应用、租户类别、路由模板等低基数字段 |
-| Request Body | 可能包含凭证、个人数据，且增加网络体积 | 默认关闭；开启时限制类型/大小并强制脱敏 |
+| `session.sampleRate` | 决定 RUM Span 总体数据量 | 按应用容量设置；排障临时设为 `1` |
 | Action 文本命名 | DOM 文本可能包含用户输入 | 保持 `nameCollection: 'explicit'`，关键元素使用 `data-bk-action-name` |
 | Device 持久 ID | 支持跨 Session 关联 | 默认不持久化；需取得合规依据后再开启 |
 | Long Task | 产生 Span 与脚本归因信息 | 仅性能分析场景开启，结合采样控制 |
-| WebSocket | Proxy 全局构造器并统计消息字节 | 同页面单实例；不采集消息内容 |
+| WebSocket | Proxy 全局构造器并监听连接生命周期 | 不包裹 `send()`，不采集消息内容、数量或字节数 |
 
 ## 下一步
 

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

@@ -2,122 +2,30 @@
 
 # 核心概念
 
-理解这些概念后，再看配置和插件会更顺畅。
+## 单一原始事件通道
 
-## 三类信号
+SDK 只使用 OpenTelemetry Trace：浏览器事实和本地体验语义都编码为 RUM Span，通过 `/v1/rum` 上报。浏览器不创建 Counter、Histogram 或 Log；聚合由服务端完成。
 
-`@blueking/open-telemetry` 同时使用 OpenTelemetry 的三类信号：
+## Session、View、Action
 
-- Trace：用于描述一次有起止时间的行为，例如页面访问、接口请求、资源加载、用户点击、长任务。
-- Metric：用于描述可聚合的数值，例如 Web Vitals、长任务数量、WebSocket 消息大小、空白屏结果。
-- Log：用于描述离散事件或诊断信息，例如 Session 生命周期、View Snapshot、请求 Body 和 WebSocket 状态。
+- `session.id` 关联一次访问会话，采样以 Session 为边界。
+- `view.id` 关联初始页面、SPA 路由、BFCache 或手动 View。
+- `action.id` 关联一次用户动作活动窗口。
+- `user.id` 由接入方提供，SDK 原样透传。
 
-示例：手动创建一个业务 span。
+生命周期事件使用 `event.id`、`event.type`、`event.phase`、`event.timestamp`。View 额外使用 `view.version` 处理更新和乱序。
 
-```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'checkout-web' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
-
-const span = bkOT.startSpan('custom.checkout_submit', {
-  'biz.order_id': '202605270001',
-  'biz.channel': 'pc',
-});
-
-span.end();
-```
-
-## Session、View、User
-
-SDK 会维护运行时公共上下文，并自动挂到后续 span/log 上：
-
-- `user.id`：由接入方提供，SDK 原样透传，不 hash、不脱敏、不改写。
-- `session.id`：由 session 插件生成和轮换，用于关联同一次访问会话。
-- `view.id` / `view.name` / `view.url` / `view.url_path_group`：由 View 管理器维护，用于关联同一个页面或路由实例。
-
-示例：登录后更新用户上下文。
-
-```ts
-bkOT.setUser({
-  id: 'user-12345',
-});
-```
-
-示例：手动模式由业务路由系统创建 View。
-
-```ts
-// 前提：autoStart: false，且已经 await bkOT.start() 建立 Session。
-bkOT.startView({
-  name: '商品详情',
-  url: window.location.href,
-  attributes: { 'biz.owner': 'product-team' },
-});
-```
-
-## 内置采集与扩展
-
-SDK 将能力分为两类：
-
-1. 内置采集：`tracking.request` 使用 SDK 自有的统一 Fetch/XHR 生命周期，负责 patch 浏览器 API、创建 `browser.resource` CLIENT Span、Trace Header 和请求 Performance Timing 匹配。
-2. RUM 插件：View、Session、`resource`、`error`、`webVitals`、`blankScreen`、`device` 等，负责主动产生 RUM 归一数据。
-
-用户交互统一由 SDK 的 `action` 插件采集。接入额外 instrumentation 时，应避免再注册覆盖 Fetch/XHR 或用户交互的探针，以免重复上报。
+## 本地计算边界
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    action: {
-      actionNameAttribute: 'data-bk-action-name',
-      maxDuration: 10000,
-    },
-  },
-});
-```
+SDK 只保留必须依赖浏览器本地状态的计算：CLS、INP、View Loading Time、Action Loading Time、挫败信号和白屏判断。错误分组、计数、分位数和跨事件聚合全部交给服务端。
 
 ## 采样
 
-`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件仍会维护必要的浏览器生命周期，但未命中时创建或导出路径会丢弃数据，`reportAction()` 和 `reportCustomEvent()` 直接返回。
-
-示例：生产环境按 10% 会话采样。
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  session: {
-    sampleRate: 0.1,
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-```
-
-## 数据归一
-
-SDK 会为 span 补充 RUM 归一字段，例如：
+`session.sampleRate` 使用 `application.name + session.id` 做确定性采样。采样率同时写入 Resource 的 `session.sample_rate`，供后端修正总体指标。
 
-- `span_type`：`document`、`resource`、`vital`、`error`、`longtask`、`action`、`route`、`custom`
-- `result`：`success`、`warning`、`error`、`timeout`、`abort`
+## 扩展
 
-示例：自定义 span 也可以复用归一字段构造器。
-
-```ts
-import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
-
-const span = bkOT.startSpan('custom.cache_warmup', {
-  ...buildRumSpanAttributes({
-    spanType: RUM_SPAN_TYPE.custom,
-    spanSubtype: 'cache_warmup',
-  }),
-});
-
-span.end();
-```
+自定义 RUM 插件使用 `context.startSpan()`，标准 OpenTelemetry instrumentation 通过 `extensions.instrumentations` 注册。避免重复注册 Fetch/XHR 或用户交互探针。
 
 # 内置采集与扩展
 
@@ -147,6 +55,6 @@ new BkOpenTelemetry({
 
 内置 Fetch/XHR 不再基于官方 instrumentation 叠加适配，而是由单一请求生命周期实现，避免重复 patch、重复活动计数及私有 `_addHeaders/_patchSend` 依赖。
 
-当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。Metric exporter 要求 SDK 内部采样标记，而包未公开对应 helper，因此第三方 instrumentation 产生的 Metric 默认会被过滤，不应作为已支持的扩展能力。
+当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。SDK 不创建 Metric Provider，第三方 instrumentation 的 Metric 不属于支持范围。
 
 扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。

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

@@ -2,7 +2,7 @@
 
 # 配置参考
 
-`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport` 必填；所有已启用信号必须能解析到有效 Endpoint。
+`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport.endpoint` 必填。
 
 ```ts
 import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
@@ -20,7 +20,7 @@ const bkOT = new BkOpenTelemetry(options);
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | `application` | `BkOTApplicationConfig` | 必填 | 应用 Resource 标识 |
-| `transport` | `BkOTTransportConfig` | 必填 | 三类 OTLP HTTP 导出链路 |
+| `transport` | `BkOTTransportConfig` | 必填 | 单一 RUM OTLP HTTP 导出链路 |
 | `session` | `BkOTSessionConfig` | `{ sampleRate: 1 }` | Session 存储和确定性采样 |
 | `tracking` | `BkOTTrackingConfig` | `{}` | 内置采集、View 与事件 Hook |
 | `context` | `BkOTContextConfig` | 无 | 初始用户与公共属性 Hook |
@@ -47,24 +47,15 @@ transport: {
   endpoint: 'https://collector.example.com',
   token: 'report-token',
   headers: { 'X-Tenant': 'blueking' },
-  signals: {
-    traces: {
-      endpoint: 'https://trace.example.com/v1/rum',
-      processor: 'batch',
-      batch: {
-        maxQueueSize: 2048,
-        maxExportBatchSize: 512,
-        scheduledDelayMillis: 5000,
-        exportTimeoutMillis: 30000,
-      },
-      timeoutMillis: 10_000,
-      concurrencyLimit: 10,
-    },
-    metrics: {
-      intervalMillis: 60_000,
-    },
-    logs: {},
+  processor: 'batch',
+  batch: {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5000,
+    exportTimeoutMillis: 30000,
   },
+  timeoutMillis: 10_000,
+  concurrencyLimit: 10,
 }
 ```
 
@@ -72,35 +63,17 @@ transport: {
 
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼默认信号路径 |
+| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼 `/v1/rum` |
 | `token` | `string` | 无 | 生成 `Authorization: Bearer <token>` |
-| `headers` | `Record<string,string>` | 无 | 所有信号的公共 Header |
-| `signals` | `SignalExportersInputConfig` | 三类开启 | 单信号开关和覆盖项 |
-
-默认路径：Trace `/v1/rum`、Metric `/v1/metrics`、Log `/v1/logs`。单信号 `endpoint` 是完整 URL，不再拼路径。
-
-Header 覆盖顺序为 `token` < 根 `headers` < 单信号 `headers`。同名字段由右侧配置覆盖。
-
-### 单信号字段
-
-| 字段 | Trace | Metric | Log | SDK 默认 |
-| --- | --- | --- | --- | --- |
-| `endpoint` | 支持 | 支持 | 支持 | 回退根 Endpoint |
-| `headers` | 支持 | 支持 | 支持 | 回退根 Header |
-| `timeoutMillis` | 支持 | 支持 | 支持 | 交给 OTel exporter |
-| `concurrencyLimit` | 支持 | 支持 | 支持 | 交给 OTel exporter |
-| `processor` | `'batch' \| 'simple'` | — | — | `batch` |
-| `batch` | `BkOTBatchConfig` | — | — | 交给 `BatchSpanProcessor` |
-| `intervalMillis` | — | number | — | `60_000` |
+| `headers` | `Record<string,string>` | 无 | RUM 请求 Header |
+| `timeoutMillis` | `number` | OTel 默认 | Exporter 超时 |
+| `concurrencyLimit` | `number` | OTel 默认 | Exporter 并发数 |
+| `processor` | `'batch' \| 'simple'` | `batch` | Span Processor 模式 |
+| `batch` | `BkOTBatchConfig` | OTel 默认 | BatchSpanProcessor 参数 |
 
 `batch` 支持 `maxQueueSize`、`maxExportBatchSize`、`scheduledDelayMillis`、`exportTimeoutMillis`。未提供时使用 OpenTelemetry `BatchSpanProcessor` 默认值。
 
-校验规则：
-
-- 三类信号不能全部为 `false`。
-- 每个已开启信号必须配置单独 Endpoint，或能回退到根 `transport.endpoint`。
-- 关闭 Trace 后不创建 Trace exporter/processor，不记录可导出的 Span，也不注入 `traceparent`。
-- 关闭 Metric 后不创建 reader；关闭 Log 后不创建 log processor，Request Body 配置也不会产生 Log。
+SDK 不提供 Logs/Metrics 开关或 Provider，所有 RUM 原始事件只走 `/v1/rum`。
 
 更多行为见[传输与采样](./transport-sampling.md)。
 
@@ -132,33 +105,23 @@ URL matcher 支持字符串包含、`RegExp` 或 `(url) => boolean`。字符串
 | --- | --- | --- | --- |
 | `excludedUrls` | matcher 或 matcher[] | 无 | 命中后不采集、不注入、不计入页面活动 |
 | `allowedTracingUrls` | matcher 或 matcher[] | 无 | W3C Trace Context 显式白名单；同源请求也必须命中，推荐 URL-aware 函数 |
-| `beforeSend` | `(event, context) => boolean \| void` | 无 | 修改请求属性；返回 `false` 丢弃 Span，并跳过该请求的 Body Log |
-| `body` | `BkOTRequestBodyConfig` | 关闭 | 请求/响应 Body Log |
-
-Request Body：
-
-| 字段 | 类型 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `capture` | `'errors' \| 'all'` | `errors` | 错误包括状态未知、0 或 `>=400` |
-| `maxSize` | `number` | `10 * 1024` | 每个最终 Body 的最大字符数；无效值回退默认 |
-| `allowedContentTypes` | `(string \| RegExp)[]` | text、json、urlencoded、graphql | Response 必须命中；无 Content-Type 的 Request 允许读取 |
-| `redact` | `(payload) => string \| undefined` | 必填 | 返回脱敏文本；`undefined` 跳过当前 Body |
+| `beforeSend` | `(event, context) => boolean \| void` | 无 | 修改请求属性；返回 `false` 丢弃 Span |
 
-默认不采集 Body。Body 只在 Log 信号开启时生效，不支持 FormData、ArrayBuffer 等不可安全文本化的内容。
+SDK 不读取或上报请求/响应 Body。
 
 ## tracking 内置能力
 
 | 字段 | 类型 | 默认 | 参数 |
 | --- | --- | --- | --- |
 | `resource` | `boolean` | `true` | 无；`false` 只关闭静态资源 Span，Resource Observer 仍服务请求 timing/活动 |
-| `error` | `boolean \| BkOTErrorPluginOptions` | `true` | `windowMs=60_000`、`maxPerWindow=5` |
+| `error` | `boolean` | `true` | 无；每条原始错误都生成 Span |
 | `webVitals` | `boolean` | `true` | 无 |
 | `blankScreen` | `boolean \| BkOTBlankScreenPluginOptions` | `true` | 见下表 |
 | `device` | `boolean \| BkOTDevicePluginOptions` | `true` | 见下表 |
 | `action` | `boolean \| BkOTActionPluginOptions` | `true` | 见下表 |
-| `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50`、`warningThreshold=100` ms |
+| `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50` ms |
 | `websocket` | `boolean` | `false` | 无 |
-| `cspViolation` | `boolean` | `false` | 无，内置同指纹 60 秒最多 5 条 |
+| `cspViolation` | `boolean` | `false` | 无；每条 CSP 违规都生成 Span |
 
 Blank Screen：
 
@@ -168,7 +131,7 @@ Blank Screen：
 | `threshold` | `0.8` | 九点采样的空白比例，限制到 `0..1` |
 | `checkDelay` | `1000` ms | 页面活动稳定后的首次检查延迟 |
 | `confirmationDelay` | `200` ms | 两次候选白屏的确认间隔 |
-| `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会替换内置数组 |
+| `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会追加到内置数组 |
 
 Action：
 
@@ -196,7 +159,7 @@ tracking: {
 }
 ```
 
-该 Hook 在 Span/Log 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning。它不处理 Metric；请求专属逻辑优先使用 `tracking.request.beforeSend`。
+该 Hook 在 Span 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning；请求专属逻辑优先使用 `tracking.request.beforeSend`。
 
 ## context
 
@@ -204,11 +167,10 @@ tracking: {
 | --- | --- | --- | --- |
 | `user.id` | `string` | 无 | SDK 原样写入 `user.id` |
 | `attributes.page` | `() => Attributes` | host/path | 页面、请求、错误、Action 等事件属性 |
-| `attributes.metric` | `() => Attributes` | `{}` | 内置 Metric 的低基数自定义维度 |
 | `attributes.error` | `() => Attributes` | `{}` | Error Span 附加属性 |
 | `attributes.custom` | `() => Attributes` | `{}` | `reportCustomEvent()` 附加属性 |
 
-自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。Metric Hook 禁止放用户 ID、订单 ID、完整 URL 等高基数字段。
+自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。
 
 ## privacy
 
@@ -216,7 +178,7 @@ tracking: {
 | --- | --- | --- | --- |
 | `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
 | `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
-| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span/Log 和内置插件属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span 和内置插件属性脱敏 |
 
 第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
 
@@ -238,11 +200,8 @@ new BkOpenTelemetry({
     endpoint: 'https://collector.example.com',
     token: 'token',
     headers: {},
-    signals: {
-      traces: { processor: 'batch', batch: {} },
-      metrics: { intervalMillis: 60_000 },
-      logs: {},
-    },
+    processor: 'batch',
+    batch: {},
   },
   session: { sampleRate: 1 },
   tracking: {

package/skills/bk-rum-otele/references/custom-plugin.md

@@ -52,9 +52,9 @@ await bkOT.start();
 
 ## 使用 runtime context
 
-`init(context)` 中可以访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()`、`getRuntimeAttributes()` 等能力。
+`init(context)` 中可以访问 `tracer`、`startSpan()`、`getRuntimeAttributes()` 等能力。
 
-优先使用 `context.startSpan()` 和 `context.emitLog()`：它们会合并事件发生时的运行时上下文并应用 SDK 脱敏。直接调用 `context.logger.emit()` 的 Log 不会自动获得这些能力，可能因缺少有效 Session/View 被导出过滤器丢弃。
+优先使用 `context.startSpan()`：它会合并事件发生时的运行时上下文并应用 SDK 脱敏。
 
 ```ts
 let teardownVisibility = () => {};
@@ -63,13 +63,12 @@ const visibilityPlugin = createPlugin({
   name: 'visibility-change',
   init(context) {
     const onVisibilityChange = () => {
-      context.emitLog({
-        severityText: 'INFO',
-        body: 'document.visibilitychange',
-        attributes: {
+      const occurredAt = Date.now();
+      context.startSpan('document.visibilitychange', {
+          'event.type': 'custom',
+          'event.timestamp': occurredAt,
           'document.visibility_state': document.visibilityState,
-        },
-      });
+      }, { startTime: occurredAt }).end(occurredAt);
     };
 
     document.addEventListener('visibilitychange', onVisibilityChange);
@@ -164,10 +163,8 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 await bkOT.start();
 ```
 
-> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束；第三方 instrumentation Metric 因没有公开采样 helper，默认会被过滤。
-
-## 自定义 Metric 注意事项
+> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束。
 
-内置 Metric 会主动带上内部采样标记与低基数 `view.url_path_group`。当前包没有导出稳定的自定义 Metric helper 或采样属性；自定义插件直接调用 `context.meter` 创建的数据点默认无法通过 `FilteringMetricExporter`。不要依赖内部 `bk.rum.sampled` 字段，也不要把 `context.getRuntimeAttributes()` 整体复制到 Metric attributes，否则还会把唯一的 `session.id`、`view.id`、`action.id` 变成高基数 labels。
+## 自定义信号边界
 
-如果需求是记录一次具体业务行为，使用 Span 或 Log。确实需要自定义 Metric 时，应先为 SDK 设计并公开低基数、采样安全的 Metric API，而不是绕过当前过滤约束。
+SDK 插件上下文不提供 Meter、Logger 或 `emitLog()`。具体业务行为使用 Span；计数、分布和分位数由服务端从 Span 派生。

package/skills/bk-rum-otele/references/data-model.md

@@ -2,110 +2,38 @@
 
 # 数据模型
 
-SDK 的数据模型遵循“浏览器 SDK 负责低成本原始数据和单事件归一，跨事件聚合交给后端”的边界。
+数据模型遵循“浏览器上报原始事件，服务端派生聚合”的边界。
 
-## 分层模型
+## 四层字段
 
-1. OpenTelemetry 原生字段：trace、span、resource、metric、log 的标准字段。
-2. RUM 归一字段：`span_type`、`span_subtype`、`result`、`error_type` 等。
-3. 运行时上下文：`user.id`、`session.id`、`view.id`、`view.url`、`view.url_path_group` 等。
-4. 后端派生字段：session/view duration、count、地理信息、影响用户数、trace tree 分析等。
+1. OpenTelemetry Resource/Span 标准字段。
+2. RUM 事件字段：`event.id/type/phase/timestamp`。
+3. 关联上下文：`user.id`、`session.id`、`view.id`、`action.id`。
+4. 单事件语义：`span_type`、`span_subtype`、`result`、`error_type` 和插件原始字段。
 
 ## Span 类型
 
-| 类型 | 说明 | 常见来源 |
-| --- | --- | --- |
-| `document` | 文档加载 | View 管理器（初始加载） |
-| `resource` | Fetch/XHR 请求与静态资源 | request、resource 采集 |
-| `vital` | Web Vitals | webVitals 插件 |
-| `error` | 浏览器与体验错误 | error 插件、blankScreen 插件、cspViolation 插件 |
-| `longtask` | 长任务 | longTask 插件 |
-| `action` | 用户动作 | action 插件、reportAction |
-| `route` | 路由切换 | View 管理器（SPA/手动 View） |
-| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件；`reportCustomEvent({ error })` 仍属于此类型 |
+`document`、`route`、`session`、`resource`、`vital`、`error`、`longtask`、`action`、`websocket`、`custom`。
 
-> 每种 span 的具体 span 名、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
+## 浏览器直接产生
 
-示例：自定义业务事件归一为 `custom`。
+- Session/View/Action 标识和生命周期；
+- URL、HTTP 状态、资源体积与 Resource Timing；
+- Error/CSP 原始字段和标准 exception event；
+- Web Vitals 值与 attribution；
+- WebSocket 连接生命周期；
+- 设备、浏览器、系统和网络上下文。
 
-```ts
-import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
+## 浏览器本地语义
 
-const span = bkOT.startSpan('custom.search', {
-  ...buildRumSpanAttributes({
-    spanType: RUM_SPAN_TYPE.custom,
-    spanSubtype: 'search',
-  }),
-  'biz.keyword_length': 6,
-});
+CLS、INP、View Loading Time、Action Loading Time、挫败信号和白屏判断依赖 DOM、Performance API 或页面活动窗口，由 SDK 计算后上报。
 
-span.end();
-```
+## 服务端派生
 
-## Result 与 Error Type
+- Session/View duration 和各类 count；
+- 错误率、错误 fingerprint/group；
+- Histogram 与 P50/P75/P95/P99；
+- 影响用户数、地理信息和采样修正；
+- 迟到/乱序关联和 View 版本合并。
 
-`result` 描述事件结果，取值包括：
-
-- `success`
-- `warning`
-- `error`
-- `timeout`
-- `abort`
-
-请求 Resource Span 会根据状态码推导结果：`408`、`504` 为 timeout，`>= 400` 为 error，其余为 success。
-
-`reportCustomEvent({ error })` 会设置 `result=error` 和 OpenTelemetry Span Status ERROR，但不会把 `span_type` 从 `custom` 改为 `error`。`span_type` 描述事件类别，`result` 描述结果，两者不要混用。
-
-```ts
-bkOT.reportCustomEvent({
-  name: 'upload_timeout',
-  error: new Error('request timeout'),
-  attributes: {
-    'biz.file_size': 1024 * 1024,
-  },
-});
-```
-
-## SDK 直接采集
-
-以下字段由浏览器 API、接入方配置或 SDK 运行期上下文直接提供：
-
-- 应用与环境：`service.name`、`deployment.environment.name`、`service.version`
-- 用户与会话：`user.id`、`session.id`
-- View：`view.id`、`view.name`、`view.url`、`view.url_path_group`、`view.loading_type`
-- 终端信息：`device.type`、`browser.name`、`browser.version`、`os.name`、`network.effective_type`
-- HTTP / Resource：`http.request.method`、`http.response.status_code`、`url.full`、`resource.size`
-- Web Vitals：`vital.metric`、`vital.value`、`vital.rating`
-- Error Span 属性：`exception.message_short`、`exception.stack_top_frame`、`exception.fingerprint`；完整异常位于标准 `exception` Span Event
-
-## 后端派生
-
-以下字段不在浏览器 SDK 中直接生成：
-
-- Session 聚合：`session.duration`、`view_count`、`trace_count`、`error_count`、`action_count`
-- View 聚合：`view.duration`、`request_count`、`resource_count`、`longtask_count`
-- Trace 树：`relative_start`、`hierarchy_level`、`parent_span_name`、`is_critical_path`
-- 影响面：`affected_user_count`
-- 地理信息：`geo.country`、`geo.city`
-
-## 高基数字段策略
-
-高基数字段可以进入 span/log，但不应进入 metric 维度。比如订单 ID、用户输入、完整 URL query 都应谨慎使用。
-
-```ts
-bkOT.reportCustomEvent({
-  name: 'order_submit',
-  attributes: {
-    'biz.order_id': '202605270001',
-    'biz.order_type': 'normal',
-  },
-});
-```
-
-上例中 `biz.order_id` 适合放在 span/log 中定位单次问题，不适合作为 metric 维度做长期聚合。
-
-## Metric 与 View 的关联
-
-Metric 不携带唯一的 `view.id`、`session.id` 或 `action.id`，只保留 `view.url_path_group`、`view.loading_type` 等低基数维度。这样可以按页面类型聚合，又不会因为每次访问生成新的时序而造成基数爆炸。
-
-需要定位某一次 View 时，使用同一指标对应的 span（例如 `browser.web_vital`）或 View Snapshot Log；它们携带精确的 `session.id` 和 `view.id`。后端需要从聚合指标跳转到样本时，应通过 exemplar 或 span/log 派生聚合建立关联，而不是把 `view.id` 放进 metric labels。
+服务端应使用 `event.id` 去重，使用 `view.id + view.version` 幂等处理 View 更新。

package/skills/bk-rum-otele/references/getting-started.md

@@ -2,7 +2,7 @@
 
 # 简介
 
-`@blueking/open-telemetry` 是面向浏览器真实用户监控（RUM）的 OpenTelemetry 封装 SDK。它基于 OpenTelemetry Web SDK，将页面访问、资源加载、接口请求、JavaScript 错误、Web Vitals、空白屏、会话、用户动作等浏览器事件统一转成 trace、metric、log 三类信号，并通过 OTLP HTTP 协议上报。
+`@blueking/open-telemetry` 是面向浏览器真实用户监控（RUM）的 OpenTelemetry 封装 SDK。它将页面访问、资源加载、接口请求、JavaScript 错误、Web Vitals、空白屏、会话和用户动作等浏览器事件统一转成原始 RUM Span，通过单一 OTLP HTTP 通道上报。
 
 ## 适合解决什么问题