@blueking/open-telemetry 0.0.15 → 0.0.16

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

@@ -0,0 +1,100 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 能力矩阵
+
+本页回答四个问题：SDK 能采什么、默认是否启用、依赖哪个浏览器能力、最终上报什么。精确名称与属性请继续查[遥测参考](./telemetry-reference.md)。
+
+## 总览
+
+| 能力 | 配置入口 | 默认 | 浏览器入口 | 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 | 作为公共属性 | — | 作为公共属性 |
+| 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 有效性和单信号开关控制。
+
+## 能力边界
+
+### SDK 直接负责
+
+- 创建和轮换 Session，划分初始加载、SPA、BFCache、手动和 Session 续期 View。
+- 统一 patch Fetch/XHR；请求 span、活动计数、Trace Header、Resource Timing 和 Body 采集共用同一生命周期。
+- 把浏览器事件归一为 `span_type`、`result`、`error_type`、`duration_bucket`、`target_*` 等字段。
+- 自动为 Span/Log 关联 `session.id`、`view.id`，为 Metric 保留低基数 `view.url_path_group`。
+- 在 exporter 前执行采样、有效上下文、自上报请求和 `tracking.beforeSend` 过滤。
+
+### SDK 不负责
+
+- 不聚合 `session.duration`、影响用户数、地理信息、Trace 关键路径等后端指标。
+- 不自动判断业务字段是否敏感，也不 hash `user.id`。
+- 不默认采集 HTTP 请求/响应 Body。
+- 不把唯一的 `session.id`、`view.id`、`action.id` 放入 Metric labels。
+- 不保证浏览器未暴露的数据，例如缺少 `Timing-Allow-Origin` 的跨域资源网络阶段。
+
+## 默认开启与关闭
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'capability-demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: {
+    request: true,
+    resource: true,
+    error: true,
+    webVitals: true,
+    action: true,
+    blankScreen: true,
+    device: true,
+    longTask: false,
+    websocket: false,
+    cspViolation: false,
+  },
+});
+```
+
+Session 与 View 是导出有效性边界，不提供关闭开关。`tracking.view` 只配置自动/手动模式、稳定耗时和路由分组。
+
+## 浏览器降级行为
+
+| 条件 | 行为 |
+| --- | --- |
+| 无 `PerformanceObserver` 或不支持 `resource` | 跳过静态资源观察和请求网络阶段匹配；Fetch/XHR 本身仍可采集 |
+| 不支持 Long Animation Frames | Long Task 插件尝试回退 Long Tasks API |
+| 两种 Long Task API 都不支持 | 跳过 Long Task，不抛出业务异常 |
+| 跨域资源无 `Timing-Allow-Origin` | 只保留浏览器可见的总耗时/体积，不伪造网络阶段 |
+| 无 Network Information / UA-CH | 只写入可获得的设备字段 |
+| 无 `localStorage` 或访问失败 | Session/Device 持久化退回内存 |
+| 插件初始化抛错 | 隔离该插件；`debug: true` 时输出 warning，其余插件继续启动 |
+
+## 成本与隐私提示
+
+| 能力 | 主要成本/风险 | 建议 |
+| --- | --- | --- |
+| `session.sampleRate` | 决定三类信号总体数据量 | 按应用容量设置；排障临时设为 `1` |
+| Metric 自定义维度 | 高基数会放大时序数量 | 只放应用、租户类别、路由模板等低基数字段 |
+| Request Body | 可能包含凭证、个人数据，且增加网络体积 | 默认关闭；开启时限制类型/大小并强制脱敏 |
+| Action 文本命名 | DOM 文本可能包含用户输入 | 保持 `nameCollection: 'explicit'`，关键元素使用 `data-bk-action-name` |
+| Device 持久 ID | 支持跨 Session 关联 | 默认不持久化；需取得合规依据后再开启 |
+| Long Task | 产生 Span 与脚本归因信息 | 仅性能分析场景开启，结合采样控制 |
+| WebSocket | Proxy 全局构造器并统计消息字节 | 同页面单实例；不采集消息内容 |
+
+## 下一步
+
+- 配置每项能力：[配置参考](./configuration.md)
+- 理解启动与上报链路：[架构与数据流](./architecture.md)
+- 查看单个插件实现行为：[插件总览](./plugins.md)
+- 查看精确遥测名称和属性：[遥测参考](./telemetry-reference.md)

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

@@ -10,7 +10,7 @@
 
 - Trace：用于描述一次有起止时间的行为，例如页面访问、接口请求、资源加载、用户点击、长任务。
 - Metric：用于描述可聚合的数值，例如 Web Vitals、长任务数量、WebSocket 消息大小、空白屏结果。
-- Log：用于描述离散事件或诊断信息，例如 CSP 违规、Session 生命周期和 WebSocket 状态。
+- Log：用于描述离散事件或诊断信息，例如 Session 生命周期、View Snapshot、请求 Body 和 WebSocket 状态。
 
 示例：手动创建一个业务 span。
 
@@ -49,6 +49,7 @@ bkOT.setUser({
 示例：手动模式由业务路由系统创建 View。
 
 ```ts
