@blueking/open-telemetry 0.0.22-beta.1 → 0.0.23

package/skills/bk-rum-otele/references/views-routing.md

@@ -0,0 +1,211 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# View、路由与页面稳定时间
+
+View 表示一次可独立分析的页面体验。初始文档加载、SPA 路由、BFCache 恢复、Session 续期和业务手动划分都可以创建新 View。View 是普通 RUM Span 的必要上下文，不能关闭。
+
+## View 类型
+
+| `view.loading_type` | 创建场景 | `span_type` |
+| --- | --- | --- |
+| `initial_load` | 初始自动 View；手动模式第一次 `startView()` | `view` |
+| `route_change` | SPA 自动路由；手动模式后续 `startView()` | `view` |
+| `bf_cache` | 从 Back/Forward Cache 恢复 | `view` |
+| `session_renewal` | Session 过期后新 Session 接管当前页面 | `view` |
+
+每个 View 都生成新的 `view.id`。View 名称、URL、路由分组和自定义属性作为运行时上下文挂到其间发生的普通 Span。
+
+## 自动路由模式
+
+`tracking.view.tracking` 默认为 `auto`。SDK：
+
+- 启动时创建初始 View；
+- 观察 `history.pushState()`、`history.replaceState()`、`popstate` 和 `hashchange`；
+- pathname 改变时创建新 View；
+- 非页内锚点的 hash path 改变时创建新 View；
+- query-only 变化不创建 View；
+- 指向当前页面真实元素 ID 的 hash 视为页内锚点，不创建 View。
+
+路由触发源写入 `view.source`，初始加载为 `load`，手动调用为 `manual`，其余使用对应 History/浏览器事件名。
+
+## 手动 View 模式
+
+框架路由希望完全控制边界时：
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'order-web' },
+  autoStart: false,
+  transport: { endpoint: 'https://rum.example.com' },
+  tracking: {
+    view: { tracking: 'manual' },
+  },
+});
+
+await bkOT.start();
+bkOT.startView({
+  name: '订单详情',
+  url: location.href,
+  attributes: { 'biz.page_owner': 'order-team' },
+});
+```
+
+必须先建立采样有效的 Session。`startView()` 在尚未启动、未授权、未采样或没有 Session 时被忽略。手动模式第一次 `startView()` 之前没有有效 View，因此普通 Span 不会导出。
+
+`attributes` 会经过 `redactAttributes`，并删除 SDK 所有保留字段；业务无法通过 View attributes 覆盖 `session.*`、`view.*`、`span_type` 或 `outcome.*`。
+
+## View 名称和路由分组
+
+默认 `view.url_path_group` 是 URL pathname，`view.name` 默认等于该分组。
+
+```ts
+tracking: {
+  view: {
+    getPathGroup(url) {
+      return new URL(url, location.href).pathname
+        .replace(/\/orders\/[^/]+/, '/orders/:id')
+        .replace(/\/users\/[^/]+/, '/users/:id');
+    },
+  },
+}
+```
+
+`getPathGroup()` 应返回低基数、稳定的路由模板。当前业务 View 默认实现不会自动把数字、UUID 或其他业务 ID 替换为 `:id`，接入方必须按自己的路由规则显式提供模板。
+
+运行期可修改名称：
+
+```ts
+bkOT.setViewName('订单详情-只读');
+```
+
+名称变化不会创建新 View，但会更新运行时上下文并发送 `browser.view` update。传入与当前相同名称时不发送更新。
+
+## URL 与前序页面
+
+- `view.url`：当前 URL，经 `privacy.redactUrl`。
+- `view.url_path_group`：聚合路由模板。
+- `url.previous`：前一个原始 URL 经脱敏；初始加载为空字符串。
+- `document.referrer`：仅初始自动加载写入并脱敏。
+
+用于路由判断的是原始 URL，写入遥测的是脱敏 URL。自定义 `redactUrl` 不会影响是否切换 View。
+
+## View 生命周期 Span
+
+Span 名固定为 `browser.view`：
+
+| phase | 触发 |
+| --- | --- |
+| `start` | 创建 View |
+| `update` | Loading Time 就绪、手动覆盖 Loading Time、名称变化 |
+| `end` | 新 View、pagehide、BFCache、Session 过期或 SDK shutdown |
+
+每条生命周期 Span 都是瞬时事件，并携带递增的 `view.version`。常见 `view.end_reason`：
+
+- 新自动路由的触发源，例如 `pushState`、`popstate`
+- `manual`
+- `bfcache`
+- `pagehide`
+- `session_expired`
+- `shutdown`
+
+服务端应按 `view.id + view.version` 幂等合并，而不是依赖网络到达顺序。
+
+## 初始导航时间
+
+初始 View 尝试从 `PerformanceNavigationTiming` 读取：
+
+| 字段 | 浏览器原值 | 单位 |
+| --- | --- | --- |
+| `view.first_byte` | `responseStart` | 相对 `performance.timeOrigin` 的 ms |
+| `view.dom_interactive` | `domInteractive` | 同上 |
+| `view.dom_content_loaded` | `domContentLoadedEventEnd` | 同上 |
+| `view.dom_complete` | `domComplete` | 同上 |
+| `view.load_event` | `loadEventEnd` | 同上 |
+
+值必须有限且大于 0 才写入。它们是相对导航起点的时间，不是 epoch 时间戳。
+
+## 自动 View Loading Time
+
+`tracking.view.loadingTime` 默认 `true`。SDK 同时等待：
+
+1. 页面活动进入稳定状态；
+2. 初始加载的 `window.load` / `loadEventEnd` 可用。
+
+页面活动包括：
+
+- Fetch/XHR 开始和结束；
+- 静态 Resource 完成；
+- DOM Mutation；
+- `window.open` 等活动总线事件。
+
+页面从 View 创建后先观察 100ms：没有任何页面活动时，活动侧不提供候选值；发生过活动后，所有请求完成且连续 100ms 无新活动即认为稳定。
+
+- 初始加载：只要能取得 `loadEventEnd`，即使前 100ms 没有其他活动，也可生成 Loading Time；最终取 `loadEventEnd` 与页面活动结束耗时的较大值。
+- SPA/BFCache/Session Renewal：只有观察到页面活动时才生成自动 Loading Time，取 View 开始到页面活动结束的耗时。
+- 页面在计算期间变为 hidden：取消自动计算，不上报不可靠结果。
+
+`view.loading_time.source=auto` 表示自动计算。
+
+## 排除长轮询和无关活动
+
+持续连接、埋点和轮询可能让页面永远无法稳定：
+
+```ts
+tracking: {
+  view: {
+    excludedActivityUrls: [
+      /\/events\/stream(?:\?|$)/,
+      url => new URL(url).pathname === '/health',
+    ],
+  },
+}
+```
+
+匹配项支持字符串包含、正则和函数。该配置只决定请求/资源是否延长 View/Action 活动窗口，不等于关闭请求 Span；完全不采集应使用 `tracking.request.excludedUrls`。
+
+DOM 子树可使用导出的 `EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE` 对应属性 `data-bk-excluded-activity-mutations` 标记，使其 Mutation 不延长页面活动。
+
+## 手动覆盖 Loading Time
+
+业务知道真实渲染完成点时：
+
+```ts
+await renderAsyncContent();
+bkOT.setViewLoadingTime();
+```
+
+SDK 计算“调用时刻 - View 开始时间”，取消仍在进行的自动计算，并发送 update：
+
+- `view.loading_time.source=manual`
+- 多次调用以后一次为准；每次都会产生新版本 update。
+- 没有采样有效 View 时忽略。
+
+## BFCache
+
+页面以 `pagehide.persisted=true` 进入 BFCache 时：
+
+1. 结束当前 View，`view.end_reason=bfcache`。
+2. 保存旧 View 的名称、URL 和自定义属性。
+3. `pageshow.persisted=true` 时创建新的 `bf_cache` View。
+
+冻结时间不会计入旧 View 或恢复后的新 View。如果恢复时 Session 已过期，SDK等到新 Session 建立后再创建 `session_renewal` View。
+
+## 常见问题
+
+### SPA 只有初始 View
+
+检查路由是否只改变 query；自动模式明确忽略 query-only 变化。需要以 query 区分业务页面时使用手动 View。
+
+### View Loading Time 一直没有出现
+
+检查：
+
+- 页面是否在计算期间进入后台；
+- 页面是否完全没有可观察活动；
+- 是否有未结束长轮询；
+- `tracking.view.loadingTime` 是否为 `false`；
+- 是否在手动模式首次 `startView()` 前观察数据。
+
+### View 数量过多
+
+确认是否同时使用自动模式和框架 `startView()`。手动同步路由时必须设 `tracking: 'manual'`。

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

@@ -1,60 +0,0 @@
-<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
-
-# 核心概念
-
-## 单一原始事件通道
-
-SDK 只使用 OpenTelemetry Trace：浏览器事实和本地体验语义都编码为 RUM Span，通过 `/v1/rum` 上报。浏览器不创建 Counter、Histogram 或 Log；聚合由服务端完成。
-
-## Session、View、Action
-
-- `session.id` 关联一次访问会话，采样以 Session 为边界。
-- `view.id` 关联初始页面、SPA 路由、BFCache 或手动 View。
-- `action.id` 关联一次用户动作活动窗口。
-- `user.id` 由接入方提供，SDK 原样透传。
-
-生命周期事件使用 `event.id`、`event.type`、`event.phase`、`event.timestamp`。View 额外使用 `view.version` 处理更新和乱序。
-
-## 本地计算边界
-
-SDK 只保留必须依赖浏览器本地状态的计算：CLS、INP、View Loading Time、Action Loading Time、挫败信号和白屏判断。错误分组、计数、分位数和跨事件聚合全部交给服务端。
-
-## 采样
-
-`session.sampleRate` 使用 `application.name + session.id` 做确定性采样。采样率同时写入 Resource 的 `session.sample_rate`，供后端修正总体指标。
-
-## 扩展
-
-自定义 RUM 插件使用 `context.startSpan()`，标准 OpenTelemetry instrumentation 通过 `extensions.instrumentations` 注册。避免重复注册 Fetch/XHR 或用户交互探针。
-
-# 内置采集与扩展
-
-`tracking` 只配置 SDK 内置采集能力；`extensions` 只注册接入方提供的扩展实例。
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: {
-    request: true,
-    error: true,
-    longTask: false,
-  },
-  extensions: {
-    plugins: [myRumPlugin],
-    instrumentations: [myOtelInstrumentation],
-  },
-});
-```
-
-| 类型 | 配置位置 | 适用场景 |
-| --- | --- | --- |
-| 内置采集 | `tracking` | View、请求、资源、错误、Web Vitals、Action 等 |
-| RUM 插件 | `extensions.plugins` / `use()` | 需要 Session/View、日志、指标和活动总线的浏览器语义 |
-| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 已有标准 instrumentation，直接使用 SDK 私有 provider |
-
-内置 Fetch/XHR 不再基于官方 instrumentation 叠加适配，而是由单一请求生命周期实现，避免重复 patch、重复活动计数及私有 `_addHeaders/_patchSend` 依赖。
-
-当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。SDK 不创建 Metric Provider，第三方 instrumentation 的 Metric 不属于支持范围。
-
-扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。

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

