@blueking/open-telemetry 0.0.14 → 0.0.16

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

@@ -2,51 +2,50 @@
 
 # 插件总览
 
-插件是 `@blueking/open-telemetry` 的能力边界。SDK 内部先启动官方 instrumentation，再按采样结果启动 RUM 插件。
+插件是 `@blueking/open-telemetry` 的能力边界。获得采集授权后，SDK 先建立 Session、Device、View 上下文，再启动请求采集和其他 RUM 插件。
 
 ## 默认插件组合
 
 ```ts
 new BkOpenTelemetry({
-  instrumentations: {
-    documentLoad: true,
-    fetch: true,
-    xhr: true,
-    userInteraction: true,
-  },
-  plugins: {
-    pageView: true,
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: {
+    request: true,
     resource: true,
     error: true,
     webVitals: true,
     blankScreen: true,
     device: true,
-    session: true,
+    action: true,
   },
 });
 ```
 
+`session` 和 View 生命周期是不可关闭的 RUM 基础能力；`tracking.view` 只切换自动/手动策略及 loading time。
+
 ## 能力分类
 
 | 分类       | 插件                                                              | 主要信号                      |
 | ---------- | ----------------------------------------------------------------- | ----------------------------- |
-| 基础上下文 | `session`、`device`、`pageView`                                   | log、span、runtime attributes |
-| 性能体验   | `resource`、`webVitals`、`blankScreen`、`longTask`、`routeTiming` | span、metric、log             |
-| 错误安全   | `error`、`cspViolation`                                           | span、log                     |
-| 网络扩展   | `httpBody`、`websocket`                                           | log、span、metric             |
+| 基础上下文 | Session、View、`device`                                           | log、span、runtime attributes |
+| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span、metric、log          |
+| 错误安全   | `error`、`cspViolation`                                           | span                          |
+| 网络扩展   | Fetch/XHR request patch、`websocket`                              | span、metric、log             |
 | 用户行为   | `action`、`reportAction()`                                        | span                          |
 
 ## 插件启用规则
 
-RUM 插件只在会话命中采样时启动。未命中采样时，SDK 仍可注册核心 provider，但不会启动主动产生数据的插件。
+获得采集授权后，已启用插件会启动并维护页面生命周期；Session 级确定性 sampler 与 exporter processor 统一决定数据是否导出。未授权时不会 patch 浏览器 API、创建 Session 或启动插件；运行期可通过 `setTrackingConsent()` 切换。
 
 ```ts
 new BkOpenTelemetry({
-  sampling: {
-    rate: 0.1,
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  session: {
+    sampleRate: 0.1,
   },
-  plugins: {
-    pageView: true,
+  tracking: {
     error: true,
     webVitals: true,
     action: true,
@@ -57,8 +56,8 @@ new BkOpenTelemetry({
 ## 选择建议
 
 - 首次接入：使用默认插件即可。
-- 需要分析慢页面：开启 `longTask` 和 `routeTiming`。
-- 需要分析接口错误体：开启 `httpBody`，并配置 `redact`。
+- 需要分析慢页面：View Loading Time 默认开启；再开启 `longTask` 获取主线程与脚本归因。
+- 需要为请求增加业务字段或过滤请求：配置 `request.beforeSend` / `request.excludedUrls`。
 - 需要分析 CSP：开启 `cspViolation`。
 - 需要分析实时通信：开启 `websocket`，注意避免多个 SDK 实例重复 patch。
 
@@ -66,28 +65,30 @@ new BkOpenTelemetry({
 
 基础插件负责建立 RUM 数据的关联上下文：哪个用户、哪个会话、哪个页面、哪个设备。
 
+以下片段聚焦对应的 `session` 或 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
 ## session
 
-`session` 插件维护 `session.id`，并在会话开始和轮换时写入 log。默认开启。
+`session` 维护 `session.id`，并在会话开始和轮换时写入 log。它是所有 RUM 信号的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
 
 默认规则：
 
-- 不活跃超过 30 分钟后轮换。
-- 会话最长 24 小时。
+- 不活跃超过 15 分钟后过期，下一次用户交互时轮换。
+- 会话最长 4 小时。
 - storage key 会按 endpoint host 隔离。
+- 页面重新可见只续期有效会话，不会复活已过期会话。
+- 跨 Tab 共享持久化状态，但已过期的 Tab 需要自身发生用户交互后才接管新会话。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    session: {
-      inactivityMs: 30 * 60 * 1000,
-      maxLifetimeMs: 24 * 60 * 60 * 1000,
-      storageKey: 'bk-rum-session',
-    },
+  session: {
+    storageKey: 'bk-rum-session',
   },
 });
 ```
 
