@blueking/open-telemetry 0.0.6 → 0.0.8

package/README.md

@@ -1,213 +1,197 @@
 # @blueking/open-telemetry
 
-面向浏览器 RUM 场景的 OpenTelemetry SDK 封装，默认会采集页面访问、错误、Web Vitals、设备、会话、fetch/xhr 等常用 RUM 数据，并通过 OTLP HTTP 上报。
+蓝鲸监控 RUM OT SDK，使用 OpenTelemetry 采集页面访问、接口请求、静态资源、错误、Web Vitals、设备和会话等数据，并通过 OTLP HTTP 上报。
 
-## 安装使用
+## 安装和使用
 
-### npm 引入
+```bash
+# npm
+npm install @blueking/open-telemetry
+
+# pnpm
+pnpm add @blueking/open-telemetry
+
+# yarn
+yarn add @blueking/open-telemetry
+```
+
+### npm 包使用
 
 ```javascript
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-  environment: 'production',
+  app: {
+    name: 'demo-app',
+    environment: 'production',
+    version: '1.0.0',
+  },
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
+  user: {
+    id: window.USER_ID,
+  },
 });
 ```
 
-### CDN 引入
+### CDN 使用
 
 ```html
 <script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
 <script>
-  const bkOT = new BkOpenTelemetry({
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
-    environment: 'production',
+  const bkOT = new window.BkOpenTelemetry({
+    app: {
+      name: 'demo-app',
+      environment: 'production',
+      version: '1.0.0',
+    },
+    transport: {
+      endpoint: 'https://your-otlp-collector',
+      token: 'your-report-token',
+    },
+    user: {
+      id: window.USER_ID,
+    },
   });
 </script>
 ```
 
-## 最小配置
-
-```javascript
-new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-});
-```
+默认 `autoStart: true`，所以 `new BkOpenTelemetry()` 后 SDK 会自动启动。
 
-`endpoint` 是 OTLP collector 地址，SDK 会自动拼出三类信号地址：
+`transport.endpoint` 填 OTLP collector 根地址即可，SDK 会自动生成：
 
 - traces: `endpoint/v1/traces`
 - metrics: `endpoint/v1/metrics`
 - logs: `endpoint/v1/logs`
 
-如果三类信号需要发到不同地址，可以分别配置：
+`transport.token` 会变成请求头：`Authorization: Bearer <token>`。
 
-```javascript
-new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-  signalEndpoints: {
-    traces: 'https://your-trace-collector/rum',
-    metrics: 'https://your-metric-collector/v1/metrics',
-    logs: 'https://your-log-collector/v1/logs',
-  },
-});
-```
+## 2. 先理解默认采集
 
-`signalEndpoints.traces`、`signalEndpoints.metrics`、`signalEndpoints.logs` 是完整上报地址，不会自动拼 `/v1/*`；未配置时会回退到对应的 `traces.endpoint`、`metrics.endpoint`、`logs.endpoint`，再回退到统一 `endpoint`。
+不写 `rum` 配置时，SDK 已经默认开启常用 RUM 能力：
 
-`token` 会转换为上报请求头：
+- 页面加载：`documentLoad`
+- 页面访问：`pageView`
+- 接口请求：`fetch`、`xhr`
+- 静态资源：`resource`
+- JS 错误：`error`
+- 页面体验：`webVitals`、`blankScreen`
+- 用户环境：`device`、`session`
+- 用户交互 instrumentation：`userInteraction`
 
-```txt
-Authorization: Bearer your-report-token
-```
+默认关闭的能力需要手动打开：
+
+- `action`: 用户点击、输入、提交等操作事件
+- `httpBody`: 请求/响应 body 采集
+- `longTask`: 长任务
+- `routeTiming`: 路由耗时
+- `cspViolation`: CSP 违规
+- `websocket`: WebSocket 事件
 