@@ -1,170 +0,0 @@
-<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
-
-# 自定义插件
-
-自定义插件适合封装业务事件、补充特定浏览器 API 采集，或接入额外 OpenTelemetry instrumentation。
-
-## 插件契约
-
-插件由 `createPlugin()` 创建，核心字段是 `name`、`enabled`、`init`、`flush`、`shutdown`。
-
-```ts
-import { createPlugin } from '@blueking/open-telemetry';
-
-const bizPlugin = createPlugin({
-  name: 'biz-plugin',
-  enabled: config => config.enabled,
-  init(context) {
-    const span = context.startSpan('custom.biz_plugin_init', {
-      'biz.plugin': 'ready',
-    });
-    span.end();
-  },
-  flush() {
-    // 可在这里刷新插件内部缓存
-  },
-  shutdown() {
-    // 可在这里移除事件监听
-  },
-});
-```
-
-## 注册插件
-
-`use()` 必须在 `start()` 之前调用。
-
-```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-import { bizPlugin } from './biz-plugin';
-
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'plugin-demo' },
-  autoStart: false,
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-
-bkOT.use(bizPlugin);
-
-await bkOT.start();
-```
-
-## 使用 runtime context
-
-`init(context)` 中可以访问 `tracer`、`startSpan()`、`getRuntimeAttributes()` 等能力。
-
-优先使用 `context.startSpan()`：它会合并事件发生时的运行时上下文并应用 SDK 脱敏。
-
-```ts
-let teardownVisibility = () => {};
-
-const visibilityPlugin = createPlugin({
-  name: 'visibility-change',
-  init(context) {
-    const onVisibilityChange = () => {
-      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);
-    teardownVisibility = () => document.removeEventListener('visibilitychange', onVisibilityChange);
-  },
-  shutdown() {
-    teardownVisibility();
-  },
-});
-```
-
-## 清理事件监听
-
-插件应在 `shutdown()` 中释放自己注册的监听器。
-
-```ts
-const resizePlugin = createPlugin({
-  name: 'window-resize',
-  init(context) {
-    const onResize = () => {
-      const span = context.startSpan('custom.window_resize', {
-        'window.inner_width': window.innerWidth,
-        'window.inner_height': window.innerHeight,
-      });
-      span.end();
-    };
-
-    window.addEventListener('resize', onResize);
-
-    this.shutdown = () => {
-      window.removeEventListener('resize', onResize);
-    };
-  },
-});
-```
-
-更推荐使用闭包保存清理函数，避免依赖 `this`。
-
-```ts
-const createResizePlugin = () => {
-  let teardown = () => {};
-
-  return createPlugin({
-    name: 'window-resize',
-    init(context) {
-      const onResize = () => {
-        const span = context.startSpan('custom.window_resize');
-        span.end();
-      };
-
-      window.addEventListener('resize', onResize);
-      teardown = () => window.removeEventListener('resize', onResize);
-    },
-    shutdown() {
-      teardown();
-    },
-  });
-};
-```
-
-## 注册额外 instrumentation
-
-第三方 OpenTelemetry instrumentation 放在 `extensions.instrumentations`，或通过 `useInstrumentation()` 链式注册。两者区别详见 [内置采集与扩展](./concepts.md)。
-
-配置式：
-
-```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'extension-demo' },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-  extensions: {
-    instrumentations: [new SomeWebInstrumentation()],
-  },
-});
-```
-
-链式（适合运行时动态追加，必须在 `start()` 之前）：
-
-```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'extension-demo' },
-  autoStart: false,
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-
-bkOT.useInstrumentation(new SomeWebInstrumentation());
-
-await bkOT.start();
-```
-
-> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束。
-
-## 自定义信号边界
-
-SDK 插件上下文不提供 Meter、Logger 或 `emitLog()`。具体业务行为使用 Span；计数、分布和分位数由服务端从 Span 派生。

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

