@blueking/open-telemetry 0.0.13 → 0.0.15

package/skills/bk-rum-otele/references/configuration.md

@@ -2,317 +2,224 @@
 
 # 配置总览
 
-SDK 的配置入口是 `BkOTOptions`。推荐先完成 `app`、`transport`、`sampling`、`route`、`privacy` 五类基础配置，再按需打开插件。
-
-## 完整配置示例
+SDK 入口按职责分为 `application`、`transport`、`session`、`tracking`、`context`、`privacy`、`extensions`。`application.name` 与 `transport` 必填；根 `transport.endpoint` 可由所有已开启信号的独立 endpoint 取代。
 
 ```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-
 const bkOT = new BkOpenTelemetry({
-  enabled: true,
-  autoStart: true,
-  debug: false,
-  app: {
+  application: {
     name: 'bk-monitor-web',
     environment: 'production',
     version: '1.4.2',
   },
-  user: {
-    id: 'user-12345',
-  },
   transport: {
     endpoint: 'https://rum-collector.example.com',
     token: 'report-token',
-    headers: {
-      'x-bk-tenant-id': 'system',
+    signals: {
+      traces: { processor: 'batch', batch: { maxQueueSize: 2048 } },
+      metrics: { intervalMillis: 60_000 },
     },
   },
-  sampling: {
-    rate: 0.2,
+  session: {
+    sampleRate: 0.2,
   },
-  route: {
-    getPathGroup: url => new URL(url).pathname.replace(/\/\d+/g, '/:id'),
+  tracking: {
+    view: {
+      tracking: 'auto',
+      getPathGroup: url => new URL(url, location.href).pathname.replace(/\/\d+/g, '/:id'),
+    },
+    request: {
+      allowedTracingUrls: ['https://api.example.com'],
+      excludedUrls: [/\/health$/],
+    },
+    longTask: false,
+    websocket: false,
+  },
+  context: {
+    user: { id: 'user-12345' },
+    attributes: {
+      page: () => ({ 'biz.space_id': window.__BK_SPACE_ID__ }),
+    },
   },
   privacy: {
-    redactUrl: url => url.replace(/([?&](token|bk_ticket)=)[^&]+/g, '$1***'),
+    trackingConsent: 'granted',
     redactAttributes: attributes => attributes,
   },
-  attributes: {
-    page: () => ({
-      'biz.space_id': window.__BK_SPACE_ID__,
-    }),
-    custom: () => ({
-      'biz.app_code': 'bk-monitor',
-    }),
-  },
-  instrumentations: {
-    documentLoad: true,
-    fetch: true,
-    xhr: true,
-    userInteraction: true,
-  },
-  plugins: {
-    pageView: true,
-    resource: true,
-    error: true,
-    webVitals: true,
-    blankScreen: {
-      rootSelector: '#app',
-      checkDelay: 3000,
-      threshold: 0.8,
-    },
-    session: true,
-    device: true,
-    action: false,
-    httpBody: false,
-    longTask: false,
-    routeTiming: false,
-    cspViolation: false,
-    websocket: false,
+  extensions: {
+    plugins: [],
+    instrumentations: [],
   },
 });
-
-export default bkOT;
 ```
 
 ## 顶层配置
 
 | 配置 | 默认值 | 说明 |
 | --- | --- | --- |
