@blueking/open-telemetry 0.0.13 → 0.0.15

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

@@ -10,7 +10,7 @@
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  app: { name: 'bk-rum-demo' },
+  application: { name: 'bk-rum-demo' },
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 ```
@@ -27,7 +27,10 @@ const bkOT = new BkOpenTelemetry({
 | `use(plugin)` | `(plugin) => this` | 注册自定义插件，须在 `start()` 前。 |
 | `useInstrumentation(instr)` | `(instr) => this` | 注册额外 OpenTelemetry instrumentation，须在 `start()` 前。 |
 | `setUser(user)` | `(user) => void` | 更新用户上下文（`user.id`）。 |
-| `setView(view)` | `(view) => void` | 更新当前 view 上下文。 |
+| `setTrackingConsent(consent)` | `(consent) => Promise<void>` | 授予或撤销采集授权，并启动或停止采集。 |
+| `startView(options?)` | `(options?) => void` | 结束当前 View 并创建新 View。可在 SDK 启动前调用。 |
+| `setViewName(name)` | `(name) => void` | 更新当前 View 名称，不创建新 View。 |
+| `setViewLoadingTime()` | `() => void` | 使用当前时刻覆盖当前 View 的自动页面稳定耗时。 |
 | `reportAction(payload)` | `(payload) => void` | 手动上报用户动作（受采样控制）。 |
 | `reportCustomEvent(payload)` | `(payload) => void` | 手动上报自定义事件（受采样控制）。 |
 | `startSpan(name, attributes?, options?)` | `(...) => Span` | 创建并返回一个 span，自动带上运行时属性与脱敏。 |
@@ -46,6 +49,7 @@ const bkOT = new BkOpenTelemetry({
 
 ```ts
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'bk-rum-demo' },
   autoStart: false,
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
@@ -105,28 +109,53 @@ bkOT.setUser({
 });
 ```
 
-### setView
+### setTrackingConsent
 
-更新当前 view 上下文。
+运行期更新采集授权。撤销授权会停止插件与浏览器 API patch，并刷新已允许采集的数据；再次授权会重新建立 Session/View 和采集能力。
 
 ```ts
-bkOT.setView({
-  id: 'view-home',
+await bkOT.setTrackingConsent('granted');
+await bkOT.setTrackingConsent('not-granted');
+```
+
+### startView
+
+创建新的 View，并结束前一个 View。`view.id` 由 SDK 生成，业务侧不能覆盖。
+
+```ts
+bkOT.startView({
+  name: '首页',
   url: window.location.href,
-  urlPathGroup: '/home',
-  loadingType: 'initial_load',
+  attributes: {
+    'biz.owner': 'portal-team',
+  },
 });
 ```
 
+### setViewName
+
+只修改当前 View 的 `view.name`，后续子事件使用新名称。
+
+```ts
+bkOT.setViewName('首页-新版');
+```
+
+### setViewLoadingTime
+
+当自动页面活动无法表达业务真正的渲染完成点时，手动覆盖当前 View 的 `view.loading_time`。每次调用都会替换前一次结果。
+
+```ts
+await renderAsyncPage();
+bkOT.setViewLoadingTime();
+```
+
 ### reportAction
 
 手动上报用户动作。
 
 ```ts
 bkOT.reportAction({
-  type: 'click',
-  targetTag: 'button',
-  targetText: '保存',
+  name: '保存',
   attributes: {
     'biz.form': 'alarm-strategy',
   },
@@ -218,11 +247,14 @@ span.end();
 import { resolveConfig } from '@blueking/open-telemetry';
 
 const config = resolveConfig({
-  app: {
+  application: {
     name: 'bk-rum-demo',
   },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
 });
 
-console.log(config.app.name);
+console.log(config.application.name);
 console.log(config.transport.traces.endpoint);
 ```

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

@@ -10,7 +10,7 @@
 
 - Trace：用于描述一次有起止时间的行为，例如页面访问、接口请求、资源加载、用户点击、长任务。
 - Metric：用于描述可聚合的数值，例如 Web Vitals、长任务数量、WebSocket 消息大小、空白屏结果。
-- Log：用于描述离散事件或诊断信息，例如错误、CSP 违规、Session 生命周期、HTTP body 错误路径。
+- Log：用于描述离散事件或诊断信息，例如 CSP 违规、Session 生命周期和 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,33 @@ bkOT.setUser({
 });
 ```
 
-示例：业务路由系统主动设置 view 上下文。
+示例：手动模式由业务路由系统创建 View。
 
 ```ts
-bkOT.setView({
-  id: 'view-product-detail',
+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` 使用统一的 Fetch/XHR 生命周期实现，负责 patch 浏览器 API、创建 CLIENT Span、Trace Header 和请求 Performance Timing 匹配。
+2. RUM 插件：View、Session、`resource`、`error`、`webVitals`、`blankScreen`、`device` 等，负责主动产生 RUM 归一数据。
 
-示例：关闭官方用户交互 instrumentation，仅使用 SDK 的 `action` 插件。
+用户交互统一由 SDK 的 `action` 插件采集，避免与官方 user-interaction instrumentation 重复上报。
 
 ```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 +80,15 @@ new BkOpenTelemetry({
 
 ## 采样
 
-`sampling.rate` 是会话级 sticky 采样。一次会话命中后，RUM 插件和手动事件都会上报；未命中时，主动产生数据的插件不会启动，`reportAction()` 和 `reportCustomEvent()` 会丢弃。
+`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件会维护必要的页面生命周期，但未命中时 sampler/processor 不导出其数据，`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 +100,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 +122,32 @@ 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';
-
-const bizPlugin = createPlugin({
-  name: 'biz-plugin',
-  init(context) {
-    const span = context.startSpan('custom.biz_ready');
-    span.end();
-  },
-});
-```
+| 类型 | 配置位置 | 适用场景 |
+| --- | --- | --- |
+| 内置采集 | `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` 依赖。
 
-- 只想 patch 一个浏览器/网络 API、拿标准遥测数据 → 用 **Instrumentation**（优先看官方是否已有现成包）。
-- 想产生带 RUM 归一字段（`span_type`、`result`、`target_label` 等）的业务事件、需要访问运行时上下文 → 用 **Plugin**。
-- 想让能力跟随采样开关、只对命中会话生效 → 必须做成 **Plugin**（RUM 数据类）。
+扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。