-## 基础配置
+## 3. 给数据加上用户和路由
 
 ```javascript
-new BkOpenTelemetry({
-  token: 'your-report-token',
-  environment: 'production',
-  enabled: true,
-  debug: false,
-  sampleRate: 1,
-  spanProcessor: 'batch',
-  headers: {
-    'X-Custom-Header': 'value',
+const bkOT = new BkOpenTelemetry({
+  app: {
+    name: 'demo-app',
+    environment: 'production',
+    version: '1.0.0',
+  },
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
   },
-  signalEndpoints: {
-    traces: 'https://your-trace-collector/rum',
-    metrics: 'https://your-metric-collector/v1/metrics',
-    logs: 'https://your-log-collector/v1/logs',
+  user: {
+    id: window.USER_ID,
+  },
+  route: {
+    getPathGroup: url => new URL(url).pathname,
   },
 });
 ```
 
-- `endpoint`: 上报地址BaseURL，默认 `http://localhost:4318`。
-- `token`: 上报 token，会写入 `Authorization: Bearer xxx`。
-- `environment`: 环境名，默认 `production`。
-- `enabled`: 是否启用 SDK，默认 `true`。
-- `debug`: 是否在控制台打印上报数据，默认 `false`。
-- `sampleRate`: 采样率，范围 `0 - 1`，默认 `1`。
-- `spanProcessor`: trace 处理模式，默认 `batch`；可选 `simple` 用于本地调试。
-- `headers`: 附加上报请求头，显式传入的 header 可覆盖 token 生成的同名 header。
-- `signalEndpoints`: 分别配置 trace、metric、log 的完整上报地址，优先级高于统一 `endpoint`。
-- `traces` / `metrics` / `logs`: 分别配置 trace、metric、log 的高级请求参数；其中 `endpoint` 优先级低于 `signalEndpoints`。
+`route.getPathGroup` 用来把高基数 URL 归类成低基数路径。例如 `/user/123` 可以归类成 `/user/:id`，方便聚合分析。
+
+运行过程中也可以更新上下文：
 
-`spanProcessor: 'batch'` 会批量缓存并定时上报 trace，适合生产环境；`spanProcessor: 'simple'` 会在 span 结束后立即触发导出，适合本地调试，不建议生产环境使用。
+```javascript
+bkOT.setUser({ id: 'user-001' });
 
-## RUM 采集配置
+bkOT.setView({
+  id: 'view-001',
+  url: location.href,
+  urlPathGroup: '/user/:id',
+  loadingType: 'route_change',
+});
+```
 
-所有采集能力统一放在 `rum` 下配置：
+## 4. 按需打开更多能力
 
 ```javascript
 new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
   rum: {
-    documentLoad: true,
-    fetch: true,
-    xhr: true,
-    userInteraction: true,
-    pageView: true,
-    error: true,
-    webVitals: true,
-    blankScreen: true,
-    device: true,
-    session: true,
-    websocket: true,
-    longTask: { threshold: 50 },
-    routeTiming: true,
-    cspViolation: true,
-    httpBody: {
-      maxBodySize: 4 * 1024,
-      redact: ({ body, type }) => (type === 'request' ? body.replace(/password/g, '***') : body),
+    plugins: {
+      action: true,
+      longTask: { threshold: 50 },
+      routeTiming: true,
+      websocket: true,
+      cspViolation: true,
+      httpBody: {
+        maxBodySize: 4 * 1024,
+        redact: ({ body }) => body.replace(/password=[^&]+/g, 'password=***'),
+      },
+      blankScreen: {
+        rootSelector: '#app',
+        checkDelay: 3000,
+        threshold: 0.8,
+        ignoreSelectors: ['.app-loading', '.page-skeleton'],
+      },
     },
   },
 });
 ```
 