-| `enabled` | `true` | 为 `false` 时不注册 provider，也不启动插件。 |
-| `autoStart` | `true` | 构造后自动调用 `start()`。需要注册自定义插件时建议设为 `false`。 |
-| `debug` | `false` | 打印 exporter 输出和部分调试日志。 |
-| `app.name` | `unknown_service` | 写入 `service.name`。 |
-| `app.environment` | `production` | 写入 `deployment.environment.name`。 |
-| `app.version` | `undefined` | 写入 `service.version`。 |
-| `spanProcessor` | `batch` | 可选 `batch` 或 `simple`。本地调试可用 `simple`。 |
-
-### 固定行为（当前不可配置）
-
-- **Metric 上报间隔固定 60s**（`PeriodicExportingMetricReader`），暂不开放配置。
-- SDK 会向 resource 注入固定属性：`rum.provider=blueking`、`telemetry.sdk.language=webjs`，以及由 `app` 派生的 `service.name`、`service.version`、`deployment.environment.name`。
-
-示例：只在生产环境开启。
-
-```ts
-new BkOpenTelemetry({
-  enabled: import.meta.env.PROD,
-  app: {
-    name: 'bk-monitor-web',
-    environment: import.meta.env.MODE,
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-```
-
-## Instrumentation 配置
-
-| 配置 | 默认值 | 说明 |
+| `application.name` | 无 | 必填，写入 `service.name` |
+| `application.environment` | `production` | 写入 `deployment.environment.name` |
+| `application.version` | 无 | 写入 `service.version` |
+| `transport.endpoint` | 无 | 上报根地址；已开启信号没有独立 endpoint 时必填 |
+| `transport.signals.traces` | `{}` | Trace 配置；设为 `false` 关闭 |
+| `transport.signals.metrics` | `{}` | Metric 配置；设为 `false` 关闭 |
+| `transport.signals.logs` | `{}` | Log 配置；设为 `false` 关闭 |
+| `session.sampleRate` | `1` | Session 级确定性采样率 |
+| `tracking.view.tracking` | `auto` | 自动或手动 View |
+| `tracking.view.loadingTime` | `true` | 自动计算 View loading time |
+| `privacy.trackingConsent` | `granted` | 初始化授权状态 |
+| `enabled` | `true` | 是否启用 SDK |
+| `autoStart` | `true` | 构造后自动启动 |
+| `debug` | `false` | 输出 exporter 与插件调试信息 |
+
+Session 固定为 15 分钟无活动过期、4 小时最长生命周期。View 和 Session 是 RUM 关联边界，不能作为普通插件关闭。
+
+## 内置采集开关
+
+内置能力全部位于 `tracking`：
+
+| 配置 | 默认 | 说明 |
 | --- | --- | --- |
-| `documentLoad` | `true` | 采集文档加载和导航性能 span。 |
-| `fetch` | `true` | patch `fetch`，采集 HTTP span，并支持同源 traceparent。 |
-| `xhr` | `true` | patch `XMLHttpRequest`，采集 HTTP span。 |
-| `userInteraction` | `true` | 使用 OpenTelemetry 官方用户交互 instrumentation。 |
-| `propagateTraceHeaderUrls` | `undefined`（仅同源） | 把跨域后台 API 纳入 `traceparent`（含 OpenTelemetry traceId）注入范围。 |
-
-`propagateTraceHeaderUrls` 用于让 fetch/xhr 请求在调用后台 API 时带上 W3C `traceparent` 请求头，实现前后端 trace 串联。同源请求始终注入，该配置只用于在此基础上扩展跨域目标，取值支持：
-
-- `'all'`：所有请求都注入（含跨域，使用前确认隐私/CORS 影响）。
-- `string`：URL 包含该子串即注入，例如 `'api.example.com'`。
-- `RegExp`：URL 匹配该正则即注入。
-- 上述字符串/正则组成的数组：命中任意一个即注入。
-- `(url: string) => boolean`：完全自定义判断。
-
-```ts
-new BkOpenTelemetry({
-  instrumentations: {
-    // 给所有调用 api.example.com / api.internal.com 的后台请求注入 traceparent
-    propagateTraceHeaderUrls: [/https:\/\/api\.example\.com/, 'api.internal.com'],
-  },
-});
-```
-
-> 注意：向跨域服务注入自定义头会触发 CORS 预检，目标服务需在 `Access-Control-Allow-Headers` 中放行 `traceparent`（以及按需的 `tracestate`），否则请求会被浏览器拦截。
-
-示例：关闭接口自动采集。
+| `view` | 开 | 初始加载、SPA、BFCache、手动 View |
+| `request` | 开 | Fetch/XHR 请求 span、Trace Header、body |
+| `resource` | 开 | 静态资源 span；PerformanceObserver 始终为 View 活动和请求 timing 服务 |
+| `error` | 开 | JS、Promise 与资源错误 |
+| `webVitals` | 开 | FCP/LCP/TTFB 及 View 级 CLS/INP |
+| `blankScreen` | 开 | 白屏检测 |
+| `device` | 开 | 浏览器、OS、屏幕与网络信息 |
+| `action` | 开 | 点击 Action 与活动聚合 |
+| `longTask` | 关 | LoAF/Long Task |
+| `websocket` | 关 | WebSocket 指标 |
+| `cspViolation` | 关 | CSP 违规 |
 
 ```ts
 new BkOpenTelemetry({
-  instrumentations: {
-    fetch: false,
-    xhr: false,
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    request: false,
+    blankScreen: false,
+    longTask: { threshold: 80 },
   },
 });
 ```
 
