@blueking/open-telemetry 0.0.19 → 0.0.21

package/dist/plugins/device.d.ts

@@ -1,16 +1,17 @@
 import type { BkOTPlugin } from '../core/plugin';
+import type { Attributes } from '@opentelemetry/api';
 export interface BkOTDevicePluginOptions {
     /** 是否跨页面持久化匿名设备 ID，默认 false。 */
     persistentId?: boolean;
     storageKey?: string;
 }
+export declare const getDeviceResourceAttributes: () => Attributes;
 /**
- * 设备元数据采集插件，把"设备级"信息写入 SDK 的 runtimeAttributes，
- * 让所有 log/span 都自动带上这些维度。
+ * 设备元数据采集插件。稳定的设备能力由 SDK 写入 Resource；这里只维护设备 ID 和运行期动态属性。
  *
  * 上报字段：
  * - `device.id`：设备级永久标识，存于 localStorage（默认 key 复用旧 session 插件以保留现网用户）。
- * - `device.memory` / `device.cpu_cores` / `device.platform` / `device.mobile`：硬件能力快照（运行期不变）。
+ * - `device.memory_gib` / `device.logical_processor_count`：硬件能力快照，写入 Resource。
  * - `browser.viewport.*` / `browser.screen.*`：视口与屏幕尺寸。
  * - `network.effective_type` / `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data`：
  *   网络信息。

package/dist/schema/attributes.d.ts

@@ -19,6 +19,8 @@ export declare const RUM_ATTRIBUTES: {
     readonly browserName: "browser.name";
     readonly browserVersion: "browser.version";
     readonly cacheHit: "resource.cache.hit";
+    readonly deviceLogicalProcessorCount: "device.logical_processor_count";
+    readonly deviceMemoryGib: "device.memory_gib";
     readonly deviceType: "device.type";
     readonly errorType: "error_type";
     readonly exceptionFingerprint: "exception.fingerprint";
@@ -35,6 +37,7 @@ export declare const RUM_ATTRIBUTES: {
     readonly networkEffectiveType: "network.effective_type";
     readonly nextHopProtocol: "resource.protocol";
     readonly result: "result";
+    readonly rumSchemaVersion: "rum.schema.version";
     readonly serviceName: "service.name";
     readonly serviceVersion: "service.version";
     readonly osName: "os.name";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
   "scripts": {
     "prepublishOnly": "pnpm build && pnpm dts && pnpm skill:refs",
     "skill:refs": "node scripts/gen-skill-references.mjs",
+    "test:skill-refs": "node --test tests/gen-skill-references.test.mjs",
     "build": "vite build && vite build --mode cdn && pnpm dts",
     "build:cdn": "vite build --mode cdn",
     "build:esm": "vite build",

package/skills/bk-rum-otele/SKILL.md

@@ -27,7 +27,11 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 | 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文                       | `references/concepts.md`              |
 | 查配置项、默认值、Endpoint、插件参数和 Hook                                                | `references/configuration.md`         |
 | 查 Transport、单信号开关、批量上报、Session 采样和 traceparent 透传                       | `references/transport-sampling.md`    |
-| 开关某个采集能力、看请求配置和各插件参数（request/error/blankScreen/longTask/websocket 等） | `references/plugins.md`               |
+| 了解插件默认组合、启用规则和能力分类                                                       | `references/plugins.md`               |
+| 配置 Session、Device、View、Action                                                         | `references/plugins-basic.md`         |
+| 配置 Resource、Web Vitals、Blank Screen、Long Task、View Loading Time                     | `references/plugins-experience.md`    |
+| 配置 Error、CSP Violation 和错误上报                                                       | `references/plugins-error-security.md` |
+| 配置 Fetch/XHR Request、HTTP Body、Trace Header、WebSocket                                 | `references/plugins-network.md`       |
 | 写自定义插件、接入第三方 OpenTelemetry instrumentation                                      | `references/custom-plugin.md`         |
 | 查公开 API（start/flush/shutdown/setUser/setView/reportAction/reportCustomEvent 等）        | `references/api.md`                   |
 | Vue / React / Vue Router / 微前端 集成                                                      | `references/framework-integration.md` |
@@ -99,7 +103,7 @@ CDN：
 
 - 基础能力：Session、View；内置采集：`request`、`action`、`resource`、`error`、`webVitals`、`blankScreen`、`device`
 
-View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数见 `references/plugins.md`。
+View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数按「任务路由」读取对应 `plugins-*.md`。
 
 ## 关键易错点
 

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

@@ -123,7 +123,7 @@ Fetch/XHR 由 `createCommonInstrumentationsPlugin()` 的单一生命周期直接
 | 入口 | 作用范围 | 适合用途 |
 | --- | --- | --- |
 | `privacy.redactUrl` | SDK 写入的 URL 类属性 | 删除 query/hash、模板化路径 |
-| `privacy.redactAttributes` | 通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
+| `privacy.redactAttributes` | Resource、通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
 | `tracking.request.beforeSend` | 单个 Fetch/XHR，带原始 Request/Response/XHR 上下文 | 请求专属补充或丢弃 |
 | Request Body `redact` | 单个请求/响应 Body，必填 | 内容级脱敏；返回 `undefined` 跳过该 Body |
 | `tracking.beforeSend` | Span/Log 进入底层 processor 前 | 最终兜底修改或丢弃；不作用于 Metric |

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

@@ -18,7 +18,7 @@
 | 手动 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 | 作为公共属性 | — | 作为公共属性 |
+| 设备 | `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` | — | — |

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

@@ -38,7 +38,7 @@ const bkOT = new BkOpenTelemetry(options);
 | `environment` | `string` | `production` | `deployment.environment.name` |
 | `version` | `string` | 无 | `service.version` |
 
-SDK 还会固定写入 `rum.provider=blueking`、`rum.schema.version=1`、`telemetry.sdk.name=@blueking/open-telemetry` 和 `telemetry.sdk.language=webjs`。
+SDK 还会固定写入 `rum.schema.version=2`、`telemetry.sdk.name=@blueking/open-telemetry`、`telemetry.sdk.language=webjs` 和当前包版本 `telemetry.sdk.version`。默认启用 `tracking.device` 时，浏览器、OS 和稳定的硬件能力也会写入 Resource。
 
 ## transport
 
@@ -216,7 +216,7 @@ tracking: {
 | --- | --- | --- | --- |
 | `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
 | `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
-| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | SDK 创建 Span/Log 和内置插件属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span/Log 和内置插件属性脱敏 |
 
 第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
 

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

@@ -0,0 +1,135 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 基础采集插件
+
+基础插件负责建立 RUM 数据的关联上下文：哪个用户、哪个会话、哪个页面、哪个设备。
+
+以下片段聚焦对应的 `session` 或 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
+## session
+
+`session` 维护 `session.id`，并在会话开始和轮换时写入 log。它是所有 RUM 信号的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
+
+默认规则：
+
+- 不活跃超过 15 分钟后过期，下一次用户交互时轮换。
+- 会话最长 4 小时。
+- storage key 会按 endpoint host 隔离。
+- 页面重新可见只续期有效会话，不会复活已过期会话。
+- 跨 Tab 共享持久化状态，但已过期的 Tab 需要自身发生用户交互后才接管新会话。
+
+```ts
+new BkOpenTelemetry({
+  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
+
+`device` 插件采集设备、浏览器、系统、视口和网络信息。默认开启。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    device: {
+      persistentId: true,
+      storageKey: 'bk-rum-device',
+    },
+  },
+});
+```
+
+稳定的浏览器、系统和硬件能力写入三类信号共享的 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 span/log 会自动携带，便于按浏览器、系统、网络类型下钻。
+
+`device.id` 默认只在当前 SDK 实例内稳定；只有显式设置 `persistentId: true` 才写入 localStorage，并按应用名隔离默认 storage key。
+
+**产出遥测**：写入 Resource 属性（如 `browser.name`、`os.name`、`device.type`、`device.memory_gib`）和运行时属性（如 `device.id`、`browser.viewport.*`、`network.effective_type`），本身不单独产生 span/metric/log。
+
+## 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({
+  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');
+      },
+    },
+  },
+});
+```
+
+自动模式只在 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，观察交互后的请求、DOM 变更、资源、错误和长任务，在页面活动稳定后生成一个 `action` span。
+
+**产出遥测**：span `action.<type>`（如 `action.click`，`span_type=action`）。`reportAction()` 走同一套字段。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    action: {
+      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({
+  name: '立即支付',
+  attributes: {
+    'biz.order_id': '202605270001',
+  },
+});
+```

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

@@ -0,0 +1,86 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 错误与安全插件
+
+以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
+错误类插件帮助定位 JavaScript 异常、Promise 异常、资源加载失败、CSP 违规和空白屏等问题。
+
+## error
+
+`error` 插件默认开启，监听：
+
+- `window.error`
+- `unhandledrejection`
+- 资源加载错误
+
+插件会生成 error span，并使用 fingerprint 做窗口内节流，避免相同错误在短时间内刷屏。
+
+**产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带异常摘要、`error.source`、`error.window_occurrence_index`；精确总量由 `browser.error.count` 记录。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    error: {
+      maxPerWindow: 5,
+      windowMs: 60_000,
+    },
+  },
+});
+```
+
+## 手动上报错误事件
+
+业务捕获到错误后，可以通过 `reportCustomEvent()` 上报。
+
+```ts
+try {
+  await submitOrder();
+} catch (error) {
+  bkOT.reportCustomEvent({
+    name: 'submit_order_failed',
+    error: error instanceof Error ? error : new Error(String(error)),
+    attributes: {
+      'biz.order_id': '202605270001',
+    },
+  });
+}
+```
+
+## cspViolation
+
+`cspViolation` 插件默认关闭。开启后监听浏览器 `securitypolicyviolation` 事件，并写入 error span。
+
+**产出遥测**：span `csp.violation`（`span_type=error`），带 `csp.*` 字段；完整策略 `csp.original_policy` 仅在节流窗口首条携带。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    cspViolation: true,
+  },
+});
+```
+
+建议与站点 CSP 响应头一起使用。
+
+```http
+Content-Security-Policy: default-src 'self'; report-uri /csp-report
+```
+
+## blankScreen 与错误排查
+
+空白屏通常是错误、资源失败或首屏渲染失败的结果。建议同时开启 `blankScreen`、`error`、`resource`。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    blankScreen: {
+      rootSelector: '#app',
+    },
+    error: true,
+    resource: true,
+  },
+});
+```
+
+通过 `view.id` 和 `session.id` 可以把空白屏、JS 错误、资源失败关联到同一次页面访问。

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

@@ -0,0 +1,125 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 体验与性能插件
+
+体验类插件关注页面加载、资源、核心 Web 指标、空白屏、主线程阻塞和 SPA 路由切换。
+
+以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
+## resource
+
+`resource` 插件默认开启，基于 PerformanceObserver 采集静态资源加载 span。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    resource: true,
+  },
+});
+```
+
+常见字段包括 `resource.type`、`resource.size`、`resource.protocol`、`url.full`、`server.address`。当 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。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({
+  tracking: {
+    webVitals: true,
+  },
+});
+```
+
+## blankScreen
+
+`blankScreen` 插件默认开启。它会针对每个 View 等待页面活动稳定后执行九点分层采样；只有两次连续检测都超过阈值才上报。View 切换或页面隐藏会取消旧检测，恢复可见后重新调度。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    blankScreen: {
+      rootSelector: '#app',
+      checkDelay: 1000,
+      confirmationDelay: 200,
+      threshold: 0.8,
+      ignoreSelectors: ['.global-loading', '.skeleton'],
+    },
+  },
+});
+```
+
+SPA 应用建议配置 `rootSelector`。根节点在确认阶段仍不存在时会以 `missing_root` 原因上报；loading 和骨架屏样本不进入空白比例分母。
+
+**产出遥测**（仅判定为白屏时）：metric `browser.blank_screen.count` + error span `browser.blank_screen`（`span_type=error`）。
+
+## longTask
+
+`longTask` 插件默认关闭。开启后优先通过 Long Animation Frames API 采集主线程阻塞；浏览器不支持时自动回退到 Long Tasks API，两种入口不会重复观察。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    longTask: {
+      threshold: 50,
+      warningThreshold: 100,
+    },
+  },
+});
+```
+
+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`）。
+
+## View Loading Time
+
+View Loading Time 属于 View 管理器，默认启用，基于页面活动结束时间计算。
+
+自动计算规则：
+
+- 初始加载：取 `navigationStart → loadEventEnd` 与 `navigationStart → 页面活动结束` 的较大值。
+- SPA 路由：取 View 创建到页面活动结束的耗时。
+- Fetch/XHR 进行中、静态资源完成和 DOM Mutation 都属于活动；连续 100ms 无活动视为稳定。
+- SDK 自身上报、`view.excludedActivityUrls` 命中的请求，以及 `data-bk-excluded-activity-mutations` 节点下的 DOM 变更不参与计算。
+
+```ts
+new BkOpenTelemetry({
+  tracking: {
+    view: {
+      loadingTime: true,
+      excludedActivityUrls: [/\/events\/stream$/, '/analytics'],
+    },
+  },
+});
+```
+
+如果业务有明确的异步渲染完成点，可覆盖自动结果：
+
+```ts
+await loadAlarmDetail();
+bkOT.setViewLoadingTime();
+```

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

@@ -0,0 +1,141 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 网络与扩展插件
+
+网络能力覆盖 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，也不会为同一请求叠加两套生命周期。
+
+### 请求生命周期
+
+一次请求按以下顺序处理：
+
+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`，常用属性包括 `http.request.method`、`http.response.status_code`、`url.full`、`server.address`、网络阶段与响应体积。
+
+```ts
+new BkOpenTelemetry({
+  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;
+      },
+    },
+  },
+});
+```
+
+`request.beforeSend` 在请求完成后执行，可修改 Span attributes；返回 `false` 会标记该 Span 在最终 processor 中丢弃，并立即跳过该请求的 Body Log。Hook 抛错不会中断业务请求，`debug: true` 时输出 warning。
+
+### excludedUrls 与 excludedActivityUrls
+
+| 配置 | 是否创建 Span | 是否计入 View/Action 活动 | 适用场景 |
+| --- | --- | --- | --- |
+| `tracking.request.excludedUrls` | 否 | 否 | 探活、埋点、无需采集的请求 |
+| `tracking.view.excludedActivityUrls` | 是 | 否 | 长轮询、SSE、流式接口，不应阻塞页面稳定 |
+
+两者都支持字符串包含、RegExp 和函数 matcher。
+
+### traceparent 注入条件
+
+只有 `allowedTracingUrls` 命中且 Trace 信号开启时才进入传播 Header 注入分支；默认 W3C propagator 会注入 `traceparent`，同源请求也不隐式放行。
+
+```ts
+tracking: {
+  request: {
+    allowedTracingUrls: [
+      url => new URL(url).origin === 'https://api.example.com',
+      /^https:\/\/[^/]+\.internal\.example\.com\//,
+    ],
+  },
+}
+```
+
+字符串 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 决定，可能还包含其他传播字段。
+
+### Resource Timing
+
+Fetch/XHR 与静态资源共用一个 Resource PerformanceObserver：
+
+- `initiatorType=fetch|xmlhttprequest` 的 entry 只用于匹配请求 Span，不再创建静态资源 Span。
+- 通过 URL 与时间窗口匹配；找不到 entry 时请求 Span 仍正常结束。
+- 跨域接口缺少 `Timing-Allow-Origin` 时，浏览器不会提供完整阶段字段。
+- Trace 关闭时跳过 timing 等待，因为不存在可导出的请求 Span。
+
+### 请求/响应 Body
+
+Body 默认关闭。开启时必须提供 `redact`，默认只采集状态未知、0 或 `>=400` 的请求：
+
+```ts
+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 body;
+      },
+    },
+  },
+}
+```
+
+**产出遥测**：Log `browser.request.body`，错误请求为 ERROR，`capture: 'all'` 下成功请求为 INFO。
+
+- 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
+
+`tracking.websocket` 默认关闭。开启后用 Proxy 包装 `window.WebSocket`，保留静态常量、`instanceof` 与子类化行为。
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'realtime-demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: { websocket: true },
+});
+```
+
+**产出遥测**：
+
+- 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`：记录错误阶段和关闭详情。
+
+插件不读取消息内容，只计算数量和字节数。超过 64KB 的字符串使用 `string.length` 近似字节数，避免编码开销；CJK/emoji 会低估。相同 URL 的错误 Log 在 60 秒内最多 5 条，Error Counter 不受节流影响。
+
+SDK shutdown 后新建连接不再采集；已存在连接上的包装会保留，但回调立即返回。若其他库后来替换了 `window.WebSocket`，shutdown 不会强行覆盖后来者。
+
+## 与额外 instrumentation 的关系
+
+`extensions.instrumentations` 适合已有标准 OpenTelemetry instrumentation。不要再注册覆盖 Fetch/XHR 或用户交互的 instrumentation，否则可能与内置 request/action 重复 patch、重复 Span。
+
+需要 Session/View、`emitLog()`、页面活动或 RUM 归一字段时，优先写自定义插件，见[内置采集与扩展](./concepts.md)与[自定义插件](./custom-plugin.md)。