@blueking/open-telemetry 0.0.13 → 0.0.15

package/README.md

@@ -1,120 +1,44 @@
 # @blueking/open-telemetry
 
-`@blueking/open-telemetry` 是蓝鲸 RUM Web 上报 SDK。它基于 OpenTelemetry 采集页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话等数据，并通过 OTLP HTTP 上报到 collector。
+蓝鲸 Web RUM SDK。采集 View、Fetch/XHR、静态资源、错误、Web Vitals、用户操作、白屏、Long Task、WebSocket、CSP、设备和 Session，并通过 OTLP HTTP 上报。
 
-## 1. 安装和使用
-
-### npm 使用
+## 安装
 
 ```bash
 npm install @blueking/open-telemetry
 ```
 
+## 最小接入
+
 ```javascript
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  app: {
-    name: 'demo-app',
+  application: {
+    name: 'order-center',
     environment: 'production',
-    version: '1.0.0',
+    version: '1.2.0',
   },
   transport: {
     endpoint: 'https://your-otlp-collector',
     token: 'your-report-token',
   },
-  user: {
-    id: window.USER_ID,
-  },
 });
 ```
 
-### CDN 使用
-
-```html
-<script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
-<script>
-  window.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>
-```
-
-`new BkOpenTelemetry()` 后默认自动启动，不需要再手动调用 `start()`。
-
-`transport.endpoint` 填上报根地址（通常包含 `/v1` 路径前缀），SDK 会自动拼出三类上报地址：
-
-- traces: `endpoint/rum`
-- metrics: `endpoint/metrics`
-- logs: `endpoint/logs`
-
-示例：`endpoint: 'http://9.134.239.232:4318/v1'` 时，traces 上报到 `http://9.134.239.232:4318/v1/rum`。
-
-`transport.token` 会作为默认鉴权头发送：`Authorization: Bearer <token>`。
+`application.name` 和 `transport` 必填。使用根 `transport.endpoint` 时，SDK 自动生成：
 
-## 2. 默认采集
-
-只配置 `app` 和 `transport` 后，SDK 已经默认开启常用能力：
-
-- `documentLoad`: 页面加载链路。
-- `pageView`: 页面访问和 SPA 路由切换。
-- `fetch`: 自动采集 fetch 接口请求。
-- `xhr`: 自动采集 XMLHttpRequest 接口请求。
-- `resource`: 静态资源加载耗时。
-- `error`: JS 错误、Promise 异常、资源加载失败。
-- `webVitals`: CLS、FCP、INP、LCP、TTFB。
-- `blankScreen`: 首屏白屏检测。
-- `device`: 设备、浏览器、屏幕、网络信息。
-- `session`: 连续访问会话。
-- `userInteraction`: OpenTelemetry 官方用户交互 instrumentation。
-
-默认关闭的能力需要手动打开：
-
-- `action`: 轻量用户操作事件，支持点击、输入、提交等。
-- `httpBody`: 接口异常时采集请求和响应 body。
-- `longTask`: 主线程 Long Task。
-- `routeTiming`: SPA 路由切换耗时。
-- `cspViolation`: CSP 违规事件。
-- `websocket`: WebSocket 连接、消息、错误指标。
-
-如果要关闭默认能力，显式配置为 `false`：
-
-```javascript
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-  instrumentations: {
-    fetch: false,
-    xhr: false,
-    userInteraction: false,
-  },
-  plugins: {
-    webVitals: false,
-    blankScreen: false,
-    session: false,
-  },
-});
-```
+- traces：`/v1/rum`
+- metrics：`/v1/metrics`
+- logs：`/v1/logs`
 
-## 3. 给数据加上应用、用户和路由
+默认开启 Session、View、Fetch/XHR、静态资源、错误、Web Vitals、Action、白屏和设备采集。Long Task、WebSocket、CSP 默认关闭。
 
