@blueking/open-telemetry 0.0.14 → 0.0.16

package/README.md

@@ -1,710 +1,165 @@
 # @blueking/open-telemetry
 
-`@blueking/open-telemetry` 是蓝鲸 RUM Web 上报 SDK。它基于 OpenTelemetry 采集页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话等数据，并通过 OTLP HTTP 上报到 collector。
+面向浏览器真实用户监控（RUM）的 OpenTelemetry SDK。它把 Session、View、Fetch/XHR、静态资源、错误、Web Vitals、用户操作、白屏、Long Task、WebSocket、CSP 和设备信息统一为 Trace、Metric、Log，并通过 OTLP HTTP 上报。
 
-## 1. 安装和使用
-
-### npm 使用
+## 快速接入
 
 ```bash
 npm install @blueking/open-telemetry
 ```
 
-```javascript
+```ts
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
-const bkOT = new BkOpenTelemetry({
-  app: {
-    name: 'demo-app',
+export const bkOT = new BkOpenTelemetry({
+  application: {
+    name: 'order-center',
     environment: 'production',
-    version: '1.0.0',
+    version: '1.2.0',
   },
   transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
   },
-  user: {
-    id: window.USER_ID,
+  session: {
+    sampleRate: 0.2,
   },
-});
-```
-
-### 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',
+  tracking: {
+    view: {
+      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id'),
     },
-    user: {
-      id: window.USER_ID,
-    },
-  });
-</script>
+  },
+});
 ```
 
-`new BkOpenTelemetry()` 后默认自动启动，不需要再手动调用 `start()`。
-
-`transport.endpoint` 填上报根地址（不含路径前缀），SDK 会自动拼出三类上报地址：
-
-- traces: `endpoint/v1/rum`
-- metrics: `endpoint/v1/metrics`
-- logs: `endpoint/v1/logs`
+`application.name` 与 `transport` 必填。根 `transport.endpoint` 会生成三个上报地址：
 
-示例：`endpoint: 'http://9.134.239.232:4318'` 时，traces 上报到 `http://9.134.239.232:4318/v1/rum`。若通过 `transport.signals.endpoints` 或单信号 `endpoint` 自定义了某一类地址，则该信号使用自定义 URL，不再拼接。
+| 信号 | 默认地址 | 主要用途 |
+| --- | --- | --- |
+| 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.token` 会作为默认鉴权头发送：`Authorization: Bearer <token>`。
+也可以为 `transport.signals.traces|metrics|logs.endpoint` 分别提供完整 URL，或把不需要的信号设为 `false`。至少要启用一种信号。
 
-## 2. 默认采集
+## 默认能力
 
-只配置 `app` 和 `transport` 后，SDK 已经默认开启常用能力：
+只提供最小配置时，SDK 会自动启动并建立 Session 与 View。
 
-- `documentLoad`: 页面加载链路。
-- `pageView`: 页面访问和 SPA 路由切换。
-- `fetch`: 自动采集 fetch 接口请求。
-- `xhr`: 自动采集 XMLHttpRequest 接口请求。
-- `resource`: 静态资源加载耗时。
-- `error`: JS 错误、Promise 异常、资源加载失败。
-- `webVitals`: CLS、FCP、INP、LCP、TTFB。
-- `blankScreen`: 首屏白屏检测。
-- `device`: 设备、浏览器、屏幕、网络信息。
-- `session`: 连续访问会话。
-- `userInteraction`: OpenTelemetry 官方用户交互 instrumentation。
+| 能力 | 默认 | 产出 |
+| --- | --- | --- |
+| 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` 开启 |
 
-默认关闭的能力需要手动打开：
+完整的浏览器 API、默认值、配置入口和遥测产出见[能力矩阵](./wikis/capabilities.md)。
 
-- `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,
-  },
-});
-```
-
-## 3. 给数据加上应用、用户和路由
-
-建议先补齐应用标识、用户 ID 和路由归类。这样后续排查问题时，可以按应用、版本、用户、页面聚合。
-
-```javascript
+```ts
 const bkOT = new BkOpenTelemetry({
-  app: {
+  application: {
     name: 'order-center',
     environment: 'production',
     version: '1.2.0',
   },
   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');
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
+    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 },
-  },
-});
-```
-
-- `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,
+  session: { sampleRate: 0.2 },
+  tracking: {
+    view: {
+      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id'),
+      excludedActivityUrls: [/\/events\/stream(?:\?|$)/],
     },
-    blankScreen: {
-      rootSelector: '#app',
-      checkDelay: 3000,
-      threshold: 0.8,
-      ignoreSelectors: ['.app-loading', '.page-skeleton'],
+    request: {
+      allowedTracingUrls: [url => new URL(url).origin === 'https://api.example.com'],
+      excludedUrls: [/\/health(?:\?|$)/],
     },
-    cspViolation: true,
+    blankScreen: { rootSelector: '#app' },
   },
-});
-```
-
-错误采集说明：
-
-- `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',
-  },
-  plugins: {
-    action: {
-      eventNames: ['click', 'submit', 'keydown'],
-    },
-    websocket: true,
-  },
-});
-```
-
-`action` 用于上报轻量用户操作：
-
-- `action: true`: 采集 `click`、`submit`、`keydown`。
-- `action.eventNames`: 自定义采集事件，支持 `click`、`input`、`keydown`、`pointerdown`、`scroll`、`submit`。
-- 上报时会截取元素文本、标签名，并写入 `action.type`、`target.text_short`、`target.tag`。
-
-`websocket` 用于采集 WebSocket：
-
-- 连接成功耗时：`browser.websocket.connect.duration`。
-- 收发消息数：`browser.websocket.message.count`。
-- 收发字节数：`browser.websocket.message.bytes`。
-- 错误数：`browser.websocket.error.count`。
-
-SDK 会忽略指向自身上报地址的 WebSocket URL。
-
-## 7. 采集异常接口 body
-
-`httpBody` 默认关闭。它会 patch `fetch` 和 `XMLHttpRequest`，只在请求失败、请求抛错或状态码 `>= 400` 时上报 body。
-
-```javascript
-new BkOpenTelemetry({
-  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=***');
-      },
+  context: {
+    user: { id: window.USER_ID },
+    attributes: {
+      page: () => ({ 'biz.module': 'order' }),
+      metric: () => ({ 'biz.app': 'order-center' }),
     },
   },
-});
-```
-
-配置项：
-
-- `httpBody: true`: 使用默认配置开启。
-- `httpBody.maxBodySize`: 单个请求或响应 body 最大采集长度，默认 `10 * 1024` 字符。
-- `httpBody.redact`: body 上报前的脱敏函数，必须返回字符串。
-
-`redact` 入参：
-
-- `body`: 已截断后的 body 字符串。
-- `type`: `request` 或 `response`。
-- `url`: 请求 URL。
-- `method`: 请求方法。
-- `status`: 响应状态码，网络错误时可能为空。
-- `contentType`: body 的 content-type。
-- `truncated`: 是否被 `maxBodySize` 截断。
-
-建议只在排障需要时开启 `httpBody`，并务必处理密码、token、手机号等敏感信息。
-
-## 8. 加公共属性和脱敏
-
-公共属性适合放业务线、模块、页面类型等每条数据都想带上的信息。
-
-```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 => {
+    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, '***');
-        }
-      }
+      delete next['biz.secret'];
       return next;
     },
   },
 });
 ```
 
-`attributes` 配置项：
-
-- `attributes.page`: 页面、接口、资源、错误等 RUM 数据都会带上。
-- `attributes.metric`: Web Vitals、Long Task、Route Timing、WebSocket 等 metric 会带上。
-- `attributes.error`: JS 错误、白屏、CSP 等错误类数据会带上。
-- `attributes.custom`: `reportCustomEvent` 上报的自定义事件会带上。
-
-`privacy` 配置项：
-
-- `privacy.redactUrl`: 处理 URL，例如 `url.full`、`document.referrer`、资源 URL。
-- `privacy.redactAttributes`: 处理 span 和 log 属性。适合兜底清理敏感字段。
-- `plugins.httpBody.redact`: 只处理请求和响应 body。
-
-脱敏顺序可以简单理解为：URL 先走 `redactUrl`，属性整体再走 `redactAttributes`。
-
-## 9. 配置设备和会话
-
-`device` 和 `session` 默认开启，一般不需要配置。多应用共用同一域名时，可以自定义 storage key。
-
-```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,
-    },
-  },
-});
-```
-
-`device` 配置项：
-
-- `device: true`: 使用默认设备配置。
-- `device.storageKey`: 设备 ID 的 localStorage key，默认 `BK_RUM_DEVICE_ID`。
-- 设备 ID 跨会话持久，会写入 `device.id`。
-
-`session` 配置项：
-
-- `session: true`: 使用默认会话配置。
-- `session.storageKey`: 会话 storage key。默认会按上报 endpoint host 自动生成隔离后缀。
-- `session.inactivityMs`: 用户不活跃多久后创建新会话，默认 `30` 分钟。
-- `session.maxLifetimeMs`: 会话最长持续时间，默认 `24` 小时。
+生产接入至少确认以下事项：
 
-会话会写入 `session.id`，并在首次创建或轮换时上报 `session.start` / `session.rotate` log。
+1. `getPathGroup` 已把动态 ID 转成低基数路由模板。
+2. 跨域 Trace Header 白名单足够精确，服务端 CORS 已放行 `traceparent`。
+3. `user.id`、URL、错误和业务属性满足隐私要求；HTTP Body 默认保持关闭。
+4. SPA 的 `blankScreen.rootSelector` 指向真实挂载节点。
+5. 同一页面只运行一个实例，避免重复 patch Fetch/XHR/WebSocket。
 
-## 10. 手动上报业务事件
+## 手动事件与 View
 
-### 自定义事件
+```ts
+bkOT.setUser({ id: 'user-001' });
 