@@ -1,135 +0,0 @@
-<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
-
-# 基础采集插件
-
-基础插件负责建立 RUM 数据的关联上下文：哪个用户、哪个会话、哪个页面、哪个设备。
-
-以下片段聚焦对应的 `session` 或 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
-
-## session
-
-`session` 维护 `session.id`，并在会话开始、轮换和结束时写入 `browser.session` 生命周期 Span。它是所有 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；下一次用户交互续期时，同时创建新的 Session 和 View。
-
-**产出遥测**：`browser.session` start/rotate/end Span，并维护 `session.id`、`session.start_time`、`session.type`。
-
-## device
-
-`device` 插件采集设备、浏览器、系统、视口和网络信息。默认开启。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    device: {
-      persistentId: true,
-      storageKey: 'bk-rum-device',
-    },
-  },
-});
-```
-
-稳定的浏览器、系统和硬件能力写入 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 Span 会自动携带。
-
-`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。
-
-## 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 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路。手动模式在首次 `startView()` 前不会导出普通 RUM 数据。
-
-View Loading Time 默认开启：初始加载取 `loadEventEnd` 与页面活动结束时间的较大值，SPA 路由取 View 创建到页面活动结束的耗时。请求、静态资源和 DOM 变更都属于页面活动，连续 100ms 无活动视为稳定。长轮询或埋点请求应配置到 `view.excludedActivityUrls`；业务也可在真正渲染完成时调用 `setViewLoadingTime()` 覆盖自动结果。
-
-**产出遥测**：`browser.view` start/update/end 原始生命周期 Span。每次事件携带 `view.version`，Loading Time 就绪或 View 名称变化时产生 update。
-
-## 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

@@ -1,86 +0,0 @@
-<!-- 本文件由 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.message`、`error.source` 和标准 exception event。SDK 不做错误指纹、计数或节流。
-
-```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 错误、资源失败关联到同一次页面访问。