-建议先补齐应用标识、用户 ID 和路由归类。这样后续排查问题时，可以按应用、版本、用户、页面聚合。
+## 推荐配置
 
 ```javascript
 const bkOT = new BkOpenTelemetry({
-  app: {
+  application: {
     name: 'order-center',
     environment: 'production',
     version: '1.2.0',
@@ -122,417 +46,217 @@ const bkOT = new BkOpenTelemetry({
   transport: {
     endpoint: 'https://your-otlp-collector',
     token: 'your-report-token',
-  },
-  user: {
-    id: window.USER_ID,
-  },
-  route: {
-    getPathGroup: url => {
-      const { pathname } = new URL(url, location.href);
-      return pathname.replace(/\/user\/\d+/, '/user/:id');
+    signals: {
+      traces: {
+        processor: 'batch',
+        batch: {
+          maxQueueSize: 2048,
+          maxExportBatchSize: 512,
+        },
+      },
+      metrics: {
+        intervalMillis: 60_000,
+      },
     },
   },
-});
-```
-
-常用基础配置：
-
-- `app.name`: 应用名，会写入 `service.name`，默认 `unknown_service`。
-- `app.environment`: 环境名，会写入 `deployment.environment.name`，默认 `production`。
-- `app.version`: 应用版本，会写入 `service.version`。
-- `user.id`: 用户 ID，会写入 `user.id`。SDK 原样透传，不做 hash 和脱敏。
-- `route.getPathGroup`: 把高基数 URL 归类成低基数路由，例如 `/user/123` 归类成 `/user/:id`。
-
-运行中也可以更新用户和当前 View：
-
-```javascript
-bkOT.setUser({ id: 'user-001' });
-
-bkOT.setView({
-  id: 'view-001',
-  url: location.href,
-  urlPathGroup: '/order/:id',
-  loadingType: 'route_change',
-});
-```
-
-`setUser` 和 `setView` 会更新运行期公共属性，后续 span、metric、log 都会自动带上这些字段。
-
-## 4. 按需打开接口、资源和路由能力
-
-多数 Web 应用可以从这一组配置开始：
-
-```javascript
-new BkOpenTelemetry({
-  app: {
-    name: 'demo-app',
-    version: '1.0.0',
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
-  },
-  route: {
-    getPathGroup: url => new URL(url, location.href).pathname,
-  },
-  plugins: {
-    routeTiming: true,
-    longTask: { threshold: 80 },
+  session: {
+    sampleRate: 0.2,
   },
-});
-```
-
-- `fetch` / `xhr`: 默认开启，采集接口耗时、状态码、请求方法、URL 归类等。
-- `resource`: 默认开启，采集 img、script、css 等静态资源耗时、大小、缓存命中和协议。
-- `pageView`: 默认开启，监听 `pushState`、`replaceState`、`popstate`、`hashchange`。
-- `routeTiming`: 默认关闭，估算 SPA 路由切换到下一帧渲染完成的耗时。
-- `longTask`: 默认关闭，采集主线程长任务。`threshold` 默认 `50` ms。
-
-SDK 会自动忽略指向自身 OTLP 上报地址的请求，避免上报请求被再次采集导致循环放大。
-
-## 5. 配置错误、白屏和 CSP
-
-```javascript
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-  plugins: {
-    error: {
-      windowMs: 60 * 1000,
-      maxPerWindow: 5,
+  tracking: {
+    view: {
+      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/orders\/\d+/, '/orders/:id'),
+      excludedActivityUrls: [/\/events\/stream$/],
     },
-    blankScreen: {
-      rootSelector: '#app',
-      checkDelay: 3000,
-      threshold: 0.8,
-      ignoreSelectors: ['.app-loading', '.page-skeleton'],
+    request: {
+      allowedTracingUrls: ['https://api.example.com'],
+      excludedUrls: [/\/health(?:\?|$)/],
     },
-    cspViolation: true,
-  },
-});
-```
-
-错误采集说明：
-
-- `error`: 默认开启，采集 `window.error`、`unhandledrejection`、资源加载失败。
-- `error.windowMs`: 同类错误节流窗口，默认 `60000` ms。
-- `error.maxPerWindow`: 同类错误在窗口内最多上报条数，默认 `5`。
-- `cspViolation`: 默认关闭，监听 `securitypolicyviolation` 事件。适合有 CSP 策略的站点开启。
-
-白屏检测说明：
-
-- `blankScreen`: 默认开启，只在判定为白屏时上报。
-- `blankScreen.rootSelector`: 应用挂载点。Vue / React 项目建议配置为 `#app` 或 `#root`。
-- `blankScreen.checkDelay`: DOM ready 后延迟多久检测，默认 `3000` ms。
-- `blankScreen.threshold`: 空白采样点比例阈值，范围 `0 - 1`，默认 `0.8`。
-- `blankScreen.ignoreSelectors`: 追加 loading、骨架屏等忽略选择器，命中后不计入空白比例。
-
-## 6. 配置用户操作和 WebSocket
-
-```javascript
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://your-otlp-collector',
+    longTask: { threshold: 50 },
+    websocket: true,
   },
-  plugins: {
-    action: {
-      eventNames: ['click', 'submit', 'keydown'],
+  context: {
+    user: { id: window.USER_ID },
+    attributes: {
+      page: () => ({ 'biz.module': 'order' }),
+      custom: () => ({ 'biz.team': 'checkout' }),
     },
-    websocket: true,
+  },
+  privacy: {
+    redactAttributes: attributes => attributes,
   },
 });
 ```
 
