@blueking/open-telemetry 0.0.8 → 0.0.10

package/README.md

@@ -1,22 +1,15 @@
 # @blueking/open-telemetry
 
-蓝鲸监控 RUM OT SDK，使用 OpenTelemetry 采集页面访问、接口请求、静态资源、错误、Web Vitals、设备和会话等数据，并通过 OTLP HTTP 上报。
+`@blueking/open-telemetry` 是蓝鲸 RUM Web 上报 SDK。它基于 OpenTelemetry 采集页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话等数据，并通过 OTLP HTTP 上报到 collector。
 
-## 安装和使用
+## 1. 安装和使用
+
+### 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';
 
@@ -41,7 +34,7 @@ const bkOT = new BkOpenTelemetry({
 ```html
 <script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
 <script>
-  const bkOT = new window.BkOpenTelemetry({
+  window.bkOT = new window.BkOpenTelemetry({
     app: {
       name: 'demo-app',
       environment: 'production',
@@ -58,46 +51,71 @@ const bkOT = new BkOpenTelemetry({
 </script>
 ```
 
-默认 `autoStart: true`，所以 `new BkOpenTelemetry()` 后 SDK 会自动启动。
+`new BkOpenTelemetry()` 后默认自动启动，不需要再手动调用 `start()`。
 
-`transport.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>`。
+`transport.token` 会作为默认鉴权头发送：`Authorization: Bearer <token>`。
 
-## 2. 先理解默认采集
+## 2. 默认采集
 
-不写 `rum` 配置时，SDK 已经默认开启常用 RUM 能力：
+只配置 `app` 和 `transport` 后，SDK 已经默认开启常用能力：
 
-- 页面加载：`documentLoad`
-- 页面访问：`pageView`
-- 接口请求：`fetch`、`xhr`
-- 静态资源：`resource`
-- JS 错误：`error`
-- 页面体验：`webVitals`、`blankScreen`
-- 用户环境：`device`、`session`
-- 用户交互 instrumentation：`userInteraction`
+- `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`: 长任务
-- `routeTiming`: 路由耗时
-- `cspViolation`: CSP 违规
-- `websocket`: WebSocket 事件
+- `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. 给数据加上应用、用户和路由
 
-## 3. 给数据加上用户和路由
+建议先补齐应用标识、用户 ID 和路由归类。这样后续排查问题时，可以按应用、版本、用户、页面聚合。
 
 ```javascript
 const bkOT = new BkOpenTelemetry({
   app: {
-    name: 'demo-app',
+    name: 'order-center',
     environment: 'production',
-    version: '1.0.0',
+    version: '1.2.0',
   },
   transport: {
     endpoint: 'https://your-otlp-collector',
@@ -107,14 +125,23 @@ const bkOT = new BkOpenTelemetry({
     id: window.USER_ID,
   },
   route: {
-    getPathGroup: url => new URL(url).pathname,
+    getPathGroup: url => {
+      const { pathname } = new URL(url, location.href);
+      return pathname.replace(/\/user\/\d+/, '/user/:id');
+    },
   },
 });
 ```
 
-`route.getPathGroup` 用来把高基数 URL 归类成低基数路径。例如 `/user/123` 可以归类成 `/user/:id`，方便聚合分析。
+常用基础配置：
+
+- `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' });
@@ -122,85 +149,175 @@ bkOT.setUser({ id: 'user-001' });
 bkOT.setView({
   id: 'view-001',
   url: location.href,
-  urlPathGroup: '/user/:id',
+  urlPathGroup: '/order/:id',
   loadingType: 'route_change',
 });
 ```
 
-## 4. 按需打开更多能力
+`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',
   },
-  rum: {
-    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'],
-      },
+  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,
     },
+    blankScreen: {
+      rootSelector: '#app',
+      checkDelay: 3000,
+      threshold: 0.8,
+      ignoreSelectors: ['.app-loading', '.page-skeleton'],
+    },
+    cspViolation: true,
   },
 });
 ```
 
-如果要关闭默认能力，显式写 `false`：
+错误采集说明：
+
+- `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',
-    token: 'your-report-token',
   },