-## 插件默认开关
+## 请求配置
 
-| 插件 | 默认状态 | 说明 |
-| --- | --- | --- |
-| `pageView` | 开 | 初始页面和 SPA 路由 view。 |
-| `resource` | 开 | 静态资源 PerformanceObserver。 |
-| `error` | 开 | JS error、unhandledrejection、资源错误。 |
-| `webVitals` | 开 | CLS、FCP、INP、LCP、TTFB。 |
-| `blankScreen` | 开 | 延迟检测页面空白比例。 |
-| `device` | 开 | 设备、浏览器、OS、viewport、网络属性。 |
-| `session` | 开 | session.id 生成、轮换和跨 tab 同步。 |
-| `action` | 关 | 自动采集 click、submit、keydown 等动作。 |
-| `httpBody` | 关 | 错误路径采集请求/响应 body。 |
-| `longTask` | 关 | Long Task API。 |
-| `routeTiming` | 关 | SPA 路由切换渲染耗时估算。 |
-| `cspViolation` | 关 | CSP 违规 error span。 |
-| `websocket` | 关 | WebSocket 连接、消息、错误、关闭。 |
-
-示例：开启高成本插件。
+`tracking.request.allowedTracingUrls` 是严格白名单，同源请求也必须命中后才注入 `traceparent`。关闭 Trace 时不会注入。`excludedUrls` 命中后完全不采集。SDK 自身已开启 signal endpoint 始终排除。
 
 ```ts
 new BkOpenTelemetry({
-  plugins: {
-    longTask: {
-      threshold: 80,
-    },
-    httpBody: {
-      maxBodySize: 4096,
-      redact: ({ body, type }) => (type === 'request' ? '[redacted request body]' : body),
+  application: { name: 'request-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    request: {
+      allowedTracingUrls: [/https:\/\/api\.example\.com/],
+      excludedUrls: [/\/health(?:\?|$)/],
+      beforeSend: (event, context) => {
+        event.attributes['request.transport'] = context.type;
+        return true;
+      },
+      body: {
+        capture: 'errors',
+        redact: ({ body }) => body.replace(/token=[^&]+/g, 'token=***'),
+      },
     },
-    websocket: true,
   },
 });
 ```
 
-# 上报与采样
+跨域注入 Trace Header 可能触发 CORS 预检，服务端需要放行 `traceparent`。
 
-SDK 使用 OTLP HTTP exporter 分别上报 traces、metrics、logs。默认 endpoint 是 `http://localhost:4318`，会自动拼接 `/rum`、`/metrics`、`/logs`。
+## 全局 beforeSend
 
