@blueking/open-telemetry 0.0.13 → 0.0.15

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

@@ -2,51 +2,49 @@
 
 # 插件总览
 
-插件是 `@blueking/open-telemetry` 的能力边界。SDK 内部先启动官方 instrumentation，再按采样结果启动 RUM 插件。
+插件是 `@blueking/open-telemetry` 的能力边界。获得采集授权后，SDK 先建立 Device、Session、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,
   },
 });
 ```
 
+`session` 和 View 生命周期是不可关闭的 RUM 基础能力；`tracking.view` 只切换自动/手动策略及 loading time。
+
 ## 能力分类
 
 | 分类       | 插件                                                              | 主要信号                      |
 | ---------- | ----------------------------------------------------------------- | ----------------------------- |
-| 基础上下文 | `session`、`device`、`pageView`                                   | log、span、runtime attributes |
-| 性能体验   | `resource`、`webVitals`、`blankScreen`、`longTask`、`routeTiming` | span、metric、log             |
+| 基础上下文 | Session、View、`device`                                           | log、span、runtime attributes |
+| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span、metric、log          |
 | 错误安全   | `error`、`cspViolation`                                           | span、log                     |
-| 网络扩展   | `httpBody`、`websocket`                                           | log、span、metric             |
+| 网络扩展   | request instrumentation、`websocket`                              | span、metric                  |
 | 用户行为   | `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 +55,8 @@ new BkOpenTelemetry({
 ## 选择建议
 
 - 首次接入：使用默认插件即可。
-- 需要分析慢页面：开启 `longTask` 和 `routeTiming`。
-- 需要分析接口错误体：开启 `httpBody`，并配置 `redact`。
+- 需要分析慢页面：View Loading Time 默认开启；再开启 `longTask` 获取主线程与脚本归因。
+- 需要为请求增加业务字段或过滤请求：配置 `request.beforeSend` / `request.excludedUrls`。
 - 需要分析 CSP：开启 `cspViolation`。
 - 需要分析实时通信：开启 `websocket`，注意避免多个 SDK 实例重复 patch。
 
@@ -66,28 +64,30 @@ new BkOpenTelemetry({
 
 基础插件负责建立 RUM 数据的关联上下文：哪个用户、哪个会话、哪个页面、哪个设备。
 
+以下片段聚焦对应的 `session` 或 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+
 ## session
 
-`session` 插件维护 `session.id`，并在会话开始和轮换时写入 log。默认开启。
+`session` 维护 `session.id`，并在会话开始和轮换时写入 log。它是所有 RUM 信号的关联边界，命中采样后始终开启，不能关闭。
 
 默认规则：
 
-- 不活跃超过 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 +96,9 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     device: {
+      persistentId: true,
       storageKey: 'bk-rum-device',
     },
   },
@@ -106,56 +107,85 @@ 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' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: { view: { tracking: 'manual' } },
+});
+
+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',
     },
   },
 });
 ```
 
+自动命名默认只读取 `data-bk-action-name`、`aria-label`、`title` 等显式或无障碍名称，不读取任意文本内容。如确实需要文本命名，可显式设置 `nameCollection: 'text'`，并自行评估隐私风险。
+
 对关键业务动作，推荐使用 `reportAction()` 显式上报，字段更稳定。
 
 ```ts
 bkOT.reportAction({
-  type: 'click',
-  targetTag: 'button',
-  targetText: '立即支付',
+  name: '立即支付',
   attributes: {
     'biz.order_id': '202605270001',
   },
@@ -166,31 +196,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 +248,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 +264,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`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
+**产出遥测**：metric `browser.long_task.count` / `browser.long_task.duration` / `browser.long_task.blocking_duration`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
 
-## routeTiming
+## View Loading Time
 
-`routeTiming` 插件默认关闭。它会监听 SPA 路由变化，并通过双 `requestAnimationFrame` 和 `setTimeout` 估算路由切换到渲染稳定的耗时。
+View Loading Time 属于 View 管理器，默认启用，基于页面活动结束时间计算。
 
-**产出遥测**：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 +336,7 @@ span.end();
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     error: {
       maxPerWindow: 5,
       windowMs: 60_000,
@@ -313,7 +371,7 @@ try {
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     cspViolation: true,
   },
 });
@@ -331,7 +389,7 @@ Content-Security-Policy: default-src 'self'; report-uri /csp-report
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     blankScreen: {
       rootSelector: '#app',
     },
@@ -345,63 +403,71 @@ new BkOpenTelemetry({
 
 # 网络与扩展插件
 
-网络类能力覆盖 fetch/xhr、HTTP body 错误路径和 WebSocket。由于这些能力会 patch 浏览器原生 API，微前端或多 SDK 实例场景需要特别注意避免重复初始化。
+以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
 
-## fetch / xhr instrumentation
+网络类能力覆盖 Fetch/XHR Resource 和 WebSocket。由于这些能力会 patch 浏览器原生 API，微前端或多 SDK 实例场景需要特别注意避免重复初始化。
 
-fetch 和 xhr 默认开启，会生成 HTTP span，并对 URL 做脱敏处理。
+## request instrumentation
 
-**产出遥测**：HTTP span（span 名由官方探针决定，如 `HTTP GET`，`span_type=http`），带 `http.request.method`、`http.response.status_code`、`url.full`、`status_class` 等。
+request 默认开启，使用 OpenTelemetry 官方 Fetch/XHR instrumentation 生成一个请求 Resource Span，并对 URL 做脱敏。静态资源观察器会跳过 Fetch/XHR timing，因此同一请求不会重复上报。
+
+**产出遥测**：Resource Span（如 `HTTP GET`，`span_type=resource`、`resource.type=fetch|xhr`），带 `resource.url`、`resource.method`、`resource.status_code`、网络阶段 span events 和请求/响应大小。
 
 ```ts
 new BkOpenTelemetry({
   privacy: {
     redactUrl: url => url.replace(/\/orders\/\d+/g, '/orders/:id'),
   },
-  instrumentations: {
-    fetch: true,
-    xhr: true,
+  tracking: {
+    request: {
+      excludedUrls: [/\/health(?:\?|$)/],
+      beforeSend: event => {
+        event.attributes['business.module'] = 'order';
+        return true;
+      },
+    },
   },
 });
 ```
 
 ### traceparent 透传（前后端 trace 串联）
 
-fetch/xhr 请求会自动给**同源**请求注入 W3C `traceparent` 请求头（内含 OpenTelemetry traceId）。后台 API 通常是跨域的，需要通过 `propagateTraceHeaderUrls` 显式纳入注入范围：
+只有命中 `allowedTracingUrls` 的请求才会注入 W3C `traceparent`。同源请求也不会隐式注入：
 
 ```ts
 new BkOpenTelemetry({
-  instrumentations: {
-    // 字符串子串 / 正则 / 数组 / (url) => boolean / 'all' 均可
-    propagateTraceHeaderUrls: ['api.example.com', /\.internal\.com\//],
+  tracking: {
+    request: {
+      allowedTracingUrls: ['api.example.com', /\.internal\.com\//],
+    },
   },
 });
 ```
 
-向跨域服务注入自定义头会触发 CORS 预检，目标服务需在 `Access-Control-Allow-Headers` 中放行 `traceparent`（以及按需的 `tracestate`）。`propagateTraceHeaderUrls` 的完整取值（`'all'` / 字符串 / 正则 / 数组 / 函数）见[配置总览](./configuration.md#instrumentation-配置)。
+向跨域服务注入自定义头会触发 CORS 预检，目标服务需在 `Access-Control-Allow-Headers` 中放行 `traceparent`（以及按需的 `tracestate`）。
 
-## httpBody
+### 错误请求 body
 
-`httpBody` 默认关闭。开启后只在错误路径采集请求/响应 body，适合排查接口错误，但必须配置脱敏策略。
-
-**产出遥测**：log `HTTP request completed`（成功，INFO）/ `HTTP request completed with error`（错误，ERROR，带 `http.request.body`、`http.response.body`、`http_body.*.truncated`）。
+body 默认不采集。显式配置 `request.body` 后，默认只采集 4xx/5xx、状态码 0 或网络异常请求的请求体和响应体，并生成关联原 Trace/Span 的 `browser.request.body` 诊断 Log：
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    httpBody: {
-      maxBodySize: 10 * 1024,
-      redact: ({ body, status, type }) => {
-        if (status && status < 500) {
-          return '[body hidden for non-5xx error]';
-        }
-        return type === 'request' ? '[request body redacted]' : body;
+  tracking: {
+    request: {
+      body: {
+        capture: 'errors',
+        maxSize: 10 * 1024,
+        allowedContentTypes: ['application/json', /^text\//],
+        redact: ({ body, kind }) =>
+          kind === 'request' ? body.replace(/("(?:password|token)"\s*:\s*)"[^"]*"/g, '$1"***"') : body,
       },
     },
   },
 });
 ```
 
+Fetch Request 会在官方 request hook 中先 clone，Response 也通过 clone 限量读取，不消费业务侧原始流；XHR request body 复用官方 send patch 记录，不再增加一层原型 patch。不支持文本化的 FormData、ArrayBuffer 和二进制响应会跳过。
+
 ## websocket
 
 `websocket` 默认关闭。开启后会用 Proxy 包装 WebSocket，采集连接、消息大小、错误和关闭事件。
@@ -410,7 +476,7 @@ new BkOpenTelemetry({
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
+  tracking: {
     websocket: true,
   },
 });

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 脱敏
 
@@ -40,7 +42,7 @@ new BkOpenTelemetry({
 
 ## 公共属性
 
-`attributes` 提供四类 hook：
+`context.attributes` 提供四类 hook：
 
 - `page`：页面、动作、错误等需要页面上下文的事件。
 - `metric`：metric 维度，必须避免高基数字段。
@@ -49,20 +51,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 +77,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 +112,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');
+      },
     },
   },
 });