-  rum: {
-    plugins: {
-      webVitals: false,
-      blankScreen: false,
+  plugins: {
+    action: {
+      eventNames: ['click', 'submit', 'keydown'],
     },
-    instrumentations: {
-      fetch: false,
-      xhr: false,
+    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=***');
+      },
     },
   },
 });
 ```
 
-## 5. 加公共属性和脱敏
+配置项：
+
+- `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',
-    token: 'your-report-token',
   },
   attributes: {
     page: () => ({
+      'biz.module': 'order',
       'rum.page.host': location.host,
       'rum.page.path': location.pathname,
     }),
-    custom: () => ({
-      'biz.team': 'demo',
+    metric: () => ({
+      'biz.metric_source': 'rum',
     }),
     error: () => ({
       'biz.error_source': 'browser',
     }),
-    metric: () => ({
-      'biz.metric_source': 'rum',
+    custom: () => ({
+      'biz.team': 'demo',
     }),
   },
   privacy: {
@@ -218,77 +335,152 @@ new BkOpenTelemetry({
 });
 ```
 
-- `attributes.page`: 页面、接口、资源等 RUM 数据都会带上。
+`attributes` 配置项：
+
+- `attributes.page`: 页面、接口、资源、错误等 RUM 数据都会带上。
+- `attributes.metric`: Web Vitals、Long Task、Route Timing、WebSocket 等 metric 会带上。
+- `attributes.error`: JS 错误、白屏、CSP 等错误类数据会带上。
 - `attributes.custom`: `reportCustomEvent` 上报的自定义事件会带上。
-- `attributes.error`: 错误数据会带上。
-- `attributes.metric`: 指标数据会带上。
-- `privacy.redactUrl`: 处理 URL，例如 `url.full`、`document.referrer`。
-- `privacy.redactAttributes`: 处理 span/log 属性。
-- `rum.plugins.httpBody.redact`: 只处理请求/响应 body。
 
-## 6. 手动上报业务事件
+`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。
+
+## 10. 手动上报业务事件
+
+### 自定义事件
 
 ```javascript
 bkOT.reportCustomEvent({
   name: 'order.checkout',
   attributes: {
-    'biz.order_id': 'O20260509001',
+    'biz.order_id': 'O20260527001',
     'biz.order_amount': 199,
   },
 });
 ```
 
-失败事件可以带 `error`：
+### 自定义失败事件
 
 ```javascript
 bkOT.reportCustomEvent({
   name: 'order.checkout',
   attributes: {
-    'biz.order_id': 'O20260509001',
+    'biz.order_id': 'O20260527001',
   },
   error: new Error('库存不足'),
 });
 ```
 
-也可以手动上报用户操作：
+### 手动上报用户操作
 
 ```javascript
 bkOT.reportAction({
   type: 'click',
   targetText: '立即购买',
   targetTag: 'button',
+  attributes: {
+    'biz.order_id': 'O20260527001',
+  },
 });
 ```
 
-## 7. 控制采样、调试和上报
+说明：
+
+- `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-Custom-Header': 'value',
+      'X-Biz-ID': 'demo',
     },
     signals: {
       traces: {
         timeoutMillis: 10000,
       },
+      metrics: {
+        concurrencyLimit: 2,
+      },
     },
   },
 });
 ```
 
-- `debug`: 打开后会在控制台输出调试信息。
+常用控制项：
+
+- `enabled`: 是否启用 SDK，默认 `true`。设为 `false` 后不会启动采集和上报。
+- `debug`: 是否在控制台输出 exporter 数据和插件异常，默认 `false`。
 - `sampling.rate`: 采样率，范围 `0 - 1`，默认 `1`。
-- `spanProcessor`: 默认 `batch`；本地调试可用 `simple`。
-- `transport.headers`: 给所有信号加请求头。
-- `transport.signals.traces/metrics/logs`: 分别配置不同信号。
+- `spanProcessor`: trace processor 模式，默认 `batch`。本地调试可用 `simple`。
+- `spanBatch`: `batch` 模式的批量上报配置。
+- `transport.endpoint`: OTLP collector 根地址，默认 `http://localhost:4318`。
+- `transport.token`: 默认鉴权 token。
+- `transport.headers`: 所有信号共用请求头。
+- `transport.signals.traces/metrics/logs`: 分别配置某一类信号。
+
+采样结果会在一次浏览器会话中保持稳定。`rate < 1` 时，SDK 会把采样结果写入 `sessionStorage`；不可用时降级到内存缓存。
 
 如果三类信号要发到不同地址：
 
@@ -299,44 +491,46 @@ new BkOpenTelemetry({
     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',
+        traces: 'https://trace.example.com/v1/traces',
+        metrics: 'https://metric.example.com/v1/metrics',
+        logs: 'https://log.example.com/v1/logs',
       },
     },
   },
 });
 ```
 
-请求头优先级为：`token` 默认头 < `transport.headers` < 单信号 `headers`。
+请求头优先级为：`transport.token` 默认头 < `transport.headers` < 单信号 `headers`。
 
-## 8. 生命周期
+## 12. 控制启动和生命周期
 
-```javascript
-await bkOT.flush();
-await bkOT.shutdown();
-```
-
-- `flush`: 立即刷新插件、trace、metric、log。
-- `shutdown`: 刷新后关闭 SDK，并卸载事件监听。
-
-如果你要先注册插件，再手动启动：
+默认 `autoStart: true`。如果要先注册自定义插件或 instrumentation，再启动 SDK，可以关闭自动启动。
 
 ```javascript
 const bkOT = new BkOpenTelemetry({
   autoStart: false,
   transport: {
     endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
   },
 });
 
 await bkOT.start();
 ```
 
-## 9. 扩展插件
+生命周期方法：
+
+```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';
@@ -348,17 +542,20 @@ const plugin = createPlugin({
       'biz.plugin_enabled': true,
     });
 
-    const span = context.startSpan('demo.plugin_ready');
+    const span = context.startSpan('demo.plugin_ready', {
+      'biz.plugin': 'demo',
+    });
     span.end();
   },
 });
 
 const bkOT = new BkOpenTelemetry({
   autoStart: false,
-  plugins: [plugin],
+  plugins: {
+    custom: [plugin],
+  },
   transport: {
     endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
   },
 });
 