+超时固定为 15 分钟无活动、4 小时最长生命周期，不开放配置。过期会结束当前 View、刷新旧 session 的待发送数据，并丢弃此后所有不带有效 `session.id` 的 span/log/metric；下一次用户交互续期时，同时创建新的 Session 和 View。Metric 使用 DELTA temporality，避免累计值跨 session 重复上报。
+
 **产出遥测**：log `session.start` / `session.rotate`，并维护运行时属性 `session.id`。
 
 ## device
@@ -96,8 +97,9 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     device: {
+      persistentId: true,
       storageKey: 'bk-rum-device',
     },
   },
@@ -106,56 +108,87 @@ new BkOpenTelemetry({
 
 后续 span/log 会自动带上这些属性，便于按浏览器、系统、网络类型下钻。
 
-**产出遥测**：只写入运行时属性（如 `device.id`、`browser_name`、`os_name`、`device_type`、`network.effective_type`），本身不单独产生 span/metric/log。
+`device.id` 默认只在当前 SDK 实例内稳定；只有显式设置 `persistentId: true` 才写入 localStorage，并按应用名隔离默认 storage key。
 
-## pageView
+**产出遥测**：只写入运行时属性（如 `device.id`、`browser.name`、`os.name`、`device.type`、`network.effective_type`），本身不单独产生 span/metric/log。
 
-`pageView` 插件负责初始页面和 SPA 路由 view。它会维护：
+## View
+
+View 管理器负责初始页面、SPA 路由、手动 View、BFCache 和 Session 续期。它与 Session 一样不可关闭，并维护：
 
 - `view.id`
+- `view.name`
 - `view.url`
 - `view.url_path_group`
 - `view.loading_type`
+- `view.loading_time`
 
 ```ts
 new BkOpenTelemetry({
-  route: {
-    getPathGroup: url => {
-      const { pathname } = new URL(url, window.location.href);
-      return pathname.replace(/\/\d+/g, '/:id');
+  tracking: {
+    view: {
+      tracking: 'auto',
+      loadingTime: true,
+      excludedActivityUrls: [/\/events\/stream$/],
+      getPathGroup: url => {
+        const { pathname } = new URL(url, window.location.href);
+        return pathname.replace(/\/\d+/g, '/:id');
+      },
     },
   },
-  plugins: {
-    pageView: true,
-  },
 });
 ```
 
-**产出遥测**：span `browser.view`（有持续时间）与 `browser.page_view`（0ms 瞬时），并维护 `view.*` 运行时属性。
+自动模式只在 pathname 或非锚点 hash path 变化时切换 View；query-only 和页内锚点变化不会切换。手动模式使用 `view.tracking: 'manual'`，并调用 `startView({ name, url, attributes })`。
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'order-web' },
+  autoStart: false,
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: { view: { tracking: 'manual' } },
+});
+
+await bkOT.start();
+bkOT.startView({
+  name: '订单详情',
+  url: window.location.href,
+  attributes: { 'biz.owner': 'order-team' },
+});
+bkOT.setViewName('订单详情-只读');
+```
+
+`view.id` 始终由 SDK 生成，`attributes` 不能覆盖 Session/View 等保留字段。普通 span/log 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路；metric 只保留 `view.url_path_group` 等低基数维度，不携带唯一 `view.id`。手动模式在首次 `startView()` 前不会导出普通 RUM 数据。
+
+View Loading Time 默认开启：初始加载取 `loadEventEnd` 与页面活动结束时间的较大值，SPA 路由取 View 创建到页面活动结束的耗时。请求、静态资源和 DOM 变更都属于页面活动，连续 100ms 无活动视为稳定。长轮询或埋点请求应配置到 `view.excludedActivityUrls`；业务也可在真正渲染完成时调用 `setViewLoadingTime()` 覆盖自动结果。
+
+**产出遥测**：长 span `browser.view`（包含 `view.loading_time`）与 body 为 `browser.view` 的 create/update/final Snapshot Log，metric `browser.view.loading_time`，并维护 `view.*` 运行时属性。
 
 ## action
 
-`action` 插件默认关闭。开启后可以自动监听 click、submit、keydown 等事件，并生成 `action` span。
+`action` 插件默认开启。它自动监听 click，观察交互后的请求、DOM 变更、资源、错误和长任务，在页面活动稳定后生成一个 `action` span。
 
 **产出遥测**：span `action.<type>`（如 `action.click`，`span_type=action`）。`reportAction()` 走同一套字段。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     action: {
-      eventNames: ['click', 'submit', 'keydown'],
+      actionNameAttribute: 'data-bk-action-name',
+      maxDuration: 10000,
+      nameCollection: 'explicit',
     },
   },
 });
 ```
 
