@blueking/open-telemetry 0.0.22-beta.1 → 0.0.23

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

@@ -2,226 +2,301 @@
 
 # 配置参考
 
-`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport.endpoint` 必填。
+本文按 `BkOTOptions` 的当前 TypeScript 定义列出全部公开配置、默认值和约束。源码只校验真正必填的字段；浏览器兼容、隐私与基数治理仍需要接入方负责。
 
-```ts
-import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
-
-const options: BkOTOptions = {
-  application: { name: 'bk-monitor-web' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-};
+## 完整结构
 
-const bkOT = new BkOpenTelemetry(options);
+```ts
+new BkOpenTelemetry({
+  application: { name, environment?, version? },
+  transport: {
+    endpoint,
+    token?, headers?, processor?, batch?, timeoutMillis?, concurrencyLimit?,
+  },
+  autoStart?,
+  enabled?,
+  debug?,
+  session: { sampleRate?, storageKey? },
+  context: { user?, attributes? },
+  privacy: { trackingConsent?, redactUrl?, redactAttributes? },
+  tracking: {
+    request?, resource?, error?, webVitals?, action?, blankScreen?, device?,
+    longTask?, websocket?, cspViolation?, view?, beforeSend?,
+  },
+  extensions: { plugins?, instrumentations? },
+});
 ```
 
 ## 顶层配置
 
-| 字段 | 类型 | 默认 | 说明 |
+| 配置 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `application` | `BkOTApplicationConfig` | 必填 | 应用 Resource 标识 |
-| `transport` | `BkOTTransportConfig` | 必填 | 单一 RUM OTLP HTTP 导出链路 |
-| `session` | `BkOTSessionConfig` | `{ sampleRate: 1 }` | Session 存储和确定性采样 |
-| `tracking` | `BkOTTrackingConfig` | `{}` | 内置采集、View 与事件 Hook |
-| `context` | `BkOTContextConfig` | 无 | 初始用户与公共属性 Hook |
-| `privacy` | `BkOTPrivacyConfig` | Consent 已授权、默认 URL 脱敏 | 授权、URL 和属性脱敏 |
-| `extensions` | `BkOTExtensionsConfig` | 空数组 | 自定义 RUM 插件与 OTel instrumentation |
-| `enabled` | `boolean` | `true` | `false` 时 `start()` 不安装采集能力 |
-| `autoStart` | `boolean` | `true` | 构造后异步启动 |
-| `debug` | `boolean` | `false` | 输出 exporter 数据和可诊断 warning |
+| `application` | `BkOTApplicationConfig` | 必填 | 应用 Resource 信息 |
+| `transport` | `BkOTTransportConfig` | 必填 | 唯一 Trace 上报通道 |
+| `autoStart` | `boolean` | `true` | 构造后异步调用 `start()` |
+| `enabled` | `boolean` | `true` | `false` 时不启动采集；Provider 仍会构造，便于公开 API 形态稳定 |
+| `debug` | `boolean` | `false` | 打印待导出 Span，并显示部分插件初始化/丢弃警告 |
+| `session` | `BkOTSessionConfig` | `{ sampleRate: 1 }` | 会话采样和存储 key |
+| `context` | `BkOTContextConfig` | 无 | 初始用户及按事件读取的自定义属性 |
+| `privacy` | `BkOTPrivacyConfig` | 已授权、默认 URL 清洗 | Consent 与脱敏 Hook |
+| `tracking` | `BkOTTrackingConfig` | 见能力矩阵 | 内置采集开关和参数 |
+| `extensions` | `BkOTExtensionsConfig` | 空数组 | 自定义 RUM 插件和 OTel instrumentation |
+
+如果要调用 `use()` 或 `useInstrumentation()`，必须设置 `autoStart: false`，先注册再 `await start()`。
+
+`enabled: false` 和初始 `trackingConsent: 'not-granted'` 都不阻止构造阶段创建 Provider/Resource。默认 Device 开启时，稳定 Device Resource 快照也会在构造时读取；它们只阻止后续插件采集和 Span 发送。对“授权前不能读取浏览器设备信息”有严格要求时，应延后整个构造调用。
 
 ## application
 
-| 字段 | 类型 | 默认 | Resource Attribute |
+| 配置 | 类型 | 默认 | 上报位置 |
 | --- | --- | --- | --- |
-| `name` | `string` | 必填且非空 | `service.name` |
-| `environment` | `string` | `production` | `deployment.environment.name` |
-| `version` | `string` | 无 | `service.version` |
+| `name` | `string` | 必填、非空 | Resource `service.name`，也参与 Session 稳定采样 |
+| `environment` | `string` | `'production'` | Resource `deployment.environment.name` |
+| `version` | `string` | 不发送 | Resource `service.version` |
 
-SDK 还会固定写入 `rum.schema.version=2`、`telemetry.sdk.name=@blueking/open-telemetry`、`telemetry.sdk.language=webjs` 和当前包版本 `telemetry.sdk.version`。默认启用 `tracking.device` 时，浏览器、OS 和稳定的硬件能力也会写入 Resource。
+`name` 应稳定且低基数，不要包含用户、构建时间或路由。`version` 推荐使用可以定位前端构建产物的版本号或 commit 标识。
 
 ## transport
 
+| 配置 | 类型 | 默认 | 说明 |
+| --- | --- | ---: | --- |
+| `endpoint` | `string` | 必填、非空 | 上报根地址；去除末尾 `/` 后追加 `/v1/rum` |
+| `token` | `string` | 无 | 生成默认 `Authorization: Bearer <token>` |
+| `headers` | `Record<string, string>` | 无 | 自定义头；同名时覆盖 token 生成的头 |
+| `processor` | `'batch' \| 'simple'` | `'batch'` | 批量或逐 Span 导出 |
+| `batch` | `BkOTBatchConfig` | OTel 默认值 | 仅 batch 模式生效 |
+| `timeoutMillis` | `number` | `10000` | exporter 请求及重试的总期限，必须大于 0 |
+| `concurrencyLimit` | `number` | `30` | exporter 并发 Promise 上限 |
+
+`batch` 子项：
+
+| 配置 | 默认 | 说明 |
+| --- | ---: | --- |
+| `maxQueueSize` | `2048` | 队列满后丢弃新的已结束 Span |
+| `maxExportBatchSize` | `512` | 单批 Span 上限，不能有效超过 queue size |
+| `scheduledDelayMillis` | `5000` | 批量调度等待 |
+| `exportTimeoutMillis` | `30000` | processor 等待 export 的上限 |
+
+完整协议与重试语义见[上报协议、批处理与采样](./transport-sampling.md)。
+
+## session
+
+| 配置 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `sampleRate` | `number` | `1` | 0–1 的 Session 级确定性采样率；越界会截断 |
+| `storageKey` | `string` | 按应用和 endpoint host 生成 | 跨 Tab 共享 Session 状态的 localStorage key |
+
+15 分钟无活动和 4 小时最大生命周期是当前固定行为，不是公开配置项。localStorage 不可用时退化为页面进程内存，无法跨页面/Tab 共享。详见[Session、用户与设备上下文](./session-context.md)。
+
+## context
+
 ```ts