-```javascript
-bkOT.reportCustomEvent({
-  name: 'order.checkout',
-  attributes: {
-    'biz.order_id': 'O20260527001',
-    'biz.order_amount': 199,
-  },
+bkOT.reportAction({
+  name: '立即购买',
+  attributes: { 'biz.order_id': 'O20260716001' },
 });
-```
-
-### 自定义失败事件
 
-```javascript
 bkOT.reportCustomEvent({
   name: 'order.checkout',
-  attributes: {
-    'biz.order_id': 'O20260527001',
-  },
-  error: new Error('库存不足'),
-});
-```
-
-### 手动上报用户操作
-
-```javascript
-bkOT.reportAction({
-  type: 'click',
-  targetText: '立即购买',
-  targetTag: 'button',
-  attributes: {
-    'biz.order_id': 'O20260527001',
-  },
-});
-```
-
-说明：
-
-- `reportCustomEvent.name`: 事件名，会生成 `custom.${name}` span。
-- `reportCustomEvent.attributes`: 业务属性，会和 `attributes.custom` 合并。
-- `reportCustomEvent.error`: 传入后事件结果会标记为 error，并记录 exception。
-- `reportAction.type`: 操作类型，会生成 `action.${type}` span。
-- 未命中采样时，手动上报事件会被静默丢弃；`debug: true` 时会打印提示。
-
-## 11. 控制采样、调试和上报
-
-```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,
-      },
-    },
-  },
-});
-```
-
-常用控制项：
-
-- `enabled`: 是否启用 SDK，默认 `true`。设为 `false` 后不会启动采集和上报。
-- `debug`: 是否在控制台输出 exporter 数据和插件异常，默认 `false`。
-- `sampling.rate`: 采样率，范围 `0 - 1`，默认 `1`。
-- `spanProcessor`: trace processor 模式，默认 `batch`。本地调试可用 `simple`。
-- `spanBatch`: `batch` 模式的批量上报配置。
-- `transport.endpoint`: 上报根地址（不含路径前缀），默认 `http://localhost:4318`。SDK 会追加 `/v1/rum`、`/v1/metrics`、`/v1/logs`。单信号自定义 URL 时不再拼接。
-- `transport.token`: 默认鉴权 token。
-- `transport.headers`: 所有信号共用请求头。
-- `transport.signals.traces/metrics/logs`: 分别配置某一类信号。
-
-采样结果会在一次浏览器会话中保持稳定。`rate < 1` 时，SDK 会把采样结果写入 `sessionStorage`；不可用时降级到内存缓存。
-
-如果三类信号要发到不同地址：
-
-```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',
-      },
-    },
-  },
-});
-```
-
-请求头优先级为：`transport.token` 默认头 < `transport.headers` < 单信号 `headers`。
-
-## 12. 控制启动和生命周期
-
-默认 `autoStart: true`。如果要先注册自定义插件或 instrumentation，再启动 SDK，可以关闭自动启动。
-
-```javascript
-const bkOT = new BkOpenTelemetry({
-  autoStart: false,
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
-});
-
-await bkOT.start();
-```
-
-生命周期方法：
-
-```javascript
-await bkOT.flush();
-await bkOT.shutdown();
-```
-
-- `start`: 启动 provider、instrumentation 和插件。重复调用会直接返回。
-- `flush`: 立即刷新插件、trace、metric、log。
-- `shutdown`: 先刷新，再卸载插件、事件监听和 instrumentation。关闭后不能再次启动同一个实例。
-
-## 13. 扩展插件
-
-普通接入方通常不需要扩展插件。只有默认采集不满足时，再使用插件能力。
-
-```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', {
-      'biz.plugin': 'demo',
-    });
-    span.end();
-  },
-});
-
-const bkOT = new BkOpenTelemetry({
-  autoStart: false,
-  plugins: {
-    custom: [plugin],
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
+  attributes: { 'biz.order_amount': 199 },
 });
-
-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';
+手动 View 最稳妥的接入方式是在 SDK 启动并建立 Session 后创建：
 
+```ts
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'manual-view-app' },
   autoStart: false,