-默认开启：`documentLoad`、`fetch`、`xhr`、`userInteraction`、`pageView`、`error`、`webVitals`、`blankScreen`、`device`、`session`、`websocket`。
-
-默认关闭：`httpBody`、`longTask`、`routeTiming`、`cspViolation`。
-
-常用说明：
-
-- `documentLoad`: 采集页面加载性能。
-- `fetch` / `xhr`: 采集 HTTP 请求，并给同源请求注入 `traceparent`。
-- `userInteraction`: 采集用户交互。
-- `pageView`: 采集页面访问和 SPA 路由变化。
-- `error`: 采集 JS 错误、未处理 Promise rejection、资源加载失败。
-- `webVitals`: 采集 LCP、CLS、INP、FCP、TTFB。
-- `blankScreen`: 检测白屏，SPA 项目建议显式配置 `rootSelector` 为应用挂载点（详见下文「白屏检测」）。
-- `device`: 采集浏览器、系统、网络等设备信息。
-- `session`: 维护匿名会话。
-- `websocket`: 采集 WebSocket 连接和消息事件。
-- `longTask`: 采集长任务，`threshold` 表示最小时长阈值。
-- `routeTiming`: 采集 SPA 路由切换耗时。
-- `cspViolation`: 采集 CSP violation。
-- `httpBody`: 采集请求/响应 body，建议配合 `redact` 做脱敏。
-
-### 白屏检测
-
-页面就绪后延迟一段时间，在视口的 5 个采样点用 `document.elementFromPoint` 判断这些点是否落在"根元素"或裸 body 上，命中比例超过阈值即视为白屏。命中后会同时上报：
-
-- metric: `browser.blank_screen.count`（仅带低基数维度 `bk.rum.blank_screen.root`）
-- log: `browser.blank_screen`（携带评分、命中元素、DOM 节点数等高基数信息）
-
-完整配置示例：
+如果要关闭默认能力，显式写 `false`：
 
 ```javascript
 new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
   rum: {
-    blankScreen: {
-      // SPA 项目强烈建议设置为应用挂载点，例如 '#app' / '#root'
-      rootSelector: '#app',
-      // 页面 ready 后延迟多少毫秒开始检测，默认 3000
-      checkDelay: 3000,
-      // 命中比例阈值，范围 0 - 1，默认 0.8
-      threshold: 0.8,
-      // 自定义"加载中"占位选择器，命中样本会从分母里剔除，避免骨架屏被误判为白屏
-      ignoreSelectors: ['.app-loading', '.page-skeleton'],
+    plugins: {
+      webVitals: false,
+      blankScreen: false,
+    },
+    instrumentations: {
+      fetch: false,
+      xhr: false,
     },
   },
 });
 ```
 
-配置项说明：
-
-- `rootSelector`: 默认 `body`。**SPA 项目（React/Vue 等）必须显式配置为应用挂载点**，否则一旦应用成功 mount，采样点会落在挂载根（如 `#app`）的子节点上，永远不会判定为白屏；反之挂载失败时挂载根本身仍存在，配置成 `#app` 后才能正确命中。
-- `checkDelay`: 从 `DOMContentLoaded` 起算的延迟（毫秒），默认 `3000`。SPA 首屏渲染较慢的项目可以适当调大。
-- `threshold`: 命中比例阈值（0 - 1），默认 `0.8`。
-- `ignoreSelectors`: 项目自定义的"加载中"占位选择器。SDK 内置了一组通用兜底（`[data-loading="true"]`、`[aria-busy="true"]`、`.loading`、`.is-loading`、`.spinner`、`.skeleton`、`.bk-loading`），但**强烈建议项目按自己的骨架屏/loading 约定显式追加**，命中此选择器的样本既不算"空白"也不算"非空白"，会从分母里剔除。
-
-判定算法（伪代码）：
-
-```text
-score = empty_samples / (total_samples - loading_samples)
-isBlank = score >= threshold
-```
-
-如果所有采样点都命中 loading（说明页面整体还在加载），本次检测会被视为待定，不上报。
-
-## 公共属性
+## 5. 加公共属性和脱敏
 