-`action` 用于上报轻量用户操作：
-
-- `action: true`: 采集 `click`、`submit`、`keydown`。
-- `action.eventNames`: 自定义采集事件，支持 `click`、`input`、`keydown`、`pointerdown`、`scroll`、`submit`。
-- 上报时会截取元素文本、标签名，并写入 `action.type`、`target.text_short`、`target.tag`。
+## 入口字段
 
-`websocket` 用于采集 WebSocket：
+| 字段 | 作用 |
+| --- | --- |
+| `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 |
 
-- 连接成功耗时：`browser.websocket.connect.duration`。
-- 收发消息数：`browser.websocket.message.count`。
-- 收发字节数：`browser.websocket.message.bytes`。
-- 错误数：`browser.websocket.error.count`。
+旧入口 `app`、`sampling`、`route`、`view`、`plugins`、`instrumentations`、`attributes`、`spanBatch` 不再支持。
 
-SDK 会忽略指向自身上报地址的 WebSocket URL。
+## 三类信号独立开关
 
-## 7. 采集异常接口 body
-
-`httpBody` 默认关闭。它会 patch `fetch` 和 `XMLHttpRequest`，只在请求失败、请求抛错或状态码 `>= 400` 时上报 body。
+`traces`、`metrics`、`logs` 默认全部开启。设为 `false` 会关闭对应导出链路；关闭的信号不会创建 exporter、processor 或 metric reader。
 
 ```javascript
 new BkOpenTelemetry({
+  application: { name: 'trace-only-app' },
   transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-  plugins: {
-    httpBody: {
-      maxBodySize: 4 * 1024,
-      redact: ({ body, type, url, status, truncated }) => {
-        return body.replace(/password=[^&]+/g, 'password=***').replace(/token=[^&]+/g, 'token=***');
-      },
+    signals: {
+      traces: { endpoint: 'https://trace.example.com/v1/rum' },
+      metrics: false,
+      logs: false,
     },
   },
 });
 ```
 
-配置项：
-
-- `httpBody: true`: 使用默认配置开启。
-- `httpBody.maxBodySize`: 单个请求或响应 body 最大采集长度，默认 `10 * 1024` 字符。
-- `httpBody.redact`: body 上报前的脱敏函数，必须返回字符串。
+根 `transport.endpoint` 可省略，但每个开启的信号必须配置独立 endpoint；三类信号不能全部关闭。关闭 Trace 后不会创建 Span，也不会注入 `traceparent`。
 
-`redact` 入参：
+## View 与 SPA
 
-- `body`: 已截断后的 body 字符串。
-- `type`: `request` 或 `response`。
-- `url`: 请求 URL。
-- `method`: 请求方法。
-- `status`: 响应状态码，网络错误时可能为空。
-- `contentType`: body 的 content-type。
-- `truncated`: 是否被 `maxBodySize` 截断。
-
-建议只在排障需要时开启 `httpBody`，并务必处理密码、token、手机号等敏感信息。
-
-## 8. 加公共属性和脱敏
-
-公共属性适合放业务线、模块、页面类型等每条数据都想带上的信息。
+自动模式会为初始加载、pathname/hash 路由、BFCache 和 Session 续期创建独立 View。query-only 和页内锚点变化不会创建新 View。
 
 ```javascript
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-  attributes: {
-    page: () => ({
-      'biz.module': 'order',
-      'rum.page.host': location.host,
-      'rum.page.path': location.pathname,
-    }),
-    metric: () => ({
-      'biz.metric_source': 'rum',
-    }),
-    error: () => ({
-      'biz.error_source': 'browser',
-    }),
-    custom: () => ({
-      'biz.team': 'demo',
-    }),
-  },
-  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 next;
-    },
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'manual-view-app' },
+  transport: { endpoint: 'https://your-otlp-collector' },
+  tracking: {
+    view: { tracking: 'manual' },
   },
 });