+自动命名在默认 `explicit` 模式只向上查找 `data-bk-action-name`；没有显式名称时退回目标元素标签名。设置 `nameCollection: 'text'` 后才会继续读取 label、按钮值、`aria-label`、`alt`、`name`、`title`、`placeholder` 和 DOM 文本，并自行评估隐私风险。
+
 对关键业务动作，推荐使用 `reportAction()` 显式上报，字段更稳定。
 
 ```ts
 bkOT.reportAction({
-  type: 'click',
-  targetTag: 'button',
-  targetText: '立即支付',
+  name: '立即支付',
   attributes: {
     'biz.order_id': '202605270001',
   },
@@ -166,31 +199,51 @@ bkOT.reportAction({
 
 体验类插件关注页面加载、资源、核心 Web 指标、空白屏、主线程阻塞和 SPA 路由切换。
 
+以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
 ## resource
 
 `resource` 插件默认开启，基于 PerformanceObserver 采集静态资源加载 span。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     resource: true,
   },
 });
 ```
 
-常见字段包括 `initiator_type`、`transfer_size`、`next_hop_protocol`、`target_domain`、`target_path_template`。
+常见字段包括 `initiator_type`、`transfer_size`、`resource.protocol`、`target_domain`、`target_path_template`。当 Resource Timing 数据可用时，还会上报：
+
+- `resource.redirect.*`、`resource.dns.*`、`resource.connect.*`、`resource.ssl.*`
+- `resource.first_byte.*`、`resource.download.*`、`resource.worker.*`
+- `resource.delivery_type`、`resource.render_blocking_status`
+
+每个网络阶段同时包含相对资源开始时刻的 `start` 与阶段 `duration`，单位均为 ms。跨域资源没有返回 `Timing-Allow-Origin` 时，浏览器不会暴露完整阶段数据，SDK 会保留资源总耗时，但不生成不可信的阶段字段。
 
 **产出遥测**：span `browser.resource`（`span_type=resource`）。
 
