@blueking/open-telemetry 0.0.15 → 0.0.17

package/README.md

@@ -1,42 +1,68 @@
 # @blueking/open-telemetry
 
-蓝鲸 Web RUM SDK。采集 View、Fetch/XHR、静态资源、错误、Web Vitals、用户操作、白屏、Long Task、WebSocket、CSP、设备和 Session，并通过 OTLP HTTP 上报。
+面向浏览器真实用户监控（RUM）的 OpenTelemetry SDK。它把 Session、View、Fetch/XHR、静态资源、错误、Web Vitals、用户操作、白屏、Long Task、WebSocket、CSP 和设备信息统一为 Trace、Metric、Log，并通过 OTLP HTTP 上报。
 
-## 安装
+## 快速接入
 
 ```bash
 npm install @blueking/open-telemetry
 ```
 
-## 最小接入
-
-```javascript
+```ts
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
-const bkOT = new BkOpenTelemetry({
+export const bkOT = new BkOpenTelemetry({
   application: {
     name: 'order-center',
     environment: 'production',
     version: '1.2.0',
   },
   transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
+  },
+  session: {
+    sampleRate: 0.2,
+  },
+  tracking: {
+    view: {
+      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id'),
+    },
   },
 });
 ```
 
-`application.name` 和 `transport` 必填。使用根 `transport.endpoint` 时，SDK 自动生成：
+`application.name` 与 `transport` 必填。根 `transport.endpoint` 会生成三个上报地址：
+
+| 信号 | 默认地址 | 主要用途 |
+| --- | --- | --- |
+| Trace | `<endpoint>/v1/rum` | View、请求、资源、错误、性能、Action |
+| Metric | `<endpoint>/v1/metrics` | Web Vitals、View Loading、白屏、Long Task、WebSocket 聚合 |
+| Log | `<endpoint>/v1/logs` | Session 生命周期、View Snapshot、请求 Body、WebSocket 事件 |
+
+也可以为 `transport.signals.traces|metrics|logs.endpoint` 分别提供完整 URL，或把不需要的信号设为 `false`。至少要启用一种信号。
+
+## 默认能力
+
+只提供最小配置时，SDK 会自动启动并建立 Session 与 View。
 
-- traces：`/v1/rum`
-- metrics：`/v1/metrics`
-- logs：`/v1/logs`
+| 能力 | 默认 | 产出 |
+| --- | --- | --- |
+| Session / View | 开启且不可关闭 | `session.*` Log、`browser.view` Span/Log/Metric、运行时关联字段 |
+| Fetch / XHR | 开启 | `browser.resource` CLIENT Span，可选 `traceparent` 与 Body Log |
+| 静态资源 | 开启 | `browser.resource` Span、网络阶段属性 |
+| Error | 开启 | JS、Promise、资源加载错误 Span |
+| Web Vitals | 开启 | CLS/FCP/INP/LCP/TTFB Span 与 Metric |
+| Action | 开启 | 点击活动、耗时、关联计数和挫败信号 Span |
+| Blank Screen | 开启 | 白屏 Span 与 Counter |
+| Device | 开启 | 浏览器、OS、屏幕、网络运行时属性 |
+| Long Task / WebSocket / CSP | 关闭 | 按需通过 `tracking` 开启 |
 
-默认开启 Session、View、Fetch/XHR、静态资源、错误、Web Vitals、Action、白屏和设备采集。Long Task、WebSocket、CSP 默认关闭。
+完整的浏览器 API、默认值、配置入口和遥测产出见[能力矩阵](./wikis/capabilities.md)。
 
-## 推荐配置
+## 生产配置基线
 
-```javascript
+```ts
 const bkOT = new BkOpenTelemetry({
   application: {
     name: 'order-center',
@@ -44,205 +70,56 @@ const bkOT = new BkOpenTelemetry({
     version: '1.2.0',
   },
   transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
     signals: {
       traces: {
         processor: 'batch',
-        batch: {
-          maxQueueSize: 2048,
-          maxExportBatchSize: 512,
-        },
-      },
-      metrics: {
-        intervalMillis: 60_000,
+        batch: { maxQueueSize: 2048, maxExportBatchSize: 512 },
       },
+      metrics: { intervalMillis: 60_000 },
     },
   },
-  session: {
-    sampleRate: 0.2,
-  },
+  session: { sampleRate: 0.2 },
   tracking: {
     view: {
-      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/orders\/\d+/, '/orders/:id'),
-      excludedActivityUrls: [/\/events\/stream$/],
+      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id'),
+      excludedActivityUrls: [/\/events\/stream(?:\?|$)/],
     },
     request: {
-      allowedTracingUrls: ['https://api.example.com'],
+      allowedTracingUrls: [url => new URL(url).origin === 'https://api.example.com'],
       excludedUrls: [/\/health(?:\?|$)/],
     },
-    longTask: { threshold: 50 },
-    websocket: true,
+    blankScreen: { rootSelector: '#app' },
   },
   context: {
     user: { id: window.USER_ID },
     attributes: {
       page: () => ({ 'biz.module': 'order' }),
-      custom: () => ({ 'biz.team': 'checkout' }),
-    },
-  },
-  privacy: {
-    redactAttributes: attributes => attributes,
-  },
-});
-```
-
-## 入口字段
-
-| 字段 | 作用 |
-| --- | --- |
-| `application` | 应用名、环境和版本；`name` 必填 |
-| `transport` | OTLP endpoint、鉴权头及每类 signal 配置；根 `endpoint` 与单信号 endpoint 至少提供一种 |
-| `session` | Session storage key 和确定性 `sampleRate` |
-| `tracking` | 内置采集能力、View 分组、请求过滤和全局 `beforeSend` |
-| `context` | 用户及 page/metric/error/custom 公共属性 |
-| `privacy` | Consent、URL 和属性脱敏 |
-| `extensions` | 自定义插件与原生 OpenTelemetry instrumentation |
-
-旧入口 `app`、`sampling`、`route`、`view`、`plugins`、`instrumentations`、`attributes`、`spanBatch` 不再支持。
-
-## 三类信号独立开关
-
-`traces`、`metrics`、`logs` 默认全部开启。设为 `false` 会关闭对应导出链路；关闭的信号不会创建 exporter、processor 或 metric reader。
-
-```javascript
-new BkOpenTelemetry({
-  application: { name: 'trace-only-app' },
-  transport: {
-    signals: {
-      traces: { endpoint: 'https://trace.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
-    },
-  },
-});
-```
-
-根 `transport.endpoint` 可省略，但每个开启的信号必须配置独立 endpoint；三类信号不能全部关闭。关闭 Trace 后不会创建 Span，也不会注入 `traceparent`。
-
-## View 与 SPA
-
-自动模式会为初始加载、pathname/hash 路由、BFCache 和 Session 续期创建独立 View。query-only 和页内锚点变化不会创建新 View。
-
-```javascript
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'manual-view-app' },
-  transport: { endpoint: 'https://your-otlp-collector' },
-  tracking: {
-    view: { tracking: 'manual' },
-  },
-});
-
-bkOT.startView({ name: '订单详情', url: location.href });
-bkOT.setViewName('订单详情-只读');
-bkOT.setViewLoadingTime();
-```
-
-每个 View 有一个覆盖生命周期的 `browser.view` span，并产生 create/update/final Snapshot log。初始 View 记录 TTFB、DOM Interactive、DOMContentLoaded、DOM Complete、Load Event；SPA View 独立计算 CLS session window 和 INP p98。
-
-## Metric 如何关联 View
-
-Metric datapoint 只携带低基数 `view.url_path_group`，不携带唯一 `view.id`，避免时序基数随 PV 无限增长。
-
-精确关联放在 View Snapshot、span 和 log：这些事件会携带 `session.id + view.id`，用户操作期间还会携带 `action.id`。需要从单个指标下钻到具体 View 时，应在后端使用 exemplar，或从原始事件派生聚合指标。
-
-## 请求与资源
-
-Fetch/XHR 由一套请求生命周期统一采集，不会重复 patch 或重复计数。Trace Header 只对 `allowedTracingUrls` 命中的 URL 注入，包括同源请求。
-
-```javascript
-new BkOpenTelemetry({
-  application: { name: 'request-demo' },
-  transport: { endpoint: 'https://your-otlp-collector' },
-  tracking: {
-    request: {
-      allowedTracingUrls: ['https://api.example.com'],
-      excludedUrls: [/\/health(?:\?|$)/],
-      beforeSend: (event, context) => {
-        event.attributes['request.transport'] = context.type;
-        return event.resource.statusCode !== 404;
-      },
-      body: {
-        capture: 'errors',
-        maxSize: 10 * 1024,
-        redact: ({ body }) => body.replace(/("(?:password|token)"\s*:\s*)"[^"]*"/g, '$1"***"'),
-      },
+      metric: () => ({ 'biz.app': 'order-center' }),
     },
   },
-});
-```
-
-静态资源与请求共用一个 Resource PerformanceObserver。静态资源生成独立 span；Fetch/XHR timing 会匹配回对应请求 span。SDK 自身 OTLP 请求始终排除。
-
-## 隐私与 Consent
-
-默认 URL 脱敏会移除用户名、密码、query 和 hash。Action 默认只读取显式属性及可访问名称，不读取任意 DOM 文本；设备 ID 默认不持久化。
-
-```javascript
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'privacy-demo' },
-  transport: { endpoint: 'https://your-otlp-collector' },
   privacy: {
-    trackingConsent: 'not-granted',
-    redactUrl: url => new URL(url, location.href).origin,
-    redactAttributes: attributes => ({ ...attributes, token: undefined }),
-  },
-});
-
-await bkOT.setTrackingConsent('granted');
-await bkOT.setTrackingConsent('not-granted');
-```
-
-未授权时不创建 Session、不安装采集 patch。运行期可授权、撤回和再次授权。
-
-## 全局 beforeSend
-
-`tracking.beforeSend` 在 span/log 进入 exporter 前执行，可修改属性或返回 `false` 丢弃事件。
-
-```javascript
-new BkOpenTelemetry({
-  application: { name: 'filter-demo' },
-  transport: { endpoint: 'https://your-otlp-collector' },
-  tracking: {
-    beforeSend(event) {
-      delete event.attributes['debug.payload'];
-      return event.name !== 'custom.ignore-me';
+    redactAttributes(attributes) {
+      const next = { ...attributes };
+      delete next['biz.secret'];
+      return next;
     },
   },
 });
 ```
 
-请求专属 `tracking.request.beforeSend` 额外提供原始 Request/Response 或 XMLHttpRequest 上下文。
-
-## Session 与采样
+生产接入至少确认以下事项：
 
-`session.sampleRate` 范围为 `0 - 1`，默认 `1`。采样决定由 `application.name + session.id` 确定性计算，不写入额外 storage；同一 Session 内始终一致。
+1. `getPathGroup` 已把动态 ID 转成低基数路由模板。
+2. 跨域 Trace Header 白名单足够精确，服务端 CORS 已放行 `traceparent`。
+3. `user.id`、URL、错误和业务属性满足隐私要求；HTTP Body 默认保持关闭。
+4. SPA 的 `blankScreen.rootSelector` 指向真实挂载节点。
+5. 同一页面只运行一个实例，避免重复 patch Fetch/XHR/WebSocket。
 
-Session 固定为 15 分钟无活动过期、4 小时最长生命周期。storage key 默认按应用名和 endpoint 隔离。
+## 手动事件与 View
 
-## Action、设备和安全默认值
-
-```javascript
-new BkOpenTelemetry({
-  application: { name: 'interaction-demo' },
-  transport: { endpoint: 'https://your-otlp-collector' },
-  tracking: {
-    action: {
-      actionNameAttribute: 'data-bk-action-name',
-      nameCollection: 'explicit',
-    },
-    device: { persistentId: false },
-    blankScreen: { rootSelector: '#app' },
-    cspViolation: true,
-  },
-});
-```
-
-只有明确接受 DOM 文本采集风险时，才设置 `action.nameCollection: 'text'`。只有需要跨 Session 设备关联时，才设置 `device.persistentId: true`。
-
-## 手动事件
-
-```javascript
+```ts
 bkOT.setUser({ id: 'user-001' });
 
 bkOT.reportAction({
@@ -256,71 +133,33 @@ bkOT.reportCustomEvent({
 });
 ```
 
-## 扩展
-
-```javascript
-import { BkOpenTelemetry, createPlugin } from '@blueking/open-telemetry';
-
-const plugin = createPlugin({
-  name: 'demo-plugin',
-  init(context) {
-    const span = context.startSpan('demo.plugin_ready');
-    span.end();
-  },
-});
+手动 View 最稳妥的接入方式是在 SDK 启动并建立 Session 后创建：
 
+```ts
 const bkOT = new BkOpenTelemetry({
-  application: { name: 'extension-demo' },
+  application: { name: 'manual-view-app' },
   autoStart: false,
-  transport: { endpoint: 'https://your-otlp-collector' },
-  extensions: {
-    plugins: [plugin],
-    instrumentations: [],
-  },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: { view: { tracking: 'manual' } },
 });
 
 await bkOT.start();
-await bkOT.flush();
-await bkOT.shutdown();
+bkOT.startView({ name: '订单详情', url: location.href });
 ```
 
-也可在 `start()` 前调用 `use(plugin)` 或 `useInstrumentation(instrumentation)`。退出上报使用 OpenTelemetry 浏览器 exporter 的 `fetch keepalive`，并在 pagehide/hidden 时 flush。
+`reportAction()`、`reportCustomEvent()` 和 View 控制方法均受 Session 采样/有效状态约束。调试时先使用 `session.sampleRate: 1`。
 
-## 完整配置骨架
+## 文档导航
 
-```javascript
-new BkOpenTelemetry({
-  application: { name: 'demo-app', environment: 'production', version: '1.0.0' },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'token',
-    headers: {},
-    signals: {
-      traces: { endpoint: 'https://trace.example.com/v1/rum', processor: 'batch', batch: {}, timeoutMillis: 10_000 },
-      metrics: { endpoint: 'https://metric.example.com/v1/metrics', intervalMillis: 60_000 }, // 或 false
-      logs: { endpoint: 'https://log.example.com/v1/logs' }, // 或 false
-    },
-  },
-  session: { sampleRate: 1, storageKey: 'optional-session-key' },
-  tracking: {
-    view: { tracking: 'auto', loadingTime: true, getPathGroup: url => new URL(url, location.href).pathname },
-    request: {},
-    resource: true,
-    error: true,
-    webVitals: true,
-    blankScreen: true,
-    device: true,
-    action: true,
-    longTask: false,
-    cspViolation: false,
-    websocket: false,
-    beforeSend: event => true,
-  },
-  context: { user: { id: 'user-001' }, attributes: {} },
-  privacy: { trackingConsent: 'granted' },
-  extensions: { plugins: [], instrumentations: [] },
-  autoStart: true,
-  enabled: true,
-  debug: false,
-});
-```
+| 目标 | 文档 |
+| --- | --- |
+| 首次接入 | [快速上手](./wikis/getting-started.md) |
+| 判断能采什么、默认是否开启、产出哪类信号 | [能力矩阵](./wikis/capabilities.md) |
+| 理解初始化、插件顺序、上下文、过滤和上报数据流 | [架构与数据流](./wikis/architecture.md) |
+| 查完整配置、默认值和约束 | [配置参考](./wikis/configuration.md) |
+| 查公开方法与导出符号 | [API 参考](./wikis/api.md) |
+| 查精确 Span / Metric / Log 名和字段 | [遥测参考](./wikis/telemetry-reference.md) |
+| 隐私、Consent 和低基数字段 | [隐私与公共属性](./wikis/privacy-attributes.md) |
+| 没有数据或数据异常 | [调试与排障](./wikis/troubleshooting.md) |
+
+完整 Wiki 入口见 [`wikis/`](./wikis/README.md)。文档以当前 `src/` 和 `src/index.ts` 公开导出为事实来源，不承诺历史配置兼容。