-通过 `attributes` 给不同类型数据补充公共属性：
+公共属性适合放业务线、页面、环境等每条数据都想带上的信息。
 
 ```javascript
 new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
   attributes: {
     page: () => ({
-      'rum.page.host': window.location.host,
-      'rum.page.path': window.location.pathname,
+      'rum.page.host': location.host,
+      'rum.page.path': location.pathname,
     }),
     custom: () => ({
       'biz.team': 'demo',
@@ -219,53 +203,32 @@ new BkOpenTelemetry({
       'biz.metric_source': 'rum',
     }),
   },
-});
-```
-
-- `page`: 页面、错误、指标、自定义事件等都会常用的页面属性。
-- `custom`: 自定义事件公共属性。
-- `error`: 错误事件公共属性。
-- `metric`: 指标类数据公共属性。
-
-## 脱敏配置
-
-通过 `redact` 统一处理敏感数据：
-
-```javascript
-new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-  redact: {
-    attributes: attributes => {
-      const result = { ...attributes };
-      for (const key of Object.keys(result)) {
-        const value = result[key];
-        if (typeof value === 'string' && /\b\d{15}|\d{18}\b/.test(value)) {
-          result[key] = value.replace(/\d/g, '*');
+  privacy: {
+    redactUrl: url => url.replace(/token=[^&]+/g, 'token=***'),
+    redactAttributes: attributes => {
+      const next = { ...attributes };
+      for (const key of Object.keys(next)) {
+        if (typeof next[key] === 'string') {
+          next[key] = next[key].replace(/\b\d{11}\b/g, '***');
         }
       }
-      return result;
+      return next;
     },
-    url: url => url.replace(/token=[^&]+/g, 'token=***'),
   },
 });
 ```
 
-- `redact.attributes`: 过滤写入 span/log 的属性。
-- `redact.url`: 过滤 URL 类属性，例如 `url.full`、`document.referrer`。
-
-`rum.httpBody.redact` 只处理请求/响应 body，适合对 body 里的密码、token 等字段做单独脱敏。
-
-## 自定义事件
+- `attributes.page`: 页面、接口、资源等 RUM 数据都会带上。
+- `attributes.custom`: `reportCustomEvent` 上报的自定义事件会带上。
+- `attributes.error`: 错误数据会带上。
+- `attributes.metric`: 指标数据会带上。
+- `privacy.redactUrl`: 处理 URL，例如 `url.full`、`document.referrer`。
+- `privacy.redactAttributes`: 处理 span/log 属性。
+- `rum.plugins.httpBody.redact`: 只处理请求/响应 body。
 
-`new BkOpenTelemetry()` 会返回 SDK 实例，可以通过 `reportCustomEvent` 上报业务自定义事件：
+## 6. 手动上报业务事件
 
 ```javascript
-const bkOT = new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-});
-
 bkOT.reportCustomEvent({
   name: 'order.checkout',
   attributes: {
@@ -275,7 +238,7 @@ bkOT.reportCustomEvent({
 });
 ```
 
-如果事件失败，可以带上 `error`：
+失败事件可以带 `error`：
 
 ```javascript
 bkOT.reportCustomEvent({
@@ -287,9 +250,93 @@ bkOT.reportCustomEvent({
 });
 ```
 
-## 自定义插件
+也可以手动上报用户操作：
+
+```javascript
+bkOT.reportAction({
+  type: 'click',
+  targetText: '立即购买',
+  targetTag: 'button',
+});
+```
 