-```
 
-`attributes` 配置项：
+bkOT.startView({ name: '订单详情', url: location.href });
+bkOT.setViewName('订单详情-只读');
+bkOT.setViewLoadingTime();
+```
 
-- `attributes.page`: 页面、接口、资源、错误等 RUM 数据都会带上。
-- `attributes.metric`: Web Vitals、Long Task、Route Timing、WebSocket 等 metric 会带上。
-- `attributes.error`: JS 错误、白屏、CSP 等错误类数据会带上。
-- `attributes.custom`: `reportCustomEvent` 上报的自定义事件会带上。
+每个 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。
 
-`privacy` 配置项：
+## Metric 如何关联 View
 
-- `privacy.redactUrl`: 处理 URL，例如 `url.full`、`document.referrer`、资源 URL。
-- `privacy.redactAttributes`: 处理 span 和 log 属性。适合兜底清理敏感字段。
-- `plugins.httpBody.redact`: 只处理请求和响应 body。
+Metric datapoint 只携带低基数 `view.url_path_group`，不携带唯一 `view.id`，避免时序基数随 PV 无限增长。
 
-脱敏顺序可以简单理解为：URL 先走 `redactUrl`，属性整体再走 `redactAttributes`。
+精确关联放在 View Snapshot、span 和 log：这些事件会携带 `session.id + view.id`，用户操作期间还会携带 `action.id`。需要从单个指标下钻到具体 View 时，应在后端使用 exemplar，或从原始事件派生聚合指标。
 
-## 9. 配置设备和会话
+## 请求与资源
 
-`device` 和 `session` 默认开启，一般不需要配置。多应用共用同一域名时，可以自定义 storage key。
+Fetch/XHR 由一套请求生命周期统一采集，不会重复 patch 或重复计数。Trace Header 只对 `allowedTracingUrls` 命中的 URL 注入，包括同源请求。
 
 ```javascript
 new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-  plugins: {
-    device: {
-      storageKey: 'DEMO_DEVICE_ID',
-    },
-    session: {
-      storageKey: 'DEMO_SESSION',
-      inactivityMs: 30 * 60 * 1000,
-      maxLifetimeMs: 24 * 60 * 60 * 1000,
+  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"***"'),
+      },
     },
   },
 });
 ```
 
-`device` 配置项：
-
-- `device: true`: 使用默认设备配置。
-- `device.storageKey`: 设备 ID 的 localStorage key，默认 `BK_RUM_DEVICE_ID`。
-- 设备 ID 跨会话持久，会写入 `device.id`。
-
-`session` 配置项：
+静态资源与请求共用一个 Resource PerformanceObserver。静态资源生成独立 span；Fetch/XHR timing 会匹配回对应请求 span。SDK 自身 OTLP 请求始终排除。
 