@@ -371,7 +568,17 @@ await bkOT.start();
 bkOT.use(plugin);
 ```
 
-## 10. 接入原生 OpenTelemetry Instrumentation
+插件上下文常用方法：
+
+- `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';
@@ -379,10 +586,11 @@ import { MyCustomInstrumentation } from './my-custom-instrumentation';
 
 const bkOT = new BkOpenTelemetry({
   autoStart: false,
-  instrumentations: [new MyCustomInstrumentation()],
+  instrumentations: {
+    custom: [new MyCustomInstrumentation()],
+  },
   transport: {
     endpoint: 'https://your-otlp-collector',
-    token: 'your-report-token',
   },
 });
 
@@ -394,3 +602,107 @@ await bkOT.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/traces',
+        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`。
+
+## 16. 推荐接入顺序
+
+新项目建议按下面顺序接入：
+
+1. 先配置 `app`、`transport`、`user`，确认页面访问、错误、接口请求能上报。
+2. 再配置 `route.getPathGroup`，避免 URL 动态 ID 导致维度过高。
+3. 按业务需要开启 `routeTiming`、`longTask`、`action`、`websocket`。
+4. 排障时再开启 `httpBody`，并先做好脱敏。
+5. 最后补充 `attributes` 和 `privacy`，统一业务维度和敏感信息处理。