@blueking/open-telemetry 0.0.14 → 0.0.16

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

@@ -1,320 +1,268 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 配置总览
+# 配置参考
 
-SDK 的配置入口是 `BkOTOptions`。推荐先完成 `app`、`transport`、`sampling`、`route`、`privacy` 五类基础配置，再按需打开插件。
-
-## 完整配置示例
+`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport` 必填；所有已启用信号必须能解析到有效 Endpoint。
 
 ```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
+import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
 
-const bkOT = new BkOpenTelemetry({
-  enabled: true,
-  autoStart: true,
-  debug: false,
-  app: {
-    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',
-    },
-  },
-  sampling: {
-    rate: 0.2,
-  },
-  route: {
-    getPathGroup: url => new URL(url).pathname.replace(/\/\d+/g, '/:id'),
-  },
-  privacy: {
-    redactUrl: url => url.replace(/([?&](token|bk_ticket)=)[^&]+/g, '$1***'),
-    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,
-  },
-});
+const options: BkOTOptions = {
+  application: { name: 'bk-monitor-web' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+};
 
-export default bkOT;
+const bkOT = new BkOpenTelemetry(options);
 ```
 
 ## 顶层配置
 
-| 配置 | 默认值 | 说明 |
-| --- | --- | --- |
-| `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`。 |
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `application` | `BkOTApplicationConfig` | 必填 | 应用 Resource 标识 |
+| `transport` | `BkOTTransportConfig` | 必填 | 三类 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
 
-- **Metric 上报间隔固定 60s**（`PeriodicExportingMetricReader`），暂不开放配置。
-- SDK 会向 resource 注入固定属性：`rum.provider=blueking`、`telemetry.sdk.language=webjs`，以及由 `app` 派生的 `service.name`、`service.version`、`deployment.environment.name`。
+| 字段 | 类型 | 默认 | Resource Attribute |
+| --- | --- | --- | --- |
+| `name` | `string` | 必填且非空 | `service.name` |
+| `environment` | `string` | `production` | `deployment.environment.name` |
+| `version` | `string` | 无 | `service.version` |
 
-示例：只在生产环境开启。
+SDK 还会固定写入 `rum.provider=blueking`、`rum.schema.version=1`、`telemetry.sdk.name=@blueking/open-telemetry` 和 `telemetry.sdk.language=webjs`。
+
+## transport
 
 ```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',
+transport: {
+  endpoint: 'https://collector.example.com',
+  token: 'report-token',
+  headers: { 'X-Tenant': 'blueking' },
+  signals: {
+    traces: {
+      endpoint: 'https://trace.example.com/v1/rum',
+      processor: 'batch',
+      batch: {
+        maxQueueSize: 2048,
+        maxExportBatchSize: 512,
+        scheduledDelayMillis: 5000,
+        exportTimeoutMillis: 30000,
+      },
+      timeoutMillis: 10_000,
+      concurrencyLimit: 10,
+    },
+    metrics: {
+      intervalMillis: 60_000,
+    },
+    logs: {},
   },
-});
+}
 ```
 
-## Instrumentation 配置
+### 根字段
 
-| 配置 | 默认值 | 说明 |
-| --- | --- | --- |
-| `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）注入范围。 |
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼默认信号路径 |
+| `token` | `string` | 无 | 生成 `Authorization: Bearer <token>` |
+| `headers` | `Record<string,string>` | 无 | 所有信号的公共 Header |
+| `signals` | `SignalExportersInputConfig` | 三类开启 | 单信号开关和覆盖项 |
 
-`propagateTraceHeaderUrls` 用于让 fetch/xhr 请求在调用后台 API 时带上 W3C `traceparent` 请求头，实现前后端 trace 串联。同源请求始终注入，该配置只用于在此基础上扩展跨域目标，取值支持：
+默认路径：Trace `/v1/rum`、Metric `/v1/metrics`、Log `/v1/logs`。单信号 `endpoint` 是完整 URL，不再拼路径。
 
-- `'all'`：所有请求都注入（含跨域，使用前确认隐私/CORS 影响）。
-- `string`：URL 包含该子串即注入，例如 `'api.example.com'`。
-- `RegExp`：URL 匹配该正则即注入。
-- 上述字符串/正则组成的数组：命中任意一个即注入。
-- `(url: string) => boolean`：完全自定义判断。
+Header 覆盖顺序为 `token` < 根 `headers` < 单信号 `headers`。同名字段由右侧配置覆盖。
 
-```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`），否则请求会被浏览器拦截。
+| 字段 | Trace | Metric | Log | SDK 默认 |
+| --- | --- | --- | --- | --- |
+| `endpoint` | 支持 | 支持 | 支持 | 回退根 Endpoint |
+| `headers` | 支持 | 支持 | 支持 | 回退根 Header |
+| `timeoutMillis` | 支持 | 支持 | 支持 | 交给 OTel exporter |
+| `concurrencyLimit` | 支持 | 支持 | 支持 | 交给 OTel exporter |
+| `processor` | `'batch' \| 'simple'` | — | — | `batch` |
+| `batch` | `BkOTBatchConfig` | — | — | 交给 `BatchSpanProcessor` |
+| `intervalMillis` | — | number | — | `60_000` |
 
-示例：关闭接口自动采集。
+`batch` 支持 `maxQueueSize`、`maxExportBatchSize`、`scheduledDelayMillis`、`exportTimeoutMillis`。未提供时使用 OpenTelemetry `BatchSpanProcessor` 默认值。
 
-```ts
-new BkOpenTelemetry({
-  instrumentations: {
-    fetch: false,
-    xhr: false,
-  },
-});
-```
+校验规则：
 
-## 插件默认开关
+- 三类信号不能全部为 `false`。
+- 每个已开启信号必须配置单独 Endpoint，或能回退到根 `transport.endpoint`。
+- 关闭 Trace 后不创建 Trace exporter/processor，不记录可导出的 Span，也不注入 `traceparent`。
+- 关闭 Metric 后不创建 reader；关闭 Log 后不创建 log processor，Request Body 配置也不会产生 Log。
 
-| 插件 | 默认状态 | 说明 |
-| --- | --- | --- |
-| `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 连接、消息、错误、关闭。 |
-
-示例：开启高成本插件。
+更多行为见[传输与采样](./transport-sampling.md)。
 