-- `session: true`: 使用默认会话配置。
-- `session.storageKey`: 会话 storage key。默认会按上报 endpoint host 自动生成隔离后缀。
-- `session.inactivityMs`: 用户不活跃多久后创建新会话，默认 `30` 分钟。
-- `session.maxLifetimeMs`: 会话最长持续时间，默认 `24` 小时。
+## 隐私与 Consent
 
-会话会写入 `session.id`，并在首次创建或轮换时上报 `session.start` / `session.rotate` log。
-
-## 10. 手动上报业务事件
-
-### 自定义事件
+默认 URL 脱敏会移除用户名、密码、query 和 hash。Action 默认只读取显式属性及可访问名称，不读取任意 DOM 文本；设备 ID 默认不持久化。
 
 ```javascript
-bkOT.reportCustomEvent({
-  name: 'order.checkout',
-  attributes: {
-    'biz.order_id': 'O20260527001',
-    'biz.order_amount': 199,
-  },
-});
-```
-
-### 自定义失败事件
-
-```javascript
-bkOT.reportCustomEvent({
-  name: 'order.checkout',
-  attributes: {
-    'biz.order_id': 'O20260527001',
+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 }),
   },
-  error: new Error('库存不足'),
 });
-```
 
-### 手动上报用户操作
-
-```javascript
-bkOT.reportAction({
-  type: 'click',
-  targetText: '立即购买',
-  targetTag: 'button',
-  attributes: {
-    'biz.order_id': 'O20260527001',
-  },
-});
+await bkOT.setTrackingConsent('granted');
+await bkOT.setTrackingConsent('not-granted');
 ```
 
-说明：
+未授权时不创建 Session、不安装采集 patch。运行期可授权、撤回和再次授权。
 
-- `reportCustomEvent.name`: 事件名，会生成 `custom.${name}` span。
-- `reportCustomEvent.attributes`: 业务属性，会和 `attributes.custom` 合并。
-- `reportCustomEvent.error`: 传入后事件结果会标记为 error，并记录 exception。
-- `reportAction.type`: 操作类型，会生成 `action.${type}` span。
-- 未命中采样时，手动上报事件会被静默丢弃；`debug: true` 时会打印提示。
+## 全局 beforeSend
 
-## 11. 控制采样、调试和上报
+`tracking.beforeSend` 在 span/log 进入 exporter 前执行，可修改属性或返回 `false` 丢弃事件。
 
 ```javascript
 new BkOpenTelemetry({
-  debug: true,
-  enabled: true,
-  sampling: {
-    rate: 0.2,
-  },
-  spanProcessor: 'batch',
-  spanBatch: {
-    maxQueueSize: 2048,
-    maxExportBatchSize: 512,
-    scheduledDelayMillis: 5000,
-    exportTimeoutMillis: 30000,
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
-    headers: {
-      'X-Biz-ID': 'demo',
-    },
-    signals: {
-      traces: {
-        timeoutMillis: 10000,
-      },
-      metrics: {
-        concurrencyLimit: 2,
-      },
+  application: { name: 'filter-demo' },
+  transport: { endpoint: 'https://your-otlp-collector' },
+  tracking: {
+    beforeSend(event) {
+      delete event.attributes['debug.payload'];
+      return event.name !== 'custom.ignore-me';
     },
   },
 });
 ```
 
-常用控制项：
+请求专属 `tracking.request.beforeSend` 额外提供原始 Request/Response 或 XMLHttpRequest 上下文。
 