-通过 `createPlugin` 扩展 SDK 能力：
+## 7. 控制采样、调试和上报
+
+```javascript
+new BkOpenTelemetry({
+  debug: true,
+  sampling: {
+    rate: 0.2,
+  },
+  spanProcessor: 'batch',
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+    headers: {
+      'X-Custom-Header': 'value',
+    },
+    signals: {
+      traces: {
+        timeoutMillis: 10000,
+      },
+    },
+  },
+});
+```
+
+- `debug`: 打开后会在控制台输出调试信息。
+- `sampling.rate`: 采样率，范围 `0 - 1`，默认 `1`。
+- `spanProcessor`: 默认 `batch`；本地调试可用 `simple`。
+- `transport.headers`: 给所有信号加请求头。
+- `transport.signals.traces/metrics/logs`: 分别配置不同信号。
+
+如果三类信号要发到不同地址：
+
+```javascript
+new BkOpenTelemetry({
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+    signals: {
+      endpoints: {
+        traces: 'https://your-trace-collector/v1/traces',
+        metrics: 'https://your-metric-collector/v1/metrics',
+        logs: 'https://your-log-collector/v1/logs',
+      },
+    },
+  },
+});
+```
+
+请求头优先级为：`token` 默认头 < `transport.headers` < 单信号 `headers`。
+
+## 8. 生命周期
+
+```javascript
+await bkOT.flush();
+await bkOT.shutdown();
+```
+
+- `flush`: 立即刷新插件、trace、metric、log。
+- `shutdown`: 刷新后关闭 SDK，并卸载事件监听。
+
+如果你要先注册插件，再手动启动：
+
+```javascript
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
+});
+
+await bkOT.start();
+```
+
+## 9. 扩展插件
+
+普通用户通常不需要看这一节。只有当默认采集不够用时，再使用插件扩展。
 
 ```javascript
 import { BkOpenTelemetry, createPlugin } from '@blueking/open-telemetry';
@@ -308,19 +355,23 @@ const plugin = createPlugin({
 
 const bkOT = new BkOpenTelemetry({
   autoStart: false,
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
   plugins: [plugin],
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
 });
 
 await bkOT.start();
 ```
 
-也可以通过 `use(plugin)` 链式注册，`use(plugin)` 只允许在 `start()` 前调用；自定义插件场景建议显式设置 `autoStart: false`。
+也可以在 `start()` 前链式注册：
 
-## 自定义 Instrumentation
+```javascript
+bkOT.use(plugin);
+```
 
-如需接入 OpenTelemetry 原生 instrumentation，可通过 `useInstrumentation` 注册：
+## 10. 接入原生 OpenTelemetry Instrumentation
 
 ```javascript
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
@@ -328,61 +379,18 @@ import { MyCustomInstrumentation } from './my-custom-instrumentation';
 
 const bkOT = new BkOpenTelemetry({
   autoStart: false,
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
   instrumentations: [new MyCustomInstrumentation()],
+  transport: {
+    endpoint: 'https://your-otlp-collector',
+    token: 'your-report-token',
+  },
 });
 
 await bkOT.start();
 ```
 
-也可以通过 `useInstrumentation(instrumentation)` 在 `start()` 前注册。
-
-## 生命周期
+也可以在 `start()` 前链式注册：
 
 ```javascript
-const bkOT = new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-});
-
-await bkOT.flush();
-await bkOT.shutdown();
-```
-
-- `flush`: 立即刷新插件、trace、metric、log。
-- `shutdown`: 刷新后关闭 SDK，并卸载事件监听。
-
-## 完整示例
-
-```javascript
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-
-export const bkOT = new BkOpenTelemetry({
-  endpoint: 'https://your-otlp-collector',
-  token: 'your-report-token',
-  environment: 'production',
-  debug: false,
-  sampleRate: 1,
-  rum: {
-    fetch: true,
-    xhr: true,
-    documentLoad: true,
-    userInteraction: true,
-    longTask: { threshold: 50 },
-    routeTiming: true,
-    httpBody: {
-      maxBodySize: 4 * 1024,
-      redact: ({ body }) => body.replace(/("password"\s*:\s*)"[^"]*"/g, '$1"***"'),
-    },
-  },
-  attributes: {
-    custom: () => ({
-      'biz.team': 'rum-demo',
-    }),
-  },
-  redact: {
-    url: url => url.replace(/token=[^&]+/g, 'token=***'),
-  },
-});
+bkOT.useInstrumentation(new MyCustomInstrumentation());
 ```