@blueking/open-telemetry 0.0.15 → 0.0.17

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

@@ -1,137 +1,191 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 配置总览
+# 配置参考
 
-SDK 入口按职责分为 `application`、`transport`、`session`、`tracking`、`context`、`privacy`、`extensions`。`application.name` 与 `transport` 必填；根 `transport.endpoint` 可由所有已开启信号的独立 endpoint 取代。
+`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport` 必填；所有已启用信号必须能解析到有效 Endpoint。
 
 ```ts
-const bkOT = new BkOpenTelemetry({
-  application: {
-    name: 'bk-monitor-web',
-    environment: 'production',
-    version: '1.4.2',
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-    token: 'report-token',
-    signals: {
-      traces: { processor: 'batch', batch: { maxQueueSize: 2048 } },
-      metrics: { intervalMillis: 60_000 },
-    },
-  },
-  session: {
-    sampleRate: 0.2,
-  },
-  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: {
-    trackingConsent: 'granted',
-    redactAttributes: attributes => attributes,
-  },
-  extensions: {
-    plugins: [],
-    instrumentations: [],
-  },
-});
+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);
 ```
 
 ## 顶层配置
 
-| 配置 | 默认值 | 说明 |
-| --- | --- | --- |
-| `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`：
-
-| 配置 | 默认 | 说明 |
-| --- | --- | --- |
-| `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 违规 |
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `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 |
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    request: false,
-    blankScreen: false,
-    longTask: { threshold: 80 },
-  },
-});
-```
+## application
 
-## 请求配置
+| 字段 | 类型 | 默认 | Resource Attribute |
+| --- | --- | --- | --- |
+| `name` | `string` | 必填且非空 | `service.name` |
+| `environment` | `string` | `production` | `deployment.environment.name` |
+| `version` | `string` | 无 | `service.version` |
 
-`tracking.request.allowedTracingUrls` 是严格白名单，同源请求也必须命中后才注入 `traceparent`。关闭 Trace 时不会注入。`excludedUrls` 命中后完全不采集。SDK 自身已开启 signal endpoint 始终排除。
+SDK 还会固定写入 `rum.provider=blueking`、`rum.schema.version=1`、`telemetry.sdk.name=@blueking/open-telemetry` 和 `telemetry.sdk.language=webjs`。
+
+## transport
 
 ```ts
-new BkOpenTelemetry({
-  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=***'),
+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: {},
   },
-});
+}
 ```
 
-跨域注入 Trace Header 可能触发 CORS 预检，服务端需要放行 `traceparent`。
+### 根字段
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼默认信号路径 |
+| `token` | `string` | 无 | 生成 `Authorization: Bearer <token>` |
+| `headers` | `Record<string,string>` | 无 | 所有信号的公共 Header |
+| `signals` | `SignalExportersInputConfig` | 三类开启 | 单信号开关和覆盖项 |
+
+默认路径：Trace `/v1/rum`、Metric `/v1/metrics`、Log `/v1/logs`。单信号 `endpoint` 是完整 URL，不再拼路径。
+
+Header 覆盖顺序为 `token` < 根 `headers` < 单信号 `headers`。同名字段由右侧配置覆盖。
+
+### 单信号字段
+
+| 字段 | 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` 默认值。
+
+校验规则：
+
+- 三类信号不能全部为 `false`。
+- 每个已开启信号必须配置单独 Endpoint，或能回退到根 `transport.endpoint`。
+- 关闭 Trace 后不创建 Trace exporter/processor，不记录可导出的 Span，也不注入 `traceparent`。
+- 关闭 Metric 后不创建 reader；关闭 Log 后不创建 log processor，Request Body 配置也不会产生 Log。
+
+更多行为见[传输与采样](./transport-sampling.md)。
+
+## session
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `sampleRate` | `number` | `1` | Session 确定性采样；有限数值限制到 `0..1`，非有限值回退 `1` |
+| `storageKey` | `string` | 按应用名和 Endpoint host hash | Session localStorage key |
+
+Session 固定为 15 分钟无活动过期、4 小时最长生命周期，不开放超时配置。localStorage 不可用时退回进程内存。
+
+## tracking.view
 