+// 前提：autoStart: false，且已经 await bkOT.start() 建立 Session。
 bkOT.startView({
   name: '商品详情',
   url: window.location.href,
@@ -60,10 +61,10 @@ bkOT.startView({
 
 SDK 将能力分为两类：
 
-1. 内置采集：`tracking.request` 使用统一的 Fetch/XHR 生命周期实现，负责 patch 浏览器 API、创建 CLIENT Span、Trace Header 和请求 Performance Timing 匹配。
+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` 插件采集，避免与官方 user-interaction instrumentation 重复上报。
+用户交互统一由 SDK 的 `action` 插件采集。接入额外 instrumentation 时，应避免再注册覆盖 Fetch/XHR 或用户交互的探针，以免重复上报。
 
 ```ts
 new BkOpenTelemetry({
@@ -80,7 +81,7 @@ new BkOpenTelemetry({
 
 ## 采样
 
-`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件会维护必要的页面生命周期，但未命中时 sampler/processor 不导出其数据，`reportAction()` 和 `reportCustomEvent()` 直接丢弃。
+`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件仍会维护必要的浏览器生命周期，但未命中时创建或导出路径会丢弃数据，`reportAction()` 和 `reportCustomEvent()` 直接返回。
 
 示例：生产环境按 10% 会话采样。
 
@@ -150,4 +151,6 @@ new BkOpenTelemetry({
 
 内置 Fetch/XHR 不再基于官方 instrumentation 叠加适配，而是由单一请求生命周期实现，避免重复 patch、重复活动计数及私有 `_addHeaders/_patchSend` 依赖。
 
+当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。Metric exporter 要求 SDK 内部采样标记，而包未公开对应 helper，因此第三方 instrumentation 产生的 Metric 默认会被过滤，不应作为已支持的扩展能力。
+
 扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。

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

@@ -1,137 +1,191 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 配置总览
+# 配置参考
 
-SDK 入口按职责分为 `application`、`transport`、`session`、`tracking`、`context`、`privacy`、`extensions`。`application.name` 与 `transport` 必填；根 `transport.endpoint` 可由所有已开启信号的独立 endpoint 取代。
+`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport` 必填；所有已启用信号必须能解析到有效 Endpoint。
 
 ```ts
-const bkOT = new BkOpenTelemetry({
-  application: {
-    name: 'bk-monitor-web',
-    environment: 'production',
-    version: '1.4.2',
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-    token: 'report-token',
-    signals: {
-      traces: { processor: 'batch', batch: { maxQueueSize: 2048 } },
-      metrics: { intervalMillis: 60_000 },
-    },
-  },
-  session: {
-    sampleRate: 0.2,
-  },
-  tracking: {
-    view: {
-      tracking: 'auto',
-      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/\d+/g, '/:id'),
-    },
-    request: {
-      allowedTracingUrls: ['https://api.example.com'],
-      excludedUrls: [/\/health$/],
-    },
-    longTask: false,
-    websocket: false,
-  },
-  context: {
-    user: { id: 'user-12345' },
-    attributes: {
-      page: () => ({ 'biz.space_id': window.__BK_SPACE_ID__ }),
-    },
-  },
-  privacy: {
-    trackingConsent: 'granted',
-    redactAttributes: attributes => attributes,
-  },
-  extensions: {
-    plugins: [],
-    instrumentations: [],
-  },
-});
+import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
+
+const options: BkOTOptions = {
+  application: { name: 'bk-monitor-web' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+};
+
+const bkOT = new BkOpenTelemetry(options);
 ```
 
 ## 顶层配置
 
-| 配置 | 默认值 | 说明 |
-| --- | --- | --- |
-| `application.name` | 无 | 必填，写入 `service.name` |
-| `application.environment` | `production` | 写入 `deployment.environment.name` |
-| `application.version` | 无 | 写入 `service.version` |
-| `transport.endpoint` | 无 | 上报根地址；已开启信号没有独立 endpoint 时必填 |
-| `transport.signals.traces` | `{}` | Trace 配置；设为 `false` 关闭 |
-| `transport.signals.metrics` | `{}` | Metric 配置；设为 `false` 关闭 |
-| `transport.signals.logs` | `{}` | Log 配置；设为 `false` 关闭 |
-| `session.sampleRate` | `1` | Session 级确定性采样率 |
-| `tracking.view.tracking` | `auto` | 自动或手动 View |
-| `tracking.view.loadingTime` | `true` | 自动计算 View loading time |
-| `privacy.trackingConsent` | `granted` | 初始化授权状态 |
-| `enabled` | `true` | 是否启用 SDK |
-| `autoStart` | `true` | 构造后自动启动 |
-| `debug` | `false` | 输出 exporter 与插件调试信息 |
-
-Session 固定为 15 分钟无活动过期、4 小时最长生命周期。View 和 Session 是 RUM 关联边界，不能作为普通插件关闭。
-
-## 内置采集开关
-
-内置能力全部位于 `tracking`：
-
-| 配置 | 默认 | 说明 |
-| --- | --- | --- |
-| `view` | 开 | 初始加载、SPA、BFCache、手动 View |
-| `request` | 开 | Fetch/XHR 请求 span、Trace Header、body |
-| `resource` | 开 | 静态资源 span；PerformanceObserver 始终为 View 活动和请求 timing 服务 |
-| `error` | 开 | JS、Promise 与资源错误 |
-| `webVitals` | 开 | FCP/LCP/TTFB 及 View 级 CLS/INP |
-| `blankScreen` | 开 | 白屏检测 |
-| `device` | 开 | 浏览器、OS、屏幕与网络信息 |
-| `action` | 开 | 点击 Action 与活动聚合 |
-| `longTask` | 关 | LoAF/Long Task |
-| `websocket` | 关 | WebSocket 指标 |
-| `cspViolation` | 关 | CSP 违规 |
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `application` | `BkOTApplicationConfig` | 必填 | 应用 Resource 标识 |
+| `transport` | `BkOTTransportConfig` | 必填 | 三类 OTLP HTTP 导出链路 |
+| `session` | `BkOTSessionConfig` | `{ sampleRate: 1 }` | Session 存储和确定性采样 |
+| `tracking` | `BkOTTrackingConfig` | `{}` | 内置采集、View 与事件 Hook |
+| `context` | `BkOTContextConfig` | 无 | 初始用户与公共属性 Hook |
+| `privacy` | `BkOTPrivacyConfig` | Consent 已授权、默认 URL 脱敏 | 授权、URL 和属性脱敏 |
+| `extensions` | `BkOTExtensionsConfig` | 空数组 | 自定义 RUM 插件与 OTel instrumentation |
+| `enabled` | `boolean` | `true` | `false` 时 `start()` 不安装采集能力 |
+| `autoStart` | `boolean` | `true` | 构造后异步启动 |
+| `debug` | `boolean` | `false` | 输出 exporter 数据和可诊断 warning |
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    request: false,
-    blankScreen: false,
-    longTask: { threshold: 80 },
-  },
-});
-```
+## application
 
-## 请求配置
+| 字段 | 类型 | 默认 | Resource Attribute |
+| --- | --- | --- | --- |
+| `name` | `string` | 必填且非空 | `service.name` |
+| `environment` | `string` | `production` | `deployment.environment.name` |
+| `version` | `string` | 无 | `service.version` |
 
-`tracking.request.allowedTracingUrls` 是严格白名单，同源请求也必须命中后才注入 `traceparent`。关闭 Trace 时不会注入。`excludedUrls` 命中后完全不采集。SDK 自身已开启 signal endpoint 始终排除。
+SDK 还会固定写入 `rum.provider=blueking`、`rum.schema.version=1`、`telemetry.sdk.name=@blueking/open-telemetry` 和 `telemetry.sdk.language=webjs`。
+
+## transport
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'request-demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    request: {
-      allowedTracingUrls: [/https:\/\/api\.example\.com/],
-      excludedUrls: [/\/health(?:\?|$)/],
-      beforeSend: (event, context) => {
-        event.attributes['request.transport'] = context.type;
-        return true;
-      },
-      body: {
-        capture: 'errors',
-        redact: ({ body }) => body.replace(/token=[^&]+/g, 'token=***'),
+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: {},
   },
-});
+}
 ```
 
-跨域注入 Trace Header 可能触发 CORS 预检，服务端需要放行 `traceparent`。
+### 根字段
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼默认信号路径 |
+| `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` |
+
+`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。
+
+更多行为见[传输与采样](./transport-sampling.md)。
+
+## session
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `sampleRate` | `number` | `1` | Session 确定性采样；有限数值限制到 `0..1`，非有限值回退 `1` |
+| `storageKey` | `string` | 按应用名和 Endpoint host hash | Session localStorage key |
+
+Session 固定为 15 分钟无活动过期、4 小时最长生命周期，不开放超时配置。localStorage 不可用时退回进程内存。
+
+## tracking.view
 
-## 全局 beforeSend
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `tracking` | `'auto' \| 'manual'` | `auto` | 自动观察 History/hash，或由业务调用 `startView()` |
+| `loadingTime` | `boolean` | `true` | 计算 View 页面活动稳定耗时 |
+| `getPathGroup` | `(url) => string \| undefined` | URL pathname | 返回低基数 `view.url_path_group` |
+| `excludedActivityUrls` | matcher 或 matcher[] | 无 | 命中请求/资源不延长 View/Action 活动窗口 |
 
-`tracking.beforeSend` 在 span/log 进入 exporter 前执行，可修改属性或返回 `false` 丢弃事件。内部 `bk.rum.sampled` 标记会在此之前移除。
+URL matcher 支持字符串包含、`RegExp` 或 `(url) => boolean`。字符串使用 `url.includes(matcher)`，不等于 origin 精确匹配；安全白名单应使用 URL-aware 函数或带边界的正则。自动 View 只对 pathname 和非页内锚点 hash path 的变化切换，query-only 变化不切换。
+
+## tracking.request
+
+`request` 可设为 `false` 完全关闭 Fetch/XHR patch；`true` 或 `{}` 使用默认配置。
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `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 |
+
+默认不采集 Body。Body 只在 Log 信号开启时生效，不支持 FormData、ArrayBuffer 等不可安全文本化的内容。
+
+## tracking 内置能力
+
+| 字段 | 类型 | 默认 | 参数 |
+| --- | --- | --- | --- |
+| `resource` | `boolean` | `true` | 无；`false` 只关闭静态资源 Span，Resource Observer 仍服务请求 timing/活动 |
+| `error` | `boolean \| BkOTErrorPluginOptions` | `true` | `windowMs=60_000`、`maxPerWindow=5` |
+| `webVitals` | `boolean` | `true` | 无 |
+| `blankScreen` | `boolean \| BkOTBlankScreenPluginOptions` | `true` | 见下表 |
+| `device` | `boolean \| BkOTDevicePluginOptions` | `true` | 见下表 |
+| `action` | `boolean \| BkOTActionPluginOptions` | `true` | 见下表 |
+| `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50`、`warningThreshold=100` ms |
+| `websocket` | `boolean` | `false` | 无 |
+| `cspViolation` | `boolean` | `false` | 无，内置同指纹 60 秒最多 5 条 |
+
+Blank Screen：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `rootSelector` | `body` | 应用挂载根节点 |
+| `threshold` | `0.8` | 九点采样的空白比例，限制到 `0..1` |
+| `checkDelay` | `1000` ms | 页面活动稳定后的首次检查延迟 |
+| `confirmationDelay` | `200` ms | 两次候选白屏的确认间隔 |
+| `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会替换内置数组 |
+
+Action：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `actionNameAttribute` | `data-bk-action-name` | 向上查找的显式动作名属性 |
+| `maxDuration` | `10_000` ms | 单次 Action 最大活动窗口 |
+| `nameCollection` | `explicit` | 默认只取显式属性，否则退回标签名；`text` 才读取可访问名称/DOM 文本 |
+
+Device：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `persistentId` | `false` | `false` 时 ID 只在当前实例稳定；`true` 写 localStorage |
+| `storageKey` | 按应用名 hash | 仅持久 ID 使用 |
+
+## tracking.beforeSend
 
 ```ts
 tracking: {
@@ -142,84 +196,73 @@ tracking: {
 }
 ```
 
-## 不再支持的旧入口
+该 Hook 在 Span/Log 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning。它不处理 Metric；请求专属逻辑优先使用 `tracking.request.beforeSend`。
 
-`app`、`sampling`、`route`、顶层 `view`、`plugins`、`instrumentations`、`attributes`、`spanProcessor`、`spanBatch` 已删除，不做兼容映射。
+## context
 
-# 传输与采样
+| 字段 | 类型 | 默认 | 作用 |
+| --- | --- | --- | --- |
+| `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()` 附加属性 |
 
-## Endpoint
+自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。Metric Hook 禁止放用户 ID、订单 ID、完整 URL 等高基数字段。
 
-`transport.endpoint` 是可选根地址。未配置独立地址的已开启信号会基于它生成 `/v1/rum`、`/v1/metrics`、`/v1/logs`；单信号 `endpoint` 是完整 URL，不再拼接路径。
+## privacy
 
-```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' },
-    },
-  },
-});
-```
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
+| `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | SDK 创建 Span/Log 和内置插件属性脱敏 |
+
+第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
+
+## extensions
 
-## 独立信号开关
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `plugins` | `BkOTPlugin[]` | `[]` | 在内置插件后初始化 |
+| `instrumentations` | `Instrumentation[]` | `[]` | 插件完成后注册到 SDK provider |
 
-三类信号默认全部开启。设为 `false` 时，不创建对应 exporter、processor 或 metric reader：
+也可以在 `start()` 前调用 `use()` / `useInstrumentation()`。需要动态注册时设置 `autoStart: false`；启动后调用会抛错。
+
+## 完整配置骨架
 
 ```ts
 new BkOpenTelemetry({
-  application: { name: 'trace-only-demo' },
+  application: { name: 'demo', environment: 'production', version: '1.0.0' },
   transport: {
+    endpoint: 'https://collector.example.com',
+    token: 'token',
+    headers: {},
     signals: {
-      traces: { endpoint: 'https://trace.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
+      traces: { processor: 'batch', batch: {} },
+      metrics: { intervalMillis: 60_000 },
+      logs: {},
     },
   },
+  session: { sampleRate: 1 },
+  tracking: {
+    view: { tracking: 'auto', loadingTime: true },
+    request: true,
+    resource: true,
+    error: true,
+    webVitals: true,
+    blankScreen: true,
+    device: true,
+    action: true,
+    longTask: false,
+    websocket: false,
+    cspViolation: false,
+  },
+  context: { attributes: {} },
+  privacy: { trackingConsent: 'granted' },
+  extensions: { plugins: [], instrumentations: [] },
+  enabled: true,
+  autoStart: true,
+  debug: 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`。
-
-浏览器 exporter 使用 `fetch keepalive`，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 得出。
-- 不写额外 sessionStorage；同一 Session 内 span/log/metric 决定一致。
-- Session 续期后使用新 ID 重新计算。
-
-Metric exporter 只接受带内部采样标记的数据点，并在传输前移除该标记。Metric 只保留低基数 `view.url_path_group`，精确 View 关联由 span/log/View Snapshot 的 `view.id` 提供。

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

@@ -54,7 +54,11 @@ await bkOT.start();
 
 `init(context)` 中可以访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()`、`getRuntimeAttributes()` 等能力。
 
+优先使用 `context.startSpan()` 和 `context.emitLog()`：它们会合并事件发生时的运行时上下文并应用 SDK 脱敏。直接调用 `context.logger.emit()` 的 Log 不会自动获得这些能力，可能因缺少有效 Session/View 被导出过滤器丢弃。
+
 ```ts
+let teardownVisibility = () => {};
+
 const visibilityPlugin = createPlugin({
   name: 'visibility-change',
   init(context) {
@@ -69,8 +73,10 @@ const visibilityPlugin = createPlugin({
     };
 
     document.addEventListener('visibilitychange', onVisibilityChange);
-
-    return undefined;
+    teardownVisibility = () => document.removeEventListener('visibilitychange', onVisibilityChange);
+  },
+  shutdown() {
+    teardownVisibility();
   },
 });
 ```
@@ -158,4 +164,10 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 await bkOT.start();
 ```
 
-> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 RUM 数据仍受 Session sampler 和导出过滤约束。
+> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束；第三方 instrumentation Metric 因没有公开采样 helper，默认会被过滤。
+
+## 自定义 Metric 注意事项
+
+内置 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，而不是绕过当前过滤约束。

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

@@ -18,11 +18,11 @@ SDK 的数据模型遵循“浏览器 SDK 负责低成本原始数据和单事
 | `document` | 文档加载 | View 管理器（初始加载） |
 | `resource` | Fetch/XHR 请求与静态资源 | request、resource 采集 |
 | `vital` | Web Vitals | webVitals 插件 |
-| `error` | 错误 | error 插件、blankScreen 插件、cspViolation 插件、自定义事件错误 |
+| `error` | 浏览器与体验错误 | error 插件、blankScreen 插件、cspViolation 插件 |
 | `longtask` | 长任务 | longTask 插件 |
 | `action` | 用户动作 | action 插件、reportAction |
 | `route` | 路由切换 | View 管理器（SPA/手动 View） |
-| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件 |
+| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件；`reportCustomEvent({ error })` 仍属于此类型 |
 
 > 每种 span 的具体 span 名、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
 
@@ -56,6 +56,8 @@ span.end();
 
 请求 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',