-- `enabled`: 是否启用 SDK，默认 `true`。设为 `false` 后不会启动采集和上报。
-- `debug`: 是否在控制台输出 exporter 数据和插件异常，默认 `false`。
-- `sampling.rate`: 采样率，范围 `0 - 1`，默认 `1`。
-- `spanProcessor`: trace processor 模式，默认 `batch`。本地调试可用 `simple`。
-- `spanBatch`: `batch` 模式的批量上报配置。
-- `transport.endpoint`: 上报根地址（通常包含 `/v1` 路径前缀），默认 `http://localhost:4318`。SDK 会追加 `/rum`、`/metrics`、`/logs`。
-- `transport.token`: 默认鉴权 token。
-- `transport.headers`: 所有信号共用请求头。
-- `transport.signals.traces/metrics/logs`: 分别配置某一类信号。
+## Session 与采样
 
-采样结果会在一次浏览器会话中保持稳定。`rate < 1` 时，SDK 会把采样结果写入 `sessionStorage`；不可用时降级到内存缓存。
+`session.sampleRate` 范围为 `0 - 1`，默认 `1`。采样决定由 `application.name + session.id` 确定性计算，不写入额外 storage；同一 Session 内始终一致。
 
-如果三类信号要发到不同地址：
+Session 固定为 15 分钟无活动过期、4 小时最长生命周期。storage key 默认按应用名和 endpoint 隔离。
+
+## Action、设备和安全默认值
 
 ```javascript
 new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
-    signals: {
-      endpoints: {
-        traces: 'https://trace.example.com/v1/rum',
-        metrics: 'https://metric.example.com/v1/metrics',
-        logs: 'https://log.example.com/v1/logs',
-      },
+  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,
   },
 });
 ```
 
-请求头优先级为：`transport.token` 默认头 < `transport.headers` < 单信号 `headers`。
+只有明确接受 DOM 文本采集风险时，才设置 `action.nameCollection: 'text'`。只有需要跨 Session 设备关联时，才设置 `device.persistentId: true`。
 
-## 12. 控制启动和生命周期
-
-默认 `autoStart: true`。如果要先注册自定义插件或 instrumentation，再启动 SDK，可以关闭自动启动。
+## 手动事件
 
 ```javascript
-const bkOT = new BkOpenTelemetry({
-  autoStart: false,
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-});
-
-await bkOT.start();
-```
+bkOT.setUser({ id: 'user-001' });
 
-生命周期方法：
+bkOT.reportAction({
+  name: '立即购买',
+  attributes: { 'biz.order_id': 'O20260716001' },
+});
 
-```javascript
-await bkOT.flush();
-await bkOT.shutdown();
+bkOT.reportCustomEvent({
+  name: 'order.checkout',
+  attributes: { 'biz.order_amount': 199 },
+});
 ```
 
-- `start`: 启动 provider、instrumentation 和插件。重复调用会直接返回。
-- `flush`: 立即刷新插件、trace、metric、log。
-- `shutdown`: 先刷新，再卸载插件、事件监听和 instrumentation。关闭后不能再次启动同一个实例。
-
-## 13. 扩展插件
-
-普通接入方通常不需要扩展插件。只有默认采集不满足时，再使用插件能力。
+## 扩展
 
 ```javascript
 import { BkOpenTelemetry, createPlugin } from '@blueking/open-telemetry';
@@ -540,171 +264,63 @@ 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', {
-      'biz.plugin': 'demo',
-    });
+    const span = context.startSpan('demo.plugin_ready');
     span.end();
   },
 });
 
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'extension-demo' },
   autoStart: false,
-  plugins: {
-    custom: [plugin],
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-});
-
-await bkOT.start();
-```
-
-也可以在 `start()` 前链式注册：
-
-```javascript
-bkOT.use(plugin);
-```
-
-插件上下文常用方法：
-
-- `context.startSpan`: 创建 span。
-- `context.emitLog`: 上报 log，并自动带上运行期公共属性和脱敏。
-- `context.meter`: 创建 metric。
-- `context.setRuntimeAttributes`: 更新后续数据都会携带的公共属性。
-- `context.getRuntimeAttributes`: 获取当前公共属性快照。
-- `context.setUser`: 更新用户上下文。
-- `context.setView`: 更新 View 上下文。
-
-## 14. 接入原生 OpenTelemetry Instrumentation
-
-```javascript
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-import { MyCustomInstrumentation } from './my-custom-instrumentation';
-
-const bkOT = new BkOpenTelemetry({
-  autoStart: false,
-  instrumentations: {
-    custom: [new MyCustomInstrumentation()],
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
+  transport: { endpoint: 'https://your-otlp-collector' },
+  extensions: {
+    plugins: [plugin],
+    instrumentations: [],
   },
 });
 
 await bkOT.start();
+await bkOT.flush();
+await bkOT.shutdown();
 ```
 