-transport: {
-  endpoint: 'https://collector.example.com',
-  token: 'report-token',
-  headers: { 'X-Tenant': 'blueking' },
-  processor: 'batch',
-  batch: {
-    maxQueueSize: 2048,
-    maxExportBatchSize: 512,
-    scheduledDelayMillis: 5000,
-    exportTimeoutMillis: 30000,
+context: {
+  user: { id: 'user-001' },
+  attributes: {
+    page: () => ({ 'biz.module': 'order' }),
+    error: () => ({ 'biz.release_channel': 'gray' }),
+    custom: () => ({ 'biz.tenant': 'tenant-a' }),
   },
-  timeoutMillis: 10_000,
-  concurrencyLimit: 10,
 }
 ```
 
-### 根字段
+| 配置 | 调用时机 | 合并到 |
+| --- | --- | --- |
+| `user.id` | 构造时，之后可用 `setUser()` 更新 | 运行时 `user.id` |
+| `attributes.page()` | 插件创建相关 Span、过滤层补属性时 | 页面/请求/事件 Span，具体取决于调用插件 |
+| `attributes.error()` | 创建错误 Span 时 | Error Span |
+| `attributes.custom()` | `reportCustomEvent()` 时 | Custom Span |
 
-| 字段 | 类型 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼 `/v1/rum` |
-| `token` | `string` | 无 | 生成 `Authorization: Bearer <token>` |
-| `headers` | `Record<string,string>` | 无 | RUM 请求 Header |
-| `timeoutMillis` | `number` | OTel 默认 | Exporter 超时 |
-| `concurrencyLimit` | `number` | OTel 默认 | Exporter 并发数 |
-| `processor` | `'batch' \| 'simple'` | `batch` | Span Processor 模式 |
-| `batch` | `BkOTBatchConfig` | OTel 默认 | BatchSpanProcessor 参数 |
+Hook 每次调用都应返回新的普通对象，且不能抛异常。SDK 不 hash、不改写 `user.id`。如果 ID 敏感，接入方必须在传入前完成不可逆处理。
 
-`batch` 支持 `maxQueueSize`、`maxExportBatchSize`、`scheduledDelayMillis`、`exportTimeoutMillis`。未提供时使用 OpenTelemetry `BatchSpanProcessor` 默认值。
+未配置 `attributes.page` 时默认返回原始 `location.host` 和 `location.pathname` 对应的 `rum.page.host/path`。自定义 Hook 会完全替换默认值；`rum.page.path` 不经过 `redactUrl` 或 `getPathGroup`，动态路径应在该 Hook 或 `redactAttributes` 中治理。
 
-SDK 不提供 Logs/Metrics 开关或 Provider，所有 RUM 原始事件只走 `/v1/rum`。
+属性合并优先级不是全局统一的：各插件会先组合公共字段、Hook 字段和事件字段，`startSpan()` 再用运行时上下文作为底层。精确字段请以对应能力页和[RUM 数据模型](./data-model.md)为准。
 
-更多行为见[传输与采样](./transport-sampling.md)。
+## privacy
 
-## session
+| 配置 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `trackingConsent` | `'granted' \| 'not-granted'` | `'granted'` | 初始化时是否安装采集插件 |
+| `redactUrl` | `(url: string) => string` | 去除认证信息、query、fragment | 所有按规范写入的 URL 在入 Span 前清洗 |
+| `redactAttributes` | `(attributes) => attributes` | 原样返回 | 插件 emit 和 Resource 构造时的统一属性过滤 |
 
-| 字段 | 类型 | 默认 | 说明 |
+`redactAttributes` 必须返回合法 OpenTelemetry `Attributes`。删除字段时返回新对象最安全。Consent 与各 Hook 的覆盖边界见[隐私、Consent 与字段治理](./privacy.md)。
+
+## tracking 默认开关
+
+| 配置 | 默认 | 类型/参数 | 作用 |
 | --- | --- | --- | --- |
-| `sampleRate` | `number` | `1` | Session 确定性采样；有限数值限制到 `0..1`，非有限值回退 `1` |
-| `storageKey` | `string` | 按应用名和 Endpoint host hash | Session localStorage key |
+| `request` | 开 | `boolean \| BkOTRequestConfig` | Fetch/XHR、可选 traceparent |
+| `resource` | 开 | `boolean` | 静态资源 PerformanceResourceTiming |
+| `error` | 开 | `boolean` | runtime、Promise、资源加载错误 |
+| `webVitals` | 开 | `boolean` | CLS/FCP/INP/LCP/TTFB |
+| `action` | 开 | `boolean \| BkOTActionPluginOptions` | 点击 Action 与挫败信号 |
+| `blankScreen` | 开 | `boolean \| BkOTBlankScreenPluginOptions` | 白屏检测 |
+| `device` | 开 | `boolean \| BkOTDevicePluginOptions` | Resource 与运行时设备属性 |
+| `longTask` | 关 | `boolean \| BkOTLongTaskPluginOptions` | LoAF/Long Task |
+| `websocket` | 关 | `boolean` | WebSocket 连接生命周期 |
+| `cspViolation` | 关 | `boolean` | CSP violation |
+| `view` | 自动、loading 开 | `BkOTViewConfig` | View 边界、命名和 loading time |
+| `beforeSend` | 无 | `(event) => boolean \| void` | 所有结束 Span 的最终业务过滤 |
+
+Session、Activity 和 Page View 上下文是关联模型的基础，不提供统一的 `tracking.session: false` 或 `tracking.activity: false` 开关。
+
+## request
 
-Session 固定为 15 分钟无活动过期、4 小时最长生命周期，不开放超时配置。localStorage 不可用时退回进程内存。
+```ts
+tracking: {
+  request: {
+    excludedUrls: [/\/health(?:\?|$)/],
+    allowedTracingUrls: [url => new URL(url, location.href).origin === 'https://api.example.com'],
+    beforeSend(event, context) {
+      if (event.resource.outcome.type === 'response' && event.resource.outcome.statusCode === 404) return false;
+      event.attributes['biz.api_group'] = 'order';
+    },
+  },
+}
+```
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `excludedUrls` | 无 | 匹配后不建请求 Span、不注入 trace header，也不计入 View/Action 活动 |
+| `allowedTracingUrls` | 无 | 只有明确匹配的 URL 才注入 W3C `traceparent`，同源也不例外 |
+| `beforeSend` | 无 | 只作用于 Fetch/XHR 请求事件；`event.resource.outcome` 区分 response/abort/timeout/network_error，返回 `false` 丢弃请求 Span |
+
+URL matcher 支持 string、RegExp 或函数：
+
+- string：URL 包含该字符串即匹配；
+- RegExp：对完整 URL 执行 `test`，SDK 会重置 `lastIndex`；
+- function：返回 true 即匹配；
+- 单个 matcher 或数组均可。
 
-## tracking.view
+请求插件不采集请求体、响应体和常规业务 header。详见[网络请求、资源与链路传播](./network.md)。
 
-| 字段 | 类型 | 默认 | 说明 |
+## view
+
+| 配置 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `tracking` | `'auto' \| 'manual'` | `auto` | 自动观察 History/hash，或由业务调用 `startView()` |
-| `loadingTime` | `boolean` | `true` | 计算 View 页面活动稳定耗时 |
-| `getPathGroup` | `(url) => string \| undefined` | URL pathname | 返回低基数 `view.url_path_group` |
-| `excludedActivityUrls` | matcher 或 matcher[] | 无 | 命中请求/资源不延长 View/Action 活动窗口 |
+| `tracking` | `'auto' \| 'manual'` | `'auto'` | 自动监听 History/hash，或只接受 `startView()` |
+| `loadingTime` | `boolean` | `true` | 自动计算初始加载和路由稳定耗时 |
+| `getPathGroup` | `(url) => string \| undefined` | URL pathname | 生成低基数 `view.url_path_group` |
+| `excludedActivityUrls` | URL matcher | 无 | 不让长轮询/流式/埋点请求延长 View loading time |
+
+`getPathGroup` 返回 `undefined` 时回退到 pathname。自动路由不会因 query-only 变化创建新 View；hash 变化会创建，但纯锚点语义由业务自行决定是否改用 manual。详见[View、路由与页面加载](./views-routing.md)。
 
-URL matcher 支持字符串包含、`RegExp` 或 `(url) => boolean`。字符串使用 `url.includes(matcher)`，不等于 origin 精确匹配；安全白名单应使用 URL-aware 函数或带边界的正则。自动 View 只对 pathname 和非页内锚点 hash path 的变化切换，query-only 变化不切换。
+## action
+
+| 配置 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `actionNameAttribute` | `string` | `'data-bk-action-name'` | 从目标或祖先读取显式名称 |
+| `maxDuration` | `number` | `10000` | Action 最长持续时间，非法或非正数回退默认 |
+| `nameCollection` | `'explicit' \| 'text'` | `'explicit'` | 是否允许从可访问名称/DOM 文本推导名称 |
 
-## tracking.request
+`text` 可能采集用户界面文本，开启前必须做隐私评审。详见[用户操作与挫败信号](./actions.md)。
 
-`request` 可设为 `false` 完全关闭 Fetch/XHR patch；`true` 或 `{}` 使用默认配置。
+## blankScreen
 
-| 字段 | 类型 | 默认 | 说明 |
+| 配置 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `excludedUrls` | matcher 或 matcher[] | 无 | 命中后不采集、不注入、不计入页面活动 |
-| `allowedTracingUrls` | matcher 或 matcher[] | 无 | W3C Trace Context 显式白名单；同源请求也必须命中，推荐 URL-aware 函数 |
-| `beforeSend` | `(event, context) => boolean \| void` | 无 | 修改请求属性；返回 `false` 丢弃 Span |
+| `rootSelector` | `string` | `'body'` | 应用根节点；不存在会成为白屏候选 |
+| `threshold` | `number` | `0.8` | 九点采样中的空白比例阈值，截断至 0–1 |
+| `checkDelay` | `number` | `1000` | 页面活动稳定后的首检延迟 |
+| `confirmationDelay` | `number` | `200` | 两次白屏结果的确认间隔 |
+| `ignoreSelectors` | `string[]` | 内置 loading/skeleton 列表 | 追加忽略元素，不替换内置列表 |
 
-SDK 不读取或上报请求/响应 Body。
+SPA 应将 `rootSelector` 指向真实挂载节点。详见[白屏检测](./blank-screen.md)。
 
-## tracking 内置能力
+## device
 
-| 字段 | 类型 | 默认 | 参数 |
+| 配置 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `resource` | `boolean` | `true` | 无；`false` 只关闭静态资源 Span，Resource Observer 仍服务请求 timing/活动 |
-| `error` | `boolean \| BkOTErrorPluginOptions` | `true` | `windowMs=60_000`、`maxPerWindow=5` |
-| `webVitals` | `boolean` | `true` | 无 |
-| `blankScreen` | `boolean \| BkOTBlankScreenPluginOptions` | `true` | 见下表 |
-| `device` | `boolean \| BkOTDevicePluginOptions` | `true` | 见下表 |
-| `action` | `boolean \| BkOTActionPluginOptions` | `true` | 见下表 |
-| `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50` ms |
-| `websocket` | `boolean` | `false` | 无 |
-| `cspViolation` | `boolean` | `false` | 无，内置同指纹 60 秒最多 5 条 |
-
-Blank Screen：
-
-| 字段 | 默认 | 说明 |
-| --- | --- | --- |
-| `rootSelector` | `body` | 应用挂载根节点 |
-| `threshold` | `0.8` | 九点采样的空白比例，限制到 `0..1` |
-| `checkDelay` | `1000` ms | 页面活动稳定后的首次检查延迟 |
-| `confirmationDelay` | `200` ms | 两次候选白屏的确认间隔 |
-| `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会替换内置数组 |
+| `persistentId` | `boolean` | `false` | 是否把匿名设备 ID 持久化到 localStorage |
+| `storageKey` | `string` | `BK_RUM_DEVICE_ID_<应用 hash>` | 持久设备 ID 的 key |
 
-Action：
+`persistentId: false` 时，每次 Device 插件初始化都会创建新的设备 ID，只在当前采集周期内稳定；撤销再授予 Consent 会重新初始化插件并换 ID。`tracking.device: false` 还会阻止浏览器/OS/硬件 Resource 属性生成。详见[Session、用户与设备上下文](./session-context.md)。
 
-| 字段 | 默认 | 说明 |
-| --- | --- | --- |
-| `actionNameAttribute` | `data-bk-action-name` | 向上查找的显式动作名属性 |
-| `maxDuration` | `10_000` ms | 单次 Action 最大活动窗口 |
-| `nameCollection` | `explicit` | 默认只取显式属性，否则退回标签名；`text` 才读取可访问名称/DOM 文本 |
+## longTask
 
-Device：
+| 配置 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `threshold` | `number` | `50` | 最低 duration，非法或负数回退默认 |
 
-| 字段 | 默认 | 说明 |
-| --- | --- | --- |
-| `persistentId` | `false` | `false` 时 ID 只在当前实例稳定；`true` 写 localStorage |
-| `storageKey` | 按应用名 hash | 仅持久 ID 使用 |
+优先使用 Long Animation Frame API，不支持时回退 Long Tasks API；两者的可用字段不同。详见[性能体验与长任务](./performance.md)。
 
 ## tracking.beforeSend
 
 ```ts
 tracking: {
   beforeSend(event) {
-    delete event.attributes['debug.payload'];
-    return event.name !== 'custom.ignore-me';
+    if (event.name === 'browser.resource' && event.attributes['url.full']?.includes('/noise')) {
+      return false;
+    }
+    event.attributes['biz.reviewed'] = true;
   },
 }
 ```
 
-该 Hook 在 Span 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning；请求专属逻辑优先使用 `tracking.request.beforeSend`。
-
-## context
+事件结构：
 
-| 字段 | 类型 | 默认 | 作用 |
-| --- | --- | --- | --- |
-| `user.id` | `string` | 无 | SDK 原样写入 `user.id` |
-| `attributes.page` | `() => Attributes` | host/path | 页面、请求、错误、Action 等事件属性 |
-| `attributes.error` | `() => Attributes` | `{}` | Error Span 附加属性 |
-| `attributes.custom` | `() => Attributes` | `{}` | `reportCustomEvent()` 附加属性 |
-
-自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。
-
-## privacy
+```ts
+interface BkOTBeforeSendEvent {
+  signal: 'span';
+  name: string;
+  attributes: Record<string, unknown>;
+}
+```
 
-| 字段 | 类型 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
-| `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
-| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span 和内置插件属性脱敏 |
+该 Hook 在 Span 结束、导出过滤阶段执行：
 
-第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
+- 返回 `false` 丢弃；返回 `void` 保留；
+- 可原地修改 `event.attributes`；
+- 只暴露名字和属性，不暴露 Span event、时间、status、trace ID；
+- 在 Span 已完成常规脱敏之后执行；该 Hook 新增或改写的字段不会再自动经过 `redactAttributes`；
+- Hook 抛异常时 SDK 保留 Span 并继续发送，`debug: true` 时打印 warning；业务仍应在 Hook 内避免可能失败或高开销的逻辑。
 
 ## extensions
 
-| 字段 | 类型 | 默认 | 说明 |
+| 配置 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `plugins` | `BkOTPlugin[]` | `[]` | 在内置插件后初始化 |
-| `instrumentations` | `Instrumentation[]` | `[]` | 插件完成后注册到 SDK provider |
+| `plugins` | `BkOTPlugin[]` | `[]` | 使用 SDK RUM runtime context 的插件 |
+| `instrumentations` | `Instrumentation[]` | `[]` | 绑定 SDK 私有 WebTracerProvider 的 OTel instrumentation |
 
-也可以在 `start()` 前调用 `use()` / `useInstrumentation()`。需要动态注册时设置 `autoStart: false`；启动后调用会抛错。
+两类扩展都在 SDK 获得 Consent 后启动，并在撤销 Consent/shutdown 时关闭。使用方法见[插件与 OpenTelemetry 扩展](./extensions.md)。
 
-## 完整配置骨架
+## 可复制的生产模板
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo', environment: 'production', version: '1.0.0' },
+const rum = new BkOpenTelemetry({
+  application: {
+    name: 'order-center',
+    environment: 'production',
+    version: '2026.07.21',
+  },
   transport: {
-    endpoint: 'https://collector.example.com',
-    token: 'token',
-    headers: {},
+    endpoint: 'https://rum.example.com',
+    token: 'limited-browser-write-token',
     processor: 'batch',
-    batch: {},
   },
-  session: { sampleRate: 1 },
+  session: { sampleRate: 0.2 },
   tracking: {
-    view: { tracking: 'auto', loadingTime: true },
-    request: true,
-    resource: true,
-    error: true,
-    webVitals: true,
-    blankScreen: true,
-    device: true,
-    action: true,
-    longTask: false,
-    websocket: false,
-    cspViolation: false,
+    view: {
+      getPathGroup(url) {
+        return new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id');
+      },
+      excludedActivityUrls: [/\/events\/stream(?:\?|$)/],
+    },
+    request: {
+      excludedUrls: [/\/health(?:\?|$)/],
+      allowedTracingUrls: [url => new URL(url, location.href).origin === 'https://api.example.com'],
+    },
+    blankScreen: { rootSelector: '#app' },
+  },
+  privacy: {
+    redactAttributes(attributes) {
+      const next = { ...attributes };
+      delete next['biz.secret'];
+      return next;
+    },
   },
-  context: { attributes: {} },
-  privacy: { trackingConsent: 'granted' },
-  extensions: { plugins: [], instrumentations: [] },
-  enabled: true,
-  autoStart: true,
-  debug: false,
 });
 ```