-```ts
-new BkOpenTelemetry({
-  plugins: {
-    longTask: {
-      threshold: 80,
-    },
-    httpBody: {
-      maxBodySize: 4096,
-      redact: ({ body, type }) => (type === 'request' ? '[redacted request body]' : body),
-    },
-    websocket: true,
-  },
-});
-```
+## session
 
-# 上报与采样
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `sampleRate` | `number` | `1` | Session 确定性采样；有限数值限制到 `0..1`，非有限值回退 `1` |
+| `storageKey` | `string` | 按应用名和 Endpoint host hash | Session localStorage key |
 
-SDK 使用 OTLP HTTP exporter 分别上报 traces、metrics、logs。默认 endpoint 是 `http://localhost:4318`，会自动拼接 `/v1/rum`、`/v1/metrics`、`/v1/logs`。
+Session 固定为 15 分钟无活动过期、4 小时最长生命周期，不开放超时配置。localStorage 不可用时退回进程内存。
 
-## 统一 endpoint
+## tracking.view
 
-```ts
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-    token: 'report-token',
-  },
-});
-```
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `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 活动窗口 |
 
-实际使用的上报地址为：
+URL matcher 支持字符串包含、`RegExp` 或 `(url) => boolean`。字符串使用 `url.includes(matcher)`，不等于 origin 精确匹配；安全白名单应使用 URL-aware 函数或带边界的正则。自动 View 只对 pathname 和非页内锚点 hash path 的变化切换，query-only 变化不切换。
 
-- traces：`https://rum-collector.example.com/v1/rum`
-- metrics：`https://rum-collector.example.com/v1/metrics`
-- logs：`https://rum-collector.example.com/v1/logs`
+## tracking.request
 
-## 分信号 endpoint
+`request` 可设为 `false` 完全关闭 Fetch/XHR patch；`true` 或 `{}` 使用默认配置。
 
-如果 traces、metrics、logs 由不同网关接收，可以使用 `transport.signals`。
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `excludedUrls` | matcher 或 matcher[] | 无 | 命中后不采集、不注入、不计入页面活动 |
+| `allowedTracingUrls` | matcher 或 matcher[] | 无 | W3C Trace Context 显式白名单；同源请求也必须命中，推荐 URL-aware 函数 |
+| `beforeSend` | `(event, context) => boolean \| void` | 无 | 修改请求属性；返回 `false` 丢弃 Span，并跳过该请求的 Body Log |
+| `body` | `BkOTRequestBodyConfig` | 关闭 | 请求/响应 Body Log |
 
-```ts
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-    headers: {
-      'x-bk-app-code': 'bk-monitor',
-    },
-    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',
-        },
-      },
-    },
-  },
-});
-```
+Request Body：
 
-自定义的 `signals.endpoints.*`（或单信号 `endpoint`）会原样使用，不再基于外层 `endpoint` 拼接 `/v1/...`。
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `capture` | `'errors' \| 'all'` | `errors` | 错误包括状态未知、0 或 `>=400` |
+| `maxSize` | `number` | `10 * 1024` | 每个最终 Body 的最大字符数；无效值回退默认 |
+| `allowedContentTypes` | `(string \| RegExp)[]` | text、json、urlencoded、graphql | Response 必须命中；无 Content-Type 的 Request 允许读取 |
+| `redact` | `(payload) => string \| undefined` | 必填 | 返回脱敏文本；`undefined` 跳过当前 Body |
 