-## 全局 beforeSend
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `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.beforeSend` 在 span/log 进入 exporter 前执行，可修改属性或返回 `false` 丢弃事件。内部 `bk.rum.sampled` 标记会在此之前移除。
+URL matcher 支持字符串包含、`RegExp` 或 `(url) => boolean`。字符串使用 `url.includes(matcher)`，不等于 origin 精确匹配；安全白名单应使用 URL-aware 函数或带边界的正则。自动 View 只对 pathname 和非页内锚点 hash path 的变化切换，query-only 变化不切换。
+
+## tracking.request
+
+`request` 可设为 `false` 完全关闭 Fetch/XHR patch；`true` 或 `{}` 使用默认配置。
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `excludedUrls` | matcher 或 matcher[] | 无 | 命中后不采集、不注入、不计入页面活动 |
+| `allowedTracingUrls` | matcher 或 matcher[] | 无 | W3C Trace Context 显式白名单；同源请求也必须命中，推荐 URL-aware 函数 |
+| `beforeSend` | `(event, context) => boolean \| void` | 无 | 修改请求属性；返回 `false` 丢弃 Span，并跳过该请求的 Body Log |
+| `body` | `BkOTRequestBodyConfig` | 关闭 | 请求/响应 Body Log |
+
+Request Body：
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `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 |
+
+默认不采集 Body。Body 只在 Log 信号开启时生效，不支持 FormData、ArrayBuffer 等不可安全文本化的内容。
+
+## tracking 内置能力
+
+| 字段 | 类型 | 默认 | 参数 |
+| --- | --- | --- | --- |
+| `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 条 |
+
+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
 tracking: {
@@ -142,84 +196,73 @@ tracking: {
 }
 ```
 
-## 不再支持的旧入口
+该 Hook 在 Span/Log 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning。它不处理 Metric；请求专属逻辑优先使用 `tracking.request.beforeSend`。
 
-`app`、`sampling`、`route`、顶层 `view`、`plugins`、`instrumentations`、`attributes`、`spanProcessor`、`spanBatch` 已删除，不做兼容映射。
+## context
 
-# 传输与采样
+| 字段 | 类型 | 默认 | 作用 |
+| --- | --- | --- | --- |
+| `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()` 附加属性 |
 
-## Endpoint
+自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。Metric Hook 禁止放用户 ID、订单 ID、完整 URL 等高基数字段。
 
-`transport.endpoint` 是可选根地址。未配置独立地址的已开启信号会基于它生成 `/v1/rum`、`/v1/metrics`、`/v1/logs`；单信号 `endpoint` 是完整 URL，不再拼接路径。
+## privacy
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: {
-    endpoint: 'https://collector.example.com',
-    token: 'report-token',
-    signals: {
-      traces: {
-        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' },
-    },
-  },
-});
-```
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
+| `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | SDK 创建 Span/Log 和内置插件属性脱敏 |
+
+第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
+
+## extensions
 
-## 独立信号开关
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `plugins` | `BkOTPlugin[]` | `[]` | 在内置插件后初始化 |
+| `instrumentations` | `Instrumentation[]` | `[]` | 插件完成后注册到 SDK provider |
 
-三类信号默认全部开启。设为 `false` 时，不创建对应 exporter、processor 或 metric reader：
+也可以在 `start()` 前调用 `use()` / `useInstrumentation()`。需要动态注册时设置 `autoStart: false`；启动后调用会抛错。
+
+## 完整配置骨架
 
 ```ts
 new BkOpenTelemetry({
-  application: { name: 'trace-only-demo' },
+  application: { name: 'demo', environment: 'production', version: '1.0.0' },
   transport: {
+    endpoint: 'https://collector.example.com',
+    token: 'token',
+    headers: {},
     signals: {
-      traces: { endpoint: 'https://trace.example.com/v1/rum' },
-      metrics: false,
-      logs: false,
+      traces: { processor: 'batch', batch: {} },
+      metrics: { intervalMillis: 60_000 },
+      logs: {},
     },
   },
+  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,
 });
 ```
-
-校验规则：
-
-- 至少开启一种信号，三类不能全部为 `false`。
-- 每个开启信号必须有独立 endpoint，或能回退到根 `transport.endpoint`。
-- 关闭 Trace 后不记录 Span，也不会向 `allowedTracingUrls` 注入 `traceparent`。
-- 关闭 Metric 后不启动周期导出定时器。
-- 关闭 Log 不影响 Session/View 上下文维护，但不会产生 Session、View Snapshot、HTTP body 等 Log。
-
-只开启 Metric 时没有精确 `view.id` 下钻链路；需要从指标定位具体 View 时，至少开启 Trace。
-
-请求头优先级：`token` 生成的 Authorization < `transport.headers` < 单 signal `headers`。
-
-浏览器 exporter 使用 `fetch keepalive`，SDK 在 `pagehide` 和页面进入 hidden 时触发 flush。`shutdown()` 会先结束 View 和插件，再 flush final Snapshot，最后关闭 provider。
-
-## Session 级确定性采样
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  session: { sampleRate: 0.05 },
-});
-```
-
-- `1` 表示全量，`0` 表示全部丢弃。
-- 决定由 `application.name + session.id` 的稳定 hash 得出。
-- 不写额外 sessionStorage；同一 Session 内 span/log/metric 决定一致。
-- Session 续期后使用新 ID 重新计算。
-
-Metric exporter 只接受带内部采样标记的数据点，并在传输前移除该标记。Metric 只保留低基数 `view.url_path_group`，精确 View 关联由 span/log/View Snapshot 的 `view.id` 提供。

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

@@ -54,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) {
@@ -69,8 +73,10 @@ const visibilityPlugin = createPlugin({
     };
 
     document.addEventListener('visibilitychange', onVisibilityChange);
-
-    return undefined;
+    teardownVisibility = () => document.removeEventListener('visibilitychange', onVisibilityChange);
+  },
+  shutdown() {
+    teardownVisibility();
   },
 });
 ```
@@ -158,4 +164,10 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 await bkOT.start();
 ```
 
-> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 RUM 数据仍受 Session sampler 和导出过滤约束。
+> 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

@@ -18,11 +18,11 @@ SDK 的数据模型遵循“浏览器 SDK 负责低成本原始数据和单事
 | `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` | 路由切换 | View 管理器（SPA/手动 View） |
-| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件 |
+| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件；`reportCustomEvent({ error })` 仍属于此类型 |
 
 > 每种 span 的具体 span 名、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
 
@@ -56,6 +56,8 @@ span.end();
 
 请求 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({
   name: 'upload_timeout',
@@ -92,7 +94,7 @@ console.log(getDurationBucket(1200)); // 500ms~2s
 - 终端信息：`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`
+- Error Span 属性：`exception.message_short`、`exception.stack_top_frame`、`exception.fingerprint`；完整异常位于标准 `exception` Span Event
 
 ## 后端派生
 

package/skills/bk-rum-otele/references/getting-started.md

@@ -18,6 +18,8 @@
 3. `schema`：负责 RUM 字段、span 类型、结果、耗时分桶等归一化模型。
 4. `browser` / `index`：分别提供 CDN 全局入口（`https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js`）和 ESM 模块入口（`@blueking/open-telemetry`）。
 
+完整能力、默认开关与信号产出见[能力矩阵](./capabilities.md)，初始化顺序、上下文和导出过滤见[架构与数据流](./architecture.md)。
+
 ## 最小示例
 
 ```ts
@@ -90,6 +92,20 @@ await bkOT.start();
 
 `use()`、`useInstrumentation()` 和 `extensions` 注册都必须发生在 `start()` 前。
 
+手动 View 也应在 `await start()` 建立 Session 后创建：
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'manual-view-demo' },
+  autoStart: false,
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: { view: { tracking: 'manual' } },
+});
+
+await bkOT.start();
+bkOT.startView({ name: '订单详情', url: location.href });
+```
+
 ## CDN
 
 ```html