@blueking/open-telemetry 0.0.14 → 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 生命周期、HTTP body 错误路径。
+- Log：用于描述离散事件或诊断信息，例如 Session 生命周期、View Snapshot、请求 Body 和 WebSocket 状态。
 
 示例：手动创建一个业务 span。
 
@@ -18,7 +18,7 @@
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  app: { name: 'checkout-web' },
+  application: { name: 'checkout-web' },
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
@@ -36,7 +36,7 @@ SDK 会维护运行时公共上下文，并自动挂到后续 span/log 上：
 
 - `user.id`：由接入方提供，SDK 原样透传，不 hash、不脱敏、不改写。
 - `session.id`：由 session 插件生成和轮换，用于关联同一次访问会话。
-- `view.id` / `view.url` / `view.url_path_group`：由 pageView 插件维护，用于关联同一个页面或路由实例。
+- `view.id` / `view.name` / `view.url` / `view.url_path_group`：由 View 管理器维护，用于关联同一个页面或路由实例。
 
 示例：登录后更新用户上下文。
 
@@ -46,34 +46,34 @@ bkOT.setUser({
 });
 ```
 
-示例：业务路由系统主动设置 view 上下文。
+示例：手动模式由业务路由系统创建 View。
 
 ```ts
-bkOT.setView({
-  id: 'view-product-detail',
+// 前提：autoStart: false，且已经 await bkOT.start() 建立 Session。
+bkOT.startView({
+  name: '商品详情',
   url: window.location.href,
-  urlPathGroup: '/product/:id',
-  loadingType: 'route_change',
+  attributes: { 'biz.owner': 'product-team' },
 });
 ```
 
-## Instrumentation 与插件
+## 内置采集与扩展
 
 SDK 将能力分为两类：
 
-1. 官方 instrumentation：`documentLoad`、`fetch`、`xhr`、`userInteraction`，主要负责 patch 浏览器 API 或读取标准浏览器性能数据。
-2. RUM 插件：`pageView`、`resource`、`error`、`webVitals`、`blankScreen`、`device`、`session` 等，负责主动产生 RUM 归一数据。
+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 归一数据。
 
-示例：关闭官方用户交互 instrumentation，仅使用 SDK 的 `action` 插件。
+用户交互统一由 SDK 的 `action` 插件采集。接入额外 instrumentation 时，应避免再注册覆盖 Fetch/XHR 或用户交互的探针，以免重复上报。
 
 ```ts
 new BkOpenTelemetry({
-  instrumentations: {
-    userInteraction: false,
-  },
-  plugins: {
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
     action: {
-      eventNames: ['click', 'submit', 'keydown'],
+      actionNameAttribute: 'data-bk-action-name',
+      maxDuration: 10000,
     },
   },
 });
@@ -81,14 +81,15 @@ new BkOpenTelemetry({
 
 ## 采样
 
-`sampling.rate` 是会话级 sticky 采样。一次会话命中后，RUM 插件和手动事件都会上报；未命中时，主动产生数据的插件不会启动，`reportAction()` 和 `reportCustomEvent()` 会丢弃。
+`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件仍会维护必要的浏览器生命周期，但未命中时创建或导出路径会丢弃数据，`reportAction()` 和 `reportCustomEvent()` 直接返回。
 
 示例：生产环境按 10% 会话采样。
 
 ```ts
 new BkOpenTelemetry({
-  sampling: {
-    rate: 0.1,
+  application: { name: 'demo' },
+  session: {
+    sampleRate: 0.1,
   },
   transport: {
     endpoint: 'https://rum-collector.example.com',
@@ -100,7 +101,7 @@ new BkOpenTelemetry({
 
 SDK 会为 span 补充 RUM 归一字段，例如：
 
-- `span_type`：`document`、`http`、`resource`、`vital`、`error`、`longtask`、`action`、`route`、`custom`
+- `span_type`：`document`、`resource`、`vital`、`error`、`longtask`、`action`、`route`、`custom`
 - `result`：`success`、`warning`、`error`、`timeout`、`abort`
 - `duration_bucket`：`<100ms`、`100~500ms`、`500ms~2s`、`>2s`
 - `target_label`：跨类型的主标签，用于统一检索
@@ -122,106 +123,34 @@ const span = bkOT.startSpan('custom.cache_warmup', {
 span.end();
 ```
 
-# Plugin 与 Instrumentation 的区别
-
-`@blueking/open-telemetry` 把采集能力拆成两类：**官方 Instrumentation** 和 **RUM 插件（Plugin）**。两者在配置入口、数据来源、生命周期和采样行为上都不同，理解差异有助于按需裁剪采集能力。
-
-## 一句话区分
+# 内置采集与扩展
 
-- **Instrumentation**：OpenTelemetry 官方/第三方探针，负责 patch 浏览器原生 API 或读取标准性能数据，是「数据从哪来」的底层来源。
-- **Plugin**：bk-ot 自研的能力单元，基于 runtime context 主动产生 RUM 归一数据，是「我们要采什么、怎么归一」的业务层。
-
-## 配置入口
-
-两类能力在配置上完全对称，分别挂在顶层的 `instrumentations` 和 `plugins` 下：
+`tracking` 只配置 SDK 内置采集能力；`extensions` 只注册接入方提供的扩展实例。
 
 ```ts
 new BkOpenTelemetry({
-  // 官方探针：开关 + 自定义实例
-  instrumentations: {
-    documentLoad: true,
-    fetch: true,
-    xhr: true,
-    userInteraction: true,
-    custom: [new MyCustomInstrumentation()],
-  },
-  // bk-ot 自研插件：开关 + 自定义插件
-  plugins: {
-    pageView: true,
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: {
+    request: true,
     error: true,
-    webVitals: true,
-    custom: [myBizPlugin],
+    longTask: false,
   },
-});
-```
-
-## 内置能力清单
-
-| 类型            | 内置项                                                                                                                       |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Instrumentation | `documentLoad`、`fetch`、`xhr`、`userInteraction`                                                                            |
-| Plugin          | `pageView`、`resource`、`error`、`webVitals`、`blankScreen`、`device`、`session`、`action`、`httpBody`、`longTask`、`routeTiming`、`cspViolation`、`websocket` |
-
-## 核心差异对比
-
-| 维度         | Instrumentation                                  | Plugin                                              |
-| ------------ | ------------------------------------------------ | --------------------------------------------------- |
-| 来源         | OpenTelemetry 官方包 / 第三方                    | bk-ot 自研                                          |
-| 职责         | patch 原生 API、读取标准性能数据                 | 基于 runtime context 主动产生 RUM 归一数据          |
-| 配置位置     | `instrumentations: {}`                           | `plugins: {}`                                       |
-| 自定义扩展   | `instrumentations.custom` / `useInstrumentation()` | `plugins.custom` / `use()` / `createPlugin()`     |
-| 启动条件     | **SDK 启用（`enabled`）即装载**                  | 官方探针适配插件随 SDK 启用；产生 RUM 数据的插件**仅采样命中时启动** |
-| 受采样影响   | 否                                               | 是（RUM 数据插件未命中采样时不启动）                |
-
-## 生命周期与采样
-
-这是两者最容易混淆、也最关键的差异：
-
-- **Instrumentation 不受采样影响**。只要 `enabled !== false`，官方探针与 `instrumentations.custom` 中的实例都会在 `start()` 时注册。它们 patch 的是底层 API，需要在采样判定之前就位。
-
-  > 注意：这里的"不受采样影响"指的是**是否装载/patch**。未命中采样的会话，trace sampler 的比例为 `0`，探针产生的 span 仍会在采样阶段被丢弃、不会上报。也就是说 patch 照做，但数据最终不落库。
-- **RUM 插件受采样影响**。`sampling.rate` 是会话级 sticky 采样，未命中的会话不会启动主动产生数据的插件，`reportAction()`、`reportCustomEvent()` 也会丢弃。
-
-> 说明：SDK 内部把官方 instrumentation 封装成一个核心适配插件（`official-instrumentations`），它与自研 RUM 插件走同一套插件生命周期，但归属于「SDK 启用即装载」的核心插件，不参与采样开关。
-
-## 如何扩展
-
-### 接入第三方 Instrumentation
-
-两种等价写法，都必须在 `start()` 之前：
-
-```ts
-// 写法一：配置式
-new BkOpenTelemetry({
-  autoStart: false,
-  instrumentations: {
-    custom: [new MyCustomInstrumentation()],
+  extensions: {
+    plugins: [myRumPlugin],
+    instrumentations: [myOtelInstrumentation],
   },
 });
-
-// 写法二：链式（适合运行时动态追加）
-bkOT.useInstrumentation(new MyCustomInstrumentation());
-await bkOT.start();
 ```
 
-### 编写自研 Plugin
-
-通过 `createPlugin()` 访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()` 等 runtime context 能力，详见[自定义插件](./custom-plugin.md)。
-
-```ts
-import { createPlugin } from '@blueking/open-telemetry';
+| 类型 | 配置位置 | 适用场景 |
+| --- | --- | --- |
+| 内置采集 | `tracking` | View、请求、资源、错误、Web Vitals、Action 等 |
+| RUM 插件 | `extensions.plugins` / `use()` | 需要 Session/View、日志、指标和活动总线的浏览器语义 |
+| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 已有标准 instrumentation，直接使用 SDK 私有 provider |
 
-const bizPlugin = createPlugin({
-  name: 'biz-plugin',
-  init(context) {
-    const span = context.startSpan('custom.biz_ready');
-    span.end();
-  },
-});
-```
+内置 Fetch/XHR 不再基于官方 instrumentation 叠加适配，而是由单一请求生命周期实现，避免重复 patch、重复活动计数及私有 `_addHeaders/_patchSend` 依赖。
 
-## 选择建议
+当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。Metric exporter 要求 SDK 内部采样标记，而包未公开对应 helper，因此第三方 instrumentation 产生的 Metric 默认会被过滤，不应作为已支持的扩展能力。
 
-- 只想 patch 一个浏览器/网络 API、拿标准遥测数据 → 用 **Instrumentation**（优先看官方是否已有现成包）。
-- 想产生带 RUM 归一字段（`span_type`、`result`、`target_label` 等）的业务事件、需要访问运行时上下文 → 用 **Plugin**。
-- 想让能力跟随采样开关、只对命中会话生效 → 必须做成 **Plugin**（RUM 数据类）。
+扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。