+## action 与挫败信号
+
+`action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time` 和子事件数量。
+
+自动点击还会判断三类挫败信号：
+
+- `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。三次点击合并为一条 action。
+- `dead_click`：点击后没有页面活动、输入、滚动或文本选择；文本输入、链接、select、textarea、canvas、contenteditable 等无法可靠判断的元素会排除。
+- `error_click`：点击活动窗口内产生前端错误。
+
+信号写入 `action.frustration.type`（string[]）和 `action.frustration.count`。为了完成连续点击判断，action span 最多延迟 1 秒创建；`action.id` 只在真实页面活动窗口内挂到关联事件上，不会因为这个上报等待期延长。
+
 ## webVitals
 
-`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。它会同时产生 metric 和 span：metric 用于聚合，span 用于定位具体页面和归因信息。
+`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。FCP/LCP/TTFB 按指标发生时刻归属 View，CLS 使用每个 View 独立的 1 秒间隔/5 秒窗口，INP 使用候选交互的近似 p98，而不是简单最大值。它会同时产生 metric 和 span：metric 用于低基数聚合，span 用于通过 `session.id`、`view.id` 定位具体页面和归因信息。
 
 **产出遥测**：metric `browser.web_vital.cls`（unit `1`）、`browser.web_vital.duration`（unit `ms`，FCP/INP/LCP/TTFB 共用）+ span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     webVitals: true,
   },
 });
@@ -198,14 +251,15 @@ new BkOpenTelemetry({
 
 ## blankScreen
 
-`blankScreen` 插件默认开启。它会在页面加载后一段时间检查视口采样点，如果空白比例超过阈值，则上报空白屏结果。
+`blankScreen` 插件默认开启。它会针对每个 View 等待页面活动稳定后执行九点分层采样；只有两次连续检测都超过阈值才上报。View 切换或页面隐藏会取消旧检测，恢复可见后重新调度。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     blankScreen: {
       rootSelector: '#app',
-      checkDelay: 3000,
+      checkDelay: 1000,
+      confirmationDelay: 200,
       threshold: 0.8,
       ignoreSelectors: ['.global-loading', '.skeleton'],
     },
@@ -213,55 +267,62 @@ new BkOpenTelemetry({
 });
 ```
 
-SPA 应用建议配置 `rootSelector`，否则默认以整个页面判断，容易受外层布局影响。
+SPA 应用建议配置 `rootSelector`。根节点在确认阶段仍不存在时会以 `missing_root` 原因上报；loading 和骨架屏样本不进入空白比例分母。
 
 **产出遥测**（仅判定为白屏时）：metric `browser.blank_screen.count` + error span `browser.blank_screen`（`span_type=error`）。
 
 ## longTask
 
-`longTask` 插件默认关闭。开启后通过 Long Task API 采集主线程阻塞。
+`longTask` 插件默认关闭。开启后优先通过 Long Animation Frames API 采集主线程阻塞；浏览器不支持时自动回退到 Long Tasks API，两种入口不会重复观察。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     longTask: {
-      threshold: 80,
+      threshold: 50,
+      warningThreshold: 100,
     },
   },
 });
 ```
 
-Firefox 对 Long Task API 支持有限，不支持时插件会跳过。
+LoAF 会补充 blocking duration、render/style/layout 阶段、最重脚本归因，并把每个脚本作为 `long_task.script` Span Event。初始化阶段的 buffered entries 延迟到后续宏任务批量处理，避免 SDK 启动自身制造阻塞。不支持 LoAF 和 Long Tasks API 的浏览器会跳过插件。
+
+**产出遥测**：metric `browser.long_task.count` / `browser.long_task.duration` / `browser.long_task.blocking_duration`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
 
-**产出遥测**：metric `browser.long_task.count` / `browser.long_task.duration`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
+## View Loading Time
 
-## routeTiming
+View Loading Time 属于 View 管理器，默认启用，基于页面活动结束时间计算。
 
-`routeTiming` 插件默认关闭。它会监听 SPA 路由变化，并通过双 `requestAnimationFrame` 和 `setTimeout` 估算路由切换到渲染稳定的耗时。
+自动计算规则：
 
-**产出遥测**：metric `browser.route_change.duration`（unit `ms`）+ span `browser.route_change`（`span_type=route`）。tab 切到后台时数据会被丢弃，避免污染 P99。
+- 初始加载：取 `navigationStart → loadEventEnd` 与 `navigationStart → 页面活动结束` 的较大值。
+- SPA 路由：取 View 创建到页面活动结束的耗时。
+- Fetch/XHR 进行中、静态资源完成和 DOM Mutation 都属于活动；连续 100ms 无活动视为稳定。
+- SDK 自身上报、`view.excludedActivityUrls` 命中的请求，以及 `data-bk-excluded-activity-mutations` 节点下的 DOM 变更不参与计算。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    routeTiming: true,
+  tracking: {
+    view: {
+      loadingTime: true,
+      excludedActivityUrls: [/\/events\/stream$/, '/analytics'],
+    },
   },
 });
 ```
 