-`transport.token` 会生成默认 `Authorization: Bearer <token>`，显式配置的 `headers` 会继续合并进去。
+默认不采集 Body。Body 只在 Log 信号开启时生效，不支持 FormData、ArrayBuffer 等不可安全文本化的内容。
 
-## 避免自循环采集
+## tracking 内置能力
 
-SDK 内置 `FilteringSpanProcessor`，会过滤指向自身 OTLP endpoint 的 span，避免上报请求本身再次被 fetch/xhr instrumentation 采集。
+| 字段 | 类型 | 默认 | 参数 |
+| --- | --- | --- | --- |
+| `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`、`warningThreshold=100` ms |
+| `websocket` | `boolean` | `false` | 无 |
+| `cspViolation` | `boolean` | `false` | 无，内置同指纹 60 秒最多 5 条 |
 
-示例：自定义 Collector 地址时无需手动忽略自身上报。
+Blank Screen：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `rootSelector` | `body` | 应用挂载根节点 |
+| `threshold` | `0.8` | 九点采样的空白比例，限制到 `0..1` |
+| `checkDelay` | `1000` ms | 页面活动稳定后的首次检查延迟 |
+| `confirmationDelay` | `200` ms | 两次候选白屏的确认间隔 |
+| `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会替换内置数组 |
+
+Action：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `actionNameAttribute` | `data-bk-action-name` | 向上查找的显式动作名属性 |
+| `maxDuration` | `10_000` ms | 单次 Action 最大活动窗口 |
+| `nameCollection` | `explicit` | 默认只取显式属性，否则退回标签名；`text` 才读取可访问名称/DOM 文本 |
+
+Device：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `persistentId` | `false` | `false` 时 ID 只在当前实例稳定；`true` 写 localStorage |
+| `storageKey` | 按应用名 hash | 仅持久 ID 使用 |
+
+## tracking.beforeSend
 
 ```ts
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://rum-collector.example.com/otlp',
+tracking: {
+  beforeSend(event) {
+    delete event.attributes['debug.payload'];
+    return event.name !== 'custom.ignore-me';
   },
-  instrumentations: {
-    fetch: true,
-    xhr: true,
-  },
-});
+}
 ```
 
-## 同源 traceparent 传播
+该 Hook 在 Span/Log 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning。它不处理 Metric；请求专属逻辑优先使用 `tracking.request.beforeSend`。
 
-fetch/xhr instrumentation 会给符合条件的同源请求注入 W3C `traceparent`，用于打通前后端 trace。跨域请求是否能传播还取决于服务端 CORS 是否允许该 header。
+## context
 
-示例：前端请求同源 API。
+| 字段 | 类型 | 默认 | 作用 |
+| --- | --- | --- | --- |
+| `user.id` | `string` | 无 | SDK 原样写入 `user.id` |
+| `attributes.page` | `() => Attributes` | host/path | 页面、请求、错误、Action 等事件属性 |
+| `attributes.metric` | `() => Attributes` | `{}` | 内置 Metric 的低基数自定义维度 |
+| `attributes.error` | `() => Attributes` | `{}` | Error Span 附加属性 |
+| `attributes.custom` | `() => Attributes` | `{}` | `reportCustomEvent()` 附加属性 |
 
-```ts
-await fetch('/api/orders/202605270001', {
-  method: 'GET',
-});
-```
+自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。Metric Hook 禁止放用户 ID、订单 ID、完整 URL 等高基数字段。
 
-## 会话级 sticky 采样
+## privacy
 
-`sampling.rate` 范围是 `0` 到 `1`。SDK 会将采样结果保存在 session 维度，保证同一会话内行为一致。
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
+| `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | SDK 创建 Span/Log 和内置插件属性脱敏 |
 
-```ts
-new BkOpenTelemetry({
-  sampling: {
-    rate: 0.05,
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-```
+第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
 
-需要注意：
+## extensions
 
-- `rate: 1` 表示全量上报。
-- `rate: 0` 表示 RUM 插件和手动事件都不上报。
-- 未命中采样时，主动产生数据的 RUM 插件不会启动。
-- 调试时建议临时设置 `rate: 1` 和 `debug: true`。
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `plugins` | `BkOTPlugin[]` | `[]` | 在内置插件后初始化 |
+| `instrumentations` | `Instrumentation[]` | `[]` | 插件完成后注册到 SDK provider |
 
-## Batch 与 Simple Processor
+也可以在 `start()` 前调用 `use()` / `useInstrumentation()`。需要动态注册时设置 `autoStart: false`；启动后调用会抛错。
 
