@blueking/open-telemetry 0.0.4 → 0.0.6

package/README.md

@@ -0,0 +1,388 @@
+# @blueking/open-telemetry
+
+面向浏览器 RUM 场景的 OpenTelemetry SDK 封装，默认会采集页面访问、错误、Web Vitals、设备、会话、fetch/xhr 等常用 RUM 数据，并通过 OTLP HTTP 上报。
+
+## 安装使用
+
+### npm 引入
+
+```javascript
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+  environment: 'production',
+});
+```
+
+### 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',
+  });
+</script>
+```
+
+## 最小配置
+
+```javascript
+new BkOpenTelemetry({
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+});
+```
+
+`endpoint` 是 OTLP collector 地址，SDK 会自动拼出三类信号地址：
+
+- traces: `endpoint/v1/traces`
+- metrics: `endpoint/v1/metrics`
+- logs: `endpoint/v1/logs`
+
+如果三类信号需要发到不同地址，可以分别配置：
+
+```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',
+  },
+});
+```
+
+`signalEndpoints.traces`、`signalEndpoints.metrics`、`signalEndpoints.logs` 是完整上报地址，不会自动拼 `/v1/*`；未配置时会回退到对应的 `traces.endpoint`、`metrics.endpoint`、`logs.endpoint`，再回退到统一 `endpoint`。
+
+`token` 会转换为上报请求头：
+
+```txt
+Authorization: Bearer your-report-token
+```
+
+## 基础配置
+
+```javascript
+new BkOpenTelemetry({
+  token: 'your-report-token',
+  environment: 'production',
+  enabled: true,
+  debug: false,
+  sampleRate: 1,
+  spanProcessor: 'batch',
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+  signalEndpoints: {
+    traces: 'https://your-trace-collector/rum',
+    metrics: 'https://your-metric-collector/v1/metrics',
+    logs: 'https://your-log-collector/v1/logs',
+  },
+});
+```
+
+- `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`。
+
+`spanProcessor: 'batch'` 会批量缓存并定时上报 trace，适合生产环境；`spanProcessor: 'simple'` 会在 span 结束后立即触发导出，适合本地调试，不建议生产环境使用。
+
+## RUM 采集配置
+
+所有采集能力统一放在 `rum` 下配置：
+
+```javascript
+new BkOpenTelemetry({
+  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),
+    },
+  },
+});
+```
+
+默认开启：`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 节点数等高基数信息）
+
+完整配置示例：
+
+```javascript
+new BkOpenTelemetry({
+  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'],
+    },
+  },
+});
+```
+
+配置项说明：
+
+- `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（说明页面整体还在加载），本次检测会被视为待定，不上报。
+
+## 公共属性
+
+通过 `attributes` 给不同类型数据补充公共属性：
+
+```javascript
+new BkOpenTelemetry({
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+  attributes: {
+    page: () => ({
+      'rum.page.host': window.location.host,
+      'rum.page.path': window.location.pathname,
+    }),
+    custom: () => ({
+      'biz.team': 'demo',
+    }),
+    error: () => ({
+      'biz.error_source': 'browser',
+    }),
+    metric: () => ({
+      '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, '*');
+        }
+      }
+      return result;
+    },
+    url: url => url.replace(/token=[^&]+/g, 'token=***'),
+  },
+});
+```
+
+- `redact.attributes`: 过滤写入 span/log 的属性。
+- `redact.url`: 过滤 URL 类属性，例如 `url.full`、`document.referrer`。
+
+`rum.httpBody.redact` 只处理请求/响应 body，适合对 body 里的密码、token 等字段做单独脱敏。
+
+## 自定义事件
+
+`new BkOpenTelemetry()` 会返回 SDK 实例，可以通过 `reportCustomEvent` 上报业务自定义事件：
+
+```javascript
+const bkOT = new BkOpenTelemetry({
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+});
+
+bkOT.reportCustomEvent({
+  name: 'order.checkout',
+  attributes: {
+    'biz.order_id': 'O20260509001',
+    'biz.order_amount': 199,
+  },
+});
+```
+
+如果事件失败，可以带上 `error`：
+
+```javascript
+bkOT.reportCustomEvent({
+  name: 'order.checkout',
+  attributes: {
+    'biz.order_id': 'O20260509001',
+  },
+  error: new Error('库存不足'),
+});
+```
+
+## 自定义插件
+
+通过 `createPlugin` 扩展 SDK 能力：
+
+```javascript
+import { BkOpenTelemetry, createPlugin } from '@blueking/open-telemetry';
+
+const plugin = createPlugin({
+  name: 'demo-plugin',
+  init(context) {
+    context.setRuntimeAttributes({
+      'biz.plugin_enabled': true,
+    });
+
+    const span = context.startSpan('demo.plugin_ready');
+    span.end();
+  },
+});
+
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+  plugins: [plugin],
+});
+
+await bkOT.start();
+```
+
+也可以通过 `use(plugin)` 链式注册，`use(plugin)` 只允许在 `start()` 前调用；自定义插件场景建议显式设置 `autoStart: false`。
+
+## 自定义 Instrumentation
+
+如需接入 OpenTelemetry 原生 instrumentation，可通过 `useInstrumentation` 注册：
+
+```javascript
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+import { MyCustomInstrumentation } from './my-custom-instrumentation';
+
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+  instrumentations: [new MyCustomInstrumentation()],
+});
+
+await bkOT.start();
+```
+
+也可以通过 `useInstrumentation(instrumentation)` 在 `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=***'),
+  },
+});
+```