-如果业务路由有异步数据加载，建议结合自定义事件补充更精确的业务完成点。
+如果业务有明确的异步渲染完成点，可覆盖自动结果：
 
 ```ts
-const span = bkOT.startSpan('custom.route_data_ready', {
-  'route.name': 'alarm-detail',
-});
-
 await loadAlarmDetail();
-span.end();
+bkOT.setViewLoadingTime();
 ```
 
 # 错误与安全插件
 
+以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
 错误类插件帮助定位 JavaScript 异常、Promise 异常、资源加载失败、CSP 违规和空白屏等问题。
 
 ## error
@@ -278,7 +339,7 @@ span.end();
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     error: {
       maxPerWindow: 5,
       windowMs: 60_000,
@@ -313,7 +374,7 @@ try {
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     cspViolation: true,
   },
 });
@@ -331,7 +392,7 @@ Content-Security-Policy: default-src 'self'; report-uri /csp-report
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     blankScreen: {
       rootSelector: '#app',
     },
@@ -345,107 +406,140 @@ new BkOpenTelemetry({
 
 # 网络与扩展插件
 
-网络类能力覆盖 fetch/xhr、HTTP body 错误路径和 WebSocket。由于这些能力会 patch 浏览器原生 API，微前端或多 SDK 实例场景需要特别注意避免重复初始化。
+网络能力覆盖 Fetch/XHR 与 WebSocket。两者都会 patch 浏览器全局 API，同一页面只应运行一个 SDK 实例。
+
+以下片段聚焦 `tracking`，实际初始化仍需提供 `application.name` 和有效 Transport。
+
+## Fetch/XHR request
+
+`tracking.request` 默认开启。当前实现由 SDK 自己统一 patch `window.fetch` 与 `XMLHttpRequest.prototype.open/send`，不使用官方 Fetch/XHR instrumentation，也不会为同一请求叠加两套生命周期。
 
-## fetch / xhr instrumentation
+### 请求生命周期
 
-fetch 和 xhr 默认开启，会生成 HTTP span，并对 URL 做脱敏处理。
+一次请求按以下顺序处理：
 
-**产出遥测**：HTTP span（span 名由官方探针决定，如 `HTTP GET`，`span_type=http`），带 `http.request.method`、`http.response.status_code`、`url.full`、`status_class` 等。
+1. 转成绝对 URL，检查 SDK 自身 OTLP Endpoint 与 `excludedUrls`。
+2. 创建名为 `browser.resource`、kind 为 `CLIENT` 的 Span。
+3. 记录 View/Action 页面活动；`view.excludedActivityUrls` 可只排除活动等待，不丢弃 Span。
+4. `allowedTracingUrls` 命中且 Trace 开启时进入传播 Header 注入分支；默认 W3C propagator 注入 `traceparent`，宿主已有全局 propagator 时以实际实现为准。
+5. 请求完成后写入状态、结果、错误和 `request.beforeSend` 属性。
+6. 等待最多 200ms 匹配 Resource Timing，把网络阶段补回同一 Span。
+7. 如已配置 Body 且 Log 开启，异步生成关联原 `trace.id` / `span.id` 的诊断 Log。
+
+**产出遥测**：Span `browser.resource`，`span_type=resource`、`resource.type=fetch|xhr`，常用属性包括 `resource.url`、`resource.method`、`resource.status_code`、`http.*`、`url.full`、网络阶段与响应体积。
 
 ```ts
 new BkOpenTelemetry({
-  privacy: {
-    redactUrl: url => url.replace(/\/orders\/\d+/g, '/orders/:id'),
-  },
-  instrumentations: {
-    fetch: true,
-    xhr: true,
+  application: { name: 'request-demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: {
+    request: {
+      excludedUrls: [/\/health(?:\?|$)/],
+      beforeSend(event, context) {
+        event.attributes['request.transport'] = context.type;
+        return event.resource.statusCode !== 404;
+      },
+    },
   },
 });
 ```
 
-### traceparent 透传（前后端 trace 串联）
+`request.beforeSend` 在请求完成后执行，可修改 Span attributes；返回 `false` 会标记该 Span 在最终 processor 中丢弃，并立即跳过该请求的 Body Log。Hook 抛错不会中断业务请求，`debug: true` 时输出 warning。
 
-fetch/xhr 请求会自动给**同源**请求注入 W3C `traceparent` 请求头（内含 OpenTelemetry traceId）。后台 API 通常是跨域的，需要通过 `propagateTraceHeaderUrls` 显式纳入注入范围：
+### excludedUrls 与 excludedActivityUrls
+
+| 配置 | 是否创建 Span | 是否计入 View/Action 活动 | 适用场景 |
+| --- | --- | --- | --- |
+| `tracking.request.excludedUrls` | 否 | 否 | 探活、埋点、无需采集的请求 |
+| `tracking.view.excludedActivityUrls` | 是 | 否 | 长轮询、SSE、流式接口，不应阻塞页面稳定 |
+
+两者都支持字符串包含、RegExp 和函数 matcher。
+
+### traceparent 注入条件
+
+只有 `allowedTracingUrls` 命中且 Trace 信号开启时才进入传播 Header 注入分支；默认 W3C propagator 会注入 `traceparent`，同源请求也不隐式放行。
 
 ```ts
-new BkOpenTelemetry({
-  instrumentations: {
-    // 字符串子串 / 正则 / 数组 / (url) => boolean / 'all' 均可
-    propagateTraceHeaderUrls: ['api.example.com', /\.internal\.com\//],
+tracking: {
+  request: {
+    allowedTracingUrls: [
+      url => new URL(url).origin === 'https://api.example.com',
+      /^https:\/\/[^/]+\.internal\.example\.com\//,
+    ],
   },
-});
+}
 ```
 
-向跨域服务注入自定义头会触发 CORS 预检，目标服务需在 `Access-Control-Allow-Headers` 中放行 `traceparent`（以及按需的 `tracestate`）。`propagateTraceHeaderUrls` 的完整取值（`'all'` / 字符串 / 正则 / 数组 / 函数）见[配置总览](./configuration.md#instrumentation-配置)。
+字符串 matcher 使用包含匹配，例如 `'https://api.example.com'` 也会命中 `https://api.example.com.evil/`，不适合作为安全 origin 边界。需要精确控制时使用上面的 URL-aware 函数或带 `/` 边界的正则。
+
+跨域注入会触发 CORS 预检，目标服务必须在 `Access-Control-Allow-Headers` 放行实际使用的 Trace Header。SDK 成功注册自己的默认 W3C propagator 时通常注入 `traceparent`，并可能透传已有 `tracestate`；如果宿主已注册全局 propagator，实际 Header 由该 propagator 决定，可能还包含其他传播字段。
 
-## httpBody
+### Resource Timing
 
-`httpBody` 默认关闭。开启后只在错误路径采集请求/响应 body，适合排查接口错误，但必须配置脱敏策略。
+Fetch/XHR 与静态资源共用一个 Resource PerformanceObserver：
 
-**产出遥测**：log `HTTP request completed`（成功，INFO）/ `HTTP request completed with error`（错误，ERROR，带 `http.request.body`、`http.response.body`、`http_body.*.truncated`）。
+- `initiatorType=fetch|xmlhttprequest` 的 entry 只用于匹配请求 Span，不再创建静态资源 Span。
+- 通过 URL 与时间窗口匹配；找不到 entry 时请求 Span 仍正常结束。
+- 跨域接口缺少 `Timing-Allow-Origin` 时，浏览器不会提供完整阶段字段。
+- Trace 关闭时跳过 timing 等待，因为不存在可导出的请求 Span。
+
+### 请求/响应 Body
+
+Body 默认关闭。开启时必须提供 `redact`，默认只采集状态未知、0 或 `>=400` 的请求：
 
 ```ts
-new BkOpenTelemetry({
-  plugins: {
-    httpBody: {
-      maxBodySize: 10 * 1024,
-      redact: ({ body, status, type }) => {
-        if (status && status < 500) {
-          return '[body hidden for non-5xx error]';
+tracking: {
+  request: {
+    body: {
+      capture: 'errors',
+      maxSize: 10 * 1024,
+      allowedContentTypes: ['application/json', /^text\//],
+      redact({ body, kind }) {
+        if (kind === 'request') {
+          return body.replace(/("(?:password|token)"\s*:\s*)"[^"]*"/g, '$1"***"');
         }
-        return type === 'request' ? '[request body redacted]' : body;
+        return body;
       },
     },
   },
-});
+}
 ```
 
-## websocket
+**产出遥测**：Log `browser.request.body`，错误请求为 ERROR，`capture: 'all'` 下成功请求为 INFO。
 
-`websocket` 默认关闭。开启后会用 Proxy 包装 WebSocket，采集连接、消息大小、错误和关闭事件。
+- Fetch 的 Request/Response 通过 clone 限量读取，不消费业务原始流。
+- XHR 支持文本与 JSON 响应。
+- string、URLSearchParams、Blob 等可文本化请求可读取；FormData、ArrayBuffer 和二进制响应跳过。
+- 默认 Content-Type：`text/*`、包含 `json`、`application/x-www-form-urlencoded`、`application/graphql`。
+- `redact` 返回 `undefined` 时只跳过当前 request 或 response Body。
+- Log 信号关闭时 Body 配置不生效。
+
+## websocket
 
-**产出遥测**：span `websocket.connect`（`span_type=custom`，仅建连阶段）；metric `browser.websocket.message.count` / `.message.bytes` / `.error.count` / `.connect.duration`；log `websocket.error` / `websocket.close`。
+`tracking.websocket` 默认关闭。开启后用 Proxy 包装 `window.WebSocket`，保留静态常量、`instanceof` 与子类化行为。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    websocket: true,
-  },
+  application: { name: 'realtime-demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: { websocket: true },
 });
 ```
 
-业务发送消息时无需改造。
+**产出遥测**：
 
-```ts
-const socket = new WebSocket('wss://message.example.com/ws');
+- Span `websocket.connect`：只覆盖建连阶段，成功/失败后结束，不用长 Span 覆盖整个连接。
+- Metric `browser.websocket.message.count`、`browser.websocket.message.bytes`：按 `in/out` 分组。
+- Metric `browser.websocket.error.count`：按 `connect/runtime` 分组。
+- Metric `browser.websocket.connect.duration`：只记录成功建连耗时。
+- Log `websocket.error`、`websocket.close`：记录错误阶段和关闭详情。
 
-socket.addEventListener('open', () => {
-  socket.send(JSON.stringify({ type: 'ping' }));
-});
-```
+插件不读取消息内容，只计算数量和字节数。超过 64KB 的字符串使用 `string.length` 近似字节数，避免编码开销；CJK/emoji 会低估。相同 URL 的错误 Log 在 60 秒内最多 5 条，Error Counter 不受节流影响。
 
-## 自定义网络事件
+SDK shutdown 后新建连接不再采集；已存在连接上的包装会保留，但回调立即返回。若其他库后来替换了 `window.WebSocket`，shutdown 不会强行覆盖后来者。
 
-如果业务已有请求封装，也可以在封装层补充更稳定的业务 span。
+## 与额外 instrumentation 的关系
 
-```ts
-export const requestWithRum = async <T>(url: string, init?: RequestInit): Promise<T> => {
-  const span = bkOT.startSpan('custom.biz_request', {
-    'biz.request.url': url.replace(/\/\d+/g, '/:id'),
-    'biz.request.method': init?.method || 'GET',
-  });
+`extensions.instrumentations` 适合已有标准 OpenTelemetry instrumentation。不要再注册覆盖 Fetch/XHR 或用户交互的 instrumentation，否则可能与内置 request/action 重复 patch、重复 Span。
 
-  try {
-    const response = await fetch(url, init);
-    span.setAttribute('http.response.status_code', response.status);
-    return response.json() as Promise<T>;
-  } catch (error) {
-    span.recordException(error as Error);
-    throw error;
-  } finally {
-    span.end();
-  }
-};
-```
+需要 Session/View、`emitLog()`、页面活动或 RUM 归一字段时，优先写自定义插件，见[内置采集与扩展](./concepts.md)与[自定义插件](./custom-plugin.md)。