-也可以在 `start()` 前链式注册：
-
-```javascript
-bkOT.useInstrumentation(new MyCustomInstrumentation());
-```
-
-注意：`use` 和 `useInstrumentation` 必须在 `start()` 前调用。如果使用默认自动启动，请改成 `autoStart: false`。
+也可在 `start()` 前调用 `use(plugin)` 或 `useInstrumentation(instrumentation)`。退出上报使用 OpenTelemetry 浏览器 exporter 的 `fetch keepalive`，并在 pagehide/hidden 时 flush。
 
-## 15. 完整配置速查
+## 完整配置骨架
 
 ```javascript
 new BkOpenTelemetry({
-  app: {
-    name: 'demo-app',
-    environment: 'production',
-    version: '1.0.0',
-  },
-  user: {
-    id: 'user-001',
-  },
+  application: { name: 'demo-app', environment: 'production', version: '1.0.0' },
   transport: {
     endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
+    token: 'token',
     headers: {},
     signals: {
-      endpoints: {
-        traces: 'https://your-otlp-collector/v1/rum',
-        metrics: 'https://your-otlp-collector/v1/metrics',
-        logs: 'https://your-otlp-collector/v1/logs',
-      },
-      traces: {
-        headers: {},
-        timeoutMillis: 10000,
-        concurrencyLimit: 2,
-      },
-      metrics: {},
-      logs: {},
+      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
     },
   },
-  enabled: true,
-  autoStart: true,
-  debug: false,
-  sampling: {
-    rate: 1,
-  },
-  spanProcessor: 'batch',
-  spanBatch: {
-    maxQueueSize: 2048,
-    maxExportBatchSize: 512,
-    scheduledDelayMillis: 5000,
-    exportTimeoutMillis: 30000,
-  },
-  route: {
-    getPathGroup: url => new URL(url, location.href).pathname,
-  },
-  attributes: {
-    page: () => ({}),
-    metric: () => ({}),
-    error: () => ({}),
-    custom: () => ({}),
-  },
-  privacy: {
-    redactUrl: url => url,
-    redactAttributes: attributes => attributes,
-  },
-  instrumentations: {
-    documentLoad: true,
-    fetch: true,
-    xhr: true,
-    userInteraction: true,
-  },
-  plugins: {
-    pageView: true,
+  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,
-    session: true,
-    action: false,
-    httpBody: false,
+    action: true,
     longTask: false,
-    routeTiming: 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,
 });
 ```
-
-配置默认值：
-
-- `autoStart`: 默认 `true`。
-- `enabled`: 默认 `true`。
-- `debug`: 默认 `false`。
-- `sampling.rate`: 默认 `1`。
-- `spanProcessor`: 默认 `batch`。
-- `transport.endpoint`: 默认 `http://localhost:4318`。
-- `app.environment`: 默认 `production`。
-- `app.name`: 默认 `unknown_service`。
-
-## 16. 推荐接入顺序
-
-新项目建议按下面顺序接入：
-
-1. 先配置 `app`、`transport`、`user`，确认页面访问、错误、接口请求能上报。
-2. 再配置 `route.getPathGroup`，避免 URL 动态 ID 导致维度过高。
-3. 按业务需要开启 `routeTiming`、`longTask`、`action`、`websocket`。
-4. 排障时再开启 `httpBody`，并先做好脱敏。
-5. 最后补充 `attributes` 和 `privacy`，统一业务维度和敏感信息处理。