-  instrumentations: {
-    custom: [new MyCustomInstrumentation()],
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-  },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: { view: { tracking: 'manual' } },
 });
 
 await bkOT.start();
+bkOT.startView({ name: '订单详情', url: location.href });
 ```
 
-也可以在 `start()` 前链式注册：
-
-```javascript
-bkOT.useInstrumentation(new MyCustomInstrumentation());
-```
-
-注意：`use` 和 `useInstrumentation` 必须在 `start()` 前调用。如果使用默认自动启动，请改成 `autoStart: false`。
-
-## 15. 完整配置速查
-
-```javascript
-new BkOpenTelemetry({
-  app: {
-    name: 'demo-app',
-    environment: 'production',
-    version: '1.0.0',
-  },
-  user: {
-    id: 'user-001',
-  },
-  transport: {
-    endpoint: 'https://your-otlp-collector',
-    token: 'your-report-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: {},
-    },
-  },
-  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,
-    resource: true,
-    error: true,
-    webVitals: true,
-    blankScreen: true,
-    device: true,
-    session: true,
-    action: false,
-    httpBody: false,
-    longTask: false,
-    routeTiming: false,
-    cspViolation: false,
-    websocket: false,
-  },
-});
-```
-
-配置默认值：
-
-- `autoStart`: 默认 `true`。
-- `enabled`: 默认 `true`。
-- `debug`: 默认 `false`。
-- `sampling.rate`: 默认 `1`。
-- `spanProcessor`: 默认 `batch`。
-- `transport.endpoint`: 默认 `http://localhost:4318`。
-- `app.environment`: 默认 `production`。
-- `app.name`: 默认 `unknown_service`。
+`reportAction()`、`reportCustomEvent()` 和 View 控制方法均受 Session 采样/有效状态约束。调试时先使用 `session.sampleRate: 1`。
 
-## 16. 推荐接入顺序
+## 文档导航
 
-新项目建议按下面顺序接入：
+| 目标 | 文档 |
+| --- | --- |
+| 首次接入 | [快速上手](./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) |
 
-1. 先配置 `app`、`transport`、`user`，确认页面访问、错误、接口请求能上报。
-2. 再配置 `route.getPathGroup`，避免 URL 动态 ID 导致维度过高。
-3. 按业务需要开启 `routeTiming`、`longTask`、`action`、`websocket`。
-4. 排障时再开启 `httpBody`，并先做好脱敏。
-5. 最后补充 `attributes` 和 `privacy`，统一业务维度和敏感信息处理。
+完整 Wiki 入口见 [`wikis/`](./wikis/README.md)。文档以当前 `src/` 和 `src/index.ts` 公开导出为事实来源，不承诺历史配置兼容。