-默认使用 batch 处理器，适合生产环境。调试时可以用 simple 处理器减少等待。
+## 完整配置骨架
 
 ```ts
 new BkOpenTelemetry({
-  debug: true,
-  spanProcessor: 'simple',
+  application: { name: 'demo', environment: 'production', version: '1.0.0' },
   transport: {
-    endpoint: 'http://localhost:4318',
+    endpoint: 'https://collector.example.com',
+    token: 'token',
+    headers: {},
+    signals: {
+      traces: { processor: 'batch', batch: {} },
+      metrics: { intervalMillis: 60_000 },
+      logs: {},
+    },
   },
-});
-```
-
-批量参数可以通过 `spanBatch` 调整。
-
-```ts
-new BkOpenTelemetry({
-  spanProcessor: 'batch',
-  spanBatch: {
-    maxQueueSize: 2048,
-    maxExportBatchSize: 256,
-    scheduledDelayMillis: 5000,
-    exportTimeoutMillis: 30000,
+  session: { sampleRate: 1 },
+  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,
   },
+  context: { attributes: {} },
+  privacy: { trackingConsent: 'granted' },
+  extensions: { plugins: [], instrumentations: [] },
+  enabled: true,
+  autoStart: true,
+  debug: false,
 });
 ```

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',
@@ -53,7 +54,11 @@ await bkOT.start();
 
 `init(context)` 中可以访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()`、`getRuntimeAttributes()` 等能力。
 
+优先使用 `context.startSpan()` 和 `context.emitLog()`：它们会合并事件发生时的运行时上下文并应用 SDK 脱敏。直接调用 `context.logger.emit()` 的 Log 不会自动获得这些能力，可能因缺少有效 Session/View 被导出过滤器丢弃。
+
 ```ts
+let teardownVisibility = () => {};
+
 const visibilityPlugin = createPlugin({
   name: 'visibility-change',
   init(context) {
@@ -68,8 +73,10 @@ const visibilityPlugin = createPlugin({
     };
 
     document.addEventListener('visibilitychange', onVisibilityChange);
-
-    return undefined;
+    teardownVisibility = () => document.removeEventListener('visibilitychange', onVisibilityChange);
+  },
+  shutdown() {
+    teardownVisibility();
   },
 });
 ```
@@ -125,18 +132,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 +152,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 +164,10 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 await bkOT.start();
 ```
 
-> 与受采样影响的 RUM 插件不同，instrumentation 只要 SDK 启用（`enabled !== false`）就会注册，不受 `sampling.rate` 影响。
+> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束；第三方 instrumentation Metric 因没有公开采样 helper，默认会被过滤。
+
+## 自定义 Metric 注意事项
+
+内置 Metric 会主动带上内部采样标记与低基数 `view.url_path_group`。当前包没有导出稳定的自定义 Metric helper 或采样属性；自定义插件直接调用 `context.meter` 创建的数据点默认无法通过 `FilteringMetricExporter`。不要依赖内部 `bk.rum.sampled` 字段，也不要把 `context.getRuntimeAttributes()` 整体复制到 Metric attributes，否则还会把唯一的 `session.id`、`view.id`、`action.id` 变成高基数 labels。
+
+如果需求是记录一次具体业务行为，使用 Span 或 Log。确实需要自定义 Metric 时，应先为 SDK 设计并公开低基数、采样安全的 Metric API，而不是绕过当前过滤约束。

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 插件、自定义事件错误 |
+| `error` | 浏览器与体验错误 | error 插件、blankScreen 插件、cspViolation 插件 |
 | `longtask` | 长任务 | longTask 插件 |
 | `action` | 用户动作 | action 插件、reportAction |
-| `route` | 路由切换 | pageView 插件（SPA 路由）、routeTiming 插件 |
-| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件 |
+| `route` | 路由切换 | View 管理器（SPA/手动 View） |
+| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件；`reportCustomEvent({ error })` 仍属于此类型 |
 
-> 每种 span 的具体 span 名（如 `browser.web_vital`、`browser.route_change`）、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
+> 每种 span 的具体 span 名、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
 
 示例：自定义业务事件归一为 `custom`。
 
@@ -55,7 +54,9 @@ span.end();
 - `timeout`
 - `abort`
 
-HTTP span 会根据状态码推导结果：`408`、`504` 为 timeout，`>= 400` 为 error，其余为 success。
+请求 Resource Span 会根据状态码推导结果：`408`、`504` 为 timeout，`>= 400` 为 error，其余为 success。
+
+`reportCustomEvent({ error })` 会设置 `result=error` 和 OpenTelemetry Span Status ERROR，但不会把 `span_type` 从 `custom` 改为 `error`。`span_type` 描述事件类别，`result` 描述结果，两者不要混用。
 
 ```ts
 bkOT.reportCustomEvent({
@@ -89,8 +90,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 +121,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。