-## 统一 endpoint
+`tracking.beforeSend` 在 span/log 进入 exporter 前执行，可修改属性或返回 `false` 丢弃事件。内部 `bk.rum.sampled` 标记会在此之前移除。
 
 ```ts
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://rum-collector.example.com/v1',
-    token: 'report-token',
+tracking: {
+  beforeSend(event) {
+    delete event.attributes['debug.payload'];
+    return event.name !== 'custom.ignore-me';
   },
-});
+}
 ```
 
-实际使用的上报地址为：
+## 不再支持的旧入口
+
+`app`、`sampling`、`route`、顶层 `view`、`plugins`、`instrumentations`、`attributes`、`spanProcessor`、`spanBatch` 已删除，不做兼容映射。
 
-- traces：`https://rum-collector.example.com/v1/rum`
-- metrics：`https://rum-collector.example.com/v1/metrics`
-- logs：`https://rum-collector.example.com/v1/logs`
+# 传输与采样
 
-## 分信号 endpoint
+## Endpoint
 
-如果 traces、metrics、logs 由不同网关接收，可以使用 `transport.signals`。
+`transport.endpoint` 是可选根地址。未配置独立地址的已开启信号会基于它生成 `/v1/rum`、`/v1/metrics`、`/v1/logs`；单信号 `endpoint` 是完整 URL，不再拼接路径。
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'demo' },
   transport: {
-    endpoint: 'https://rum-collector.example.com',
-    headers: {
-      'x-bk-app-code': 'bk-monitor',
-    },
+    endpoint: 'https://collector.example.com',
+    token: 'report-token',
     signals: {
-      endpoints: {
-        traces: 'https://trace-gateway.example.com/v1/rum',
-        metrics: 'https://metric-gateway.example.com/v1/metrics',
-        logs: 'https://log-gateway.example.com/v1/logs',
-      },
       traces: {
-        timeoutMillis: 5000,
-        concurrencyLimit: 4,
-      },
-      logs: {
-        headers: {
-          'x-bk-log-source': 'browser',
+        endpoint: 'https://trace.example.com/v1/rum',
+        processor: 'batch',
+        batch: {
+          maxQueueSize: 2048,
+          maxExportBatchSize: 512,
+          scheduledDelayMillis: 5000,
+          exportTimeoutMillis: 30000,
         },
       },
+      metrics: { endpoint: 'https://metric.example.com/v1/metrics', intervalMillis: 60_000 },
+      logs: { endpoint: 'https://log.example.com/v1/logs' },
     },
   },
 });
 ```
 
-`transport.token` 会生成默认 `Authorization: Bearer <token>`，显式配置的 `headers` 会继续合并进去。
-
-## 避免自循环采集
-
-SDK 内置 `FilteringSpanProcessor`，会过滤指向自身 OTLP endpoint 的 span，避免上报请求本身再次被 fetch/xhr instrumentation 采集。
+## 独立信号开关
 
-示例：自定义 Collector 地址时无需手动忽略自身上报。
+三类信号默认全部开启。设为 `false` 时，不创建对应 exporter、processor 或 metric reader：
 
 ```ts
 new BkOpenTelemetry({
+  application: { name: 'trace-only-demo' },
   transport: {
-    endpoint: 'https://rum-collector.example.com/otlp',
-  },
-  instrumentations: {
-    fetch: true,
-    xhr: true,
+    signals: {
+      traces: { endpoint: 'https://trace.example.com/v1/rum' },
+      metrics: false,
+      logs: false,
+    },
   },
 });
 ```
 
-## 同源 traceparent 传播
-
-fetch/xhr instrumentation 会给符合条件的同源请求注入 W3C `traceparent`，用于打通前后端 trace。跨域请求是否能传播还取决于服务端 CORS 是否允许该 header。
-
-示例：前端请求同源 API。
-
-```ts
-await fetch('/api/orders/202605270001', {
-  method: 'GET',
-});
-```
-
-## 会话级 sticky 采样
+校验规则：
 
-`sampling.rate` 范围是 `0` 到 `1`。SDK 会将采样结果保存在 session 维度，保证同一会话内行为一致。
+- 至少开启一种信号，三类不能全部为 `false`。
+- 每个开启信号必须有独立 endpoint，或能回退到根 `transport.endpoint`。
+- 关闭 Trace 后不记录 Span，也不会向 `allowedTracingUrls` 注入 `traceparent`。
+- 关闭 Metric 后不启动周期导出定时器。
+- 关闭 Log 不影响 Session/View 上下文维护，但不会产生 Session、View Snapshot、HTTP body 等 Log。
 
-```ts
-new BkOpenTelemetry({
-  sampling: {
-    rate: 0.05,
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-```
-
-需要注意：
+只开启 Metric 时没有精确 `view.id` 下钻链路；需要从指标定位具体 View 时，至少开启 Trace。
 
-- `rate: 1` 表示全量上报。
-- `rate: 0` 表示 RUM 插件和手动事件都不上报。
-- 未命中采样时，主动产生数据的 RUM 插件不会启动。
-- 调试时建议临时设置 `rate: 1` 和 `debug: true`。
+请求头优先级：`token` 生成的 Authorization < `transport.headers` < 单 signal `headers`。
 
-## Batch 与 Simple Processor
+浏览器 exporter 使用 `fetch keepalive`，SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。`shutdown()` 会先结束 View 和插件，再 flush final Snapshot，最后关闭 provider。
 
-默认使用 batch 处理器，适合生产环境。调试时可以用 simple 处理器减少等待。
+## Session 级确定性采样
 
 ```ts
 new BkOpenTelemetry({
-  debug: true,
-  spanProcessor: 'simple',
-  transport: {
-    endpoint: 'http://localhost:4318',
-  },
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  session: { sampleRate: 0.05 },
 });
 ```
 
-批量参数可以通过 `spanBatch` 调整。
+- `1` 表示全量，`0` 表示全部丢弃。
+- 决定由 `application.name + session.id` 的稳定 hash 得出。
+- 不写额外 sessionStorage；同一 Session 内 span/log/metric 决定一致。
+- Session 续期后使用新 ID 重新计算。
 
-```ts
-new BkOpenTelemetry({
-  spanProcessor: 'batch',
-  spanBatch: {
-    maxQueueSize: 2048,
-    maxExportBatchSize: 256,
-    scheduledDelayMillis: 5000,
-    exportTimeoutMillis: 30000,
-  },
-});
-```
+Metric exporter 只接受带内部采样标记的数据点，并在传输前移除该标记。Metric 只保留低基数 `view.url_path_group`，精确 View 关联由 span/log/View Snapshot 的 `view.id` 提供。

package/skills/bk-rum-otele/references/custom-plugin.md

@@ -38,6 +38,7 @@ import { BkOpenTelemetry } from '@blueking/open-telemetry';
 import { bizPlugin } from './biz-plugin';
 
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'plugin-demo' },
   autoStart: false,
   transport: {
     endpoint: 'https://rum-collector.example.com',
@@ -125,18 +126,19 @@ const createResizePlugin = () => {
 
 ## 注册额外 instrumentation
 
-第三方 OpenTelemetry instrumentation 属于 instrumentation 而非 bk-ot 插件，因此挂在顶层 `instrumentations.custom` 下，或通过 `useInstrumentation()` 链式注册。两者区别详见 [Plugin 与 Instrumentation 的区别](./concepts.md)。
+第三方 OpenTelemetry instrumentation 放在 `extensions.instrumentations`，或通过 `useInstrumentation()` 链式注册。两者区别详见 [内置采集与扩展](./concepts.md)。
 
 配置式：
 
 ```ts
 const bkOT = new BkOpenTelemetry({
-  instrumentations: {
-    custom: [new SomeWebInstrumentation()],
-  },
+  application: { name: 'extension-demo' },
   transport: {
     endpoint: 'https://rum-collector.example.com',
   },
+  extensions: {
+    instrumentations: [new SomeWebInstrumentation()],
+  },
 });
 ```
 
@@ -144,6 +146,7 @@ const bkOT = new BkOpenTelemetry({
 
 ```ts
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'extension-demo' },
   autoStart: false,
   transport: {
     endpoint: 'https://rum-collector.example.com',
@@ -155,4 +158,4 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 await bkOT.start();
 ```
 
-> 与受采样影响的 RUM 插件不同，instrumentation 只要 SDK 启用（`enabled !== false`）就会注册，不受 `sampling.rate` 影响。
+> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 RUM 数据仍受 Session sampler 和导出过滤约束。

package/skills/bk-rum-otele/references/data-model.md

@@ -15,17 +15,16 @@ SDK 的数据模型遵循“浏览器 SDK 负责低成本原始数据和单事
 
 | 类型 | 说明 | 常见来源 |
 | --- | --- | --- |
-| `document` | 文档加载 | documentLoad instrumentation、pageView 插件（初始加载） |
-| `http` | 接口请求 | fetch/xhr instrumentation、httpBody 插件 |
-| `resource` | 静态资源 | resource 插件、documentLoad instrumentation |
+| `document` | 文档加载 | View 管理器（初始加载） |
+| `resource` | Fetch/XHR 请求与静态资源 | request、resource 采集 |
 | `vital` | Web Vitals | webVitals 插件 |
 | `error` | 错误 | error 插件、blankScreen 插件、cspViolation 插件、自定义事件错误 |
 | `longtask` | 长任务 | longTask 插件 |
 | `action` | 用户动作 | action 插件、reportAction |
-| `route` | 路由切换 | pageView 插件（SPA 路由）、routeTiming 插件 |
+| `route` | 路由切换 | View 管理器（SPA/手动 View） |
 | `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件 |
 
-> 每种 span 的具体 span 名（如 `browser.web_vital`、`browser.route_change`）、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
+> 每种 span 的具体 span 名、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
 
 示例：自定义业务事件归一为 `custom`。
 
@@ -55,7 +54,7 @@ span.end();
 - `timeout`
 - `abort`
 
-HTTP span 会根据状态码推导结果：`408`、`504` 为 timeout，`>= 400` 为 error，其余为 success。
+请求 Resource Span 会根据状态码推导结果：`408`、`504` 为 timeout，`>= 400` 为 error，其余为 success。
 
 ```ts
 bkOT.reportCustomEvent({
@@ -89,8 +88,8 @@ console.log(getDurationBucket(1200)); // 500ms~2s
 
 - 应用与环境：`service.name`、`deployment.environment.name`、`service.version`
 - 用户与会话：`user.id`、`session.id`
-- View：`view.id`、`view.url`、`view.url_path_group`、`view.loading_type`
-- 终端信息：`device_type`、`browser_name`、`browser_version`、`os_name`、`network.effective_type`
+- View：`view.id`、`view.name`、`view.url`、`view.url_path_group`、`view.loading_type`
+- 终端信息：`device.type`、`browser.name`、`browser.version`、`os.name`、`network.effective_type`
 - HTTP / Resource：`http.request.method`、`http.response.status_code`、`url.full`、`transfer_size`
 - Web Vitals：`vital.metric`、`vital.value`、`vital.rating`
 - Error：`exception.type`、`exception.message`、`exception.stacktrace`、`exception.fingerprint`
@@ -120,3 +119,9 @@ bkOT.reportCustomEvent({
 ```
 
 上例中 `biz.order_id` 适合放在 span/log 中定位单次问题，不适合作为 metric 维度做长期聚合。
+
+## Metric 与 View 的关联
+
+Metric 不携带唯一的 `view.id`、`session.id` 或 `action.id`，只保留 `view.url_path_group`、`view.loading_type` 等低基数维度。这样可以按页面类型聚合，又不会因为每次访问生成新的时序而造成基数爆炸。
+
+需要定位某一次 View 时，使用同一指标对应的 span（例如 `browser.web_vital`）或 View Snapshot Log；它们携带精确的 `session.id` 和 `view.id`。后端需要从聚合指标跳转到样本时，应通过 exemplar 或 span/log 派生聚合建立关联，而不是把 `view.id` 放进 metric labels。

package/skills/bk-rum-otele/references/framework-integration.md

@@ -12,14 +12,17 @@ import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 export const bkOT = new BkOpenTelemetry({
   autoStart: false,
-  app: {
+  application: {
     name: 'vue-rum-demo',
     environment: import.meta.env.MODE,
   },
   transport: {
     endpoint: 'https://rum-collector.example.com',
   },
-  plugins: {
+  tracking: {
+    view: {
+      tracking: 'manual',
+    },
     blankScreen: {
       rootSelector: '#app',
     },
@@ -35,10 +38,9 @@ import App from './App.vue';
 import router from './router';
 
 router.afterEach(to => {
-  bkOT.setView({
+  bkOT.startView({
+    name: to.matched.at(-1)?.path || to.path,
     url: window.location.href,
-    urlPathGroup: to.matched.at(-1)?.path || to.path,
-    loadingType: 'route_change',
   });
 });
 
@@ -49,7 +51,7 @@ createApp(App).use(router).mount('#app');
 
 ## Vue Router 路由模板
 
-如果不想在 `afterEach` 中主动 `setView()`，可以通过 `route.getPathGroup` 统一处理。
+自动模式不需要 `afterEach`，通过 `tracking.view.getPathGroup` 统一生成低基数路径。
 
 ```ts
 const routeGroups = [
@@ -58,10 +60,14 @@ const routeGroups = [
 ];
 
 new BkOpenTelemetry({
-  route: {
-    getPathGroup: url => {
-      const pathname = new URL(url, window.location.href).pathname;
-      return routeGroups.find(route => route.pattern.test(pathname))?.group || pathname.replace(/\/\d+/g, '/:id');
+  application: { name: 'vue-rum-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    view: {
+      getPathGroup: url => {
+        const pathname = new URL(url, window.location.href).pathname;
+        return routeGroups.find(route => route.pattern.test(pathname))?.group || pathname.replace(/\/\d+/g, '/:id');
+      },
     },
   },
 });
@@ -75,9 +81,10 @@ import { useEffect } from 'react';
 import { useLocation, useMatches } from 'react-router-dom';
 
 export const bkOT = new BkOpenTelemetry({
-  app: { name: 'react-rum-demo' },
+  application: { name: 'react-rum-demo' },
   transport: { endpoint: 'https://rum-collector.example.com' },
-  plugins: {
+  tracking: {
+    view: { tracking: 'manual' },
     blankScreen: {
       rootSelector: '#root',
     },
@@ -89,10 +96,9 @@ export const RumRouteSync = () => {
   const matches = useMatches();
 
   useEffect(() => {
-    bkOT.setView({
+    bkOT.startView({
+      name: matches.at(-1)?.pathname || location.pathname,
       url: window.location.href,
-      urlPathGroup: matches.at(-1)?.pathname || location.pathname,
-      loadingType: 'route_change',
     });
   }, [location.pathname, matches]);
 
@@ -127,14 +133,16 @@ export const onLogout = () => {
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  app: { name: 'micro-frontend-host' },
+  application: { name: 'micro-frontend-host' },
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
 window.__BK_RUM__ = {
   reportAction: bkOT.reportAction,
   reportCustomEvent: bkOT.reportCustomEvent,
-  setView: bkOT.setView,
+  setViewName: bkOT.setViewName,
+  setViewLoadingTime: bkOT.setViewLoadingTime,
+  startView: bkOT.startView,
 };
 ```