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

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

@@ -2,122 +2,30 @@
 
 # 核心概念
 
-理解这些概念后，再看配置和插件会更顺畅。
+## 单一原始事件通道
 
-## 三类信号
+SDK 只使用 OpenTelemetry Trace：浏览器事实和本地体验语义都编码为 RUM Span，通过 `/v1/rum` 上报。浏览器不创建 Counter、Histogram 或 Log；聚合由服务端完成。
 
-`@blueking/open-telemetry` 同时使用 OpenTelemetry 的三类信号：
+## Session、View、Action
 
-- Trace：用于描述一次有起止时间的行为，例如页面访问、接口请求、资源加载、用户点击、长任务。
-- Metric：用于描述可聚合的数值，例如 Web Vitals、长任务数量、WebSocket 消息大小、空白屏结果。
-- Log：用于描述离散事件或诊断信息，例如 Session 生命周期、View Snapshot、请求 Body 和 WebSocket 状态。
+- `session.id` 关联一次访问会话，采样以 Session 为边界。
+- `view.id` 关联初始页面、SPA 路由、BFCache 或手动 View。
+- `action.id` 关联一次用户动作活动窗口。
+- `user.id` 由接入方提供，SDK 原样透传。
 
-示例：手动创建一个业务 span。
+生命周期事件使用 `event.id`、`event.type`、`event.phase`、`event.timestamp`。View 额外使用 `view.version` 处理更新和乱序。
 
-```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'checkout-web' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
-
-const span = bkOT.startSpan('custom.checkout_submit', {
-  'biz.order_id': '202605270001',
-  'biz.channel': 'pc',
-});
-
-span.end();
-```
-
-## Session、View、User
-
-SDK 会维护运行时公共上下文，并自动挂到后续 span/log 上：
-
-- `user.id`：由接入方提供，SDK 原样透传，不 hash、不脱敏、不改写。
-- `session.id`：由 session 插件生成和轮换，用于关联同一次访问会话。
-- `view.id` / `view.name` / `view.url` / `view.url_path_group`：由 View 管理器维护，用于关联同一个页面或路由实例。
-
-示例：登录后更新用户上下文。
-
-```ts
-bkOT.setUser({
-  id: 'user-12345',
-});
-```
-
-示例：手动模式由业务路由系统创建 View。
-
-```ts
-// 前提：autoStart: false，且已经 await bkOT.start() 建立 Session。
-bkOT.startView({
-  name: '商品详情',
-  url: window.location.href,
-  attributes: { 'biz.owner': 'product-team' },
-});
-```
-
-## 内置采集与扩展
-
-SDK 将能力分为两类：
-
-1. 内置采集：`tracking.request` 使用 SDK 自有的统一 Fetch/XHR 生命周期，负责 patch 浏览器 API、创建 `browser.resource` CLIENT Span、Trace Header 和请求 Performance Timing 匹配。
-2. RUM 插件：View、Session、`resource`、`error`、`webVitals`、`blankScreen`、`device` 等，负责主动产生 RUM 归一数据。
-
-用户交互统一由 SDK 的 `action` 插件采集。接入额外 instrumentation 时，应避免再注册覆盖 Fetch/XHR 或用户交互的探针，以免重复上报。
+## 本地计算边界
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    action: {
-      actionNameAttribute: 'data-bk-action-name',
-      maxDuration: 10000,
-    },
-  },
-});
-```
+SDK 只保留必须依赖浏览器本地状态的计算：CLS、INP、View Loading Time、Action Loading Time、挫败信号和白屏判断。错误分组、计数、分位数和跨事件聚合全部交给服务端。
 
 ## 采样
 
-`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件仍会维护必要的浏览器生命周期，但未命中时创建或导出路径会丢弃数据，`reportAction()` 和 `reportCustomEvent()` 直接返回。
-
-示例：生产环境按 10% 会话采样。
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  session: {
-    sampleRate: 0.1,
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
-});
-```
-
-## 数据归一
-
-SDK 会为 span 补充 RUM 归一字段，例如：
+`session.sampleRate` 使用 `application.name + session.id` 做确定性采样。采样率同时写入 Resource 的 `session.sample_rate`，供后端修正总体指标。
 
-- `span_type`：`document`、`resource`、`vital`、`error`、`longtask`、`action`、`route`、`custom`
-- `result`：`success`、`warning`、`error`、`timeout`、`abort`
+## 扩展
 
-示例：自定义 span 也可以复用归一字段构造器。
-
-```ts
-import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
-
-const span = bkOT.startSpan('custom.cache_warmup', {
-  ...buildRumSpanAttributes({
-    spanType: RUM_SPAN_TYPE.custom,
-    spanSubtype: 'cache_warmup',
-  }),
-});
-
-span.end();
-```
+自定义 RUM 插件使用 `context.startSpan()`，标准 OpenTelemetry instrumentation 通过 `extensions.instrumentations` 注册。避免重复注册 Fetch/XHR 或用户交互探针。
 
 # 内置采集与扩展
 
@@ -147,6 +55,6 @@ new BkOpenTelemetry({
 
 内置 Fetch/XHR 不再基于官方 instrumentation 叠加适配，而是由单一请求生命周期实现，避免重复 patch、重复活动计数及私有 `_addHeaders/_patchSend` 依赖。
 
-当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。Metric exporter 要求 SDK 内部采样标记，而包未公开对应 helper，因此第三方 instrumentation 产生的 Metric 默认会被过滤，不应作为已支持的扩展能力。
+当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。SDK 不创建 Metric Provider，第三方 instrumentation 的 Metric 不属于支持范围。
 
 扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。

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

@@ -2,7 +2,7 @@
 
 # 配置参考
 
-`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport` 必填；所有已启用信号必须能解析到有效 Endpoint。
+`BkOpenTelemetry` 只接受当前 `BkOTOptions` 结构。`application.name` 与 `transport.endpoint` 必填。
 
 ```ts
 import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
@@ -20,7 +20,7 @@ const bkOT = new BkOpenTelemetry(options);
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | `application` | `BkOTApplicationConfig` | 必填 | 应用 Resource 标识 |
-| `transport` | `BkOTTransportConfig` | 必填 | 三类 OTLP HTTP 导出链路 |
+| `transport` | `BkOTTransportConfig` | 必填 | 单一 RUM OTLP HTTP 导出链路 |
 | `session` | `BkOTSessionConfig` | `{ sampleRate: 1 }` | Session 存储和确定性采样 |
 | `tracking` | `BkOTTrackingConfig` | `{}` | 内置采集、View 与事件 Hook |
 | `context` | `BkOTContextConfig` | 无 | 初始用户与公共属性 Hook |
@@ -47,24 +47,15 @@ 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: {},
+  processor: 'batch',
+  batch: {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5000,
+    exportTimeoutMillis: 30000,
   },
+  timeoutMillis: 10_000,
+  concurrencyLimit: 10,
 }
 ```
 
@@ -72,35 +63,17 @@ transport: {
 
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼默认信号路径 |
+| `endpoint` | `string` | 无 | 根地址，去掉末尾 `/` 后拼 `/v1/rum` |
 | `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` |
+| `headers` | `Record<string,string>` | 无 | RUM 请求 Header |
+| `timeoutMillis` | `number` | OTel 默认 | Exporter 超时 |
+| `concurrencyLimit` | `number` | OTel 默认 | Exporter 并发数 |
+| `processor` | `'batch' \| 'simple'` | `batch` | Span Processor 模式 |
+| `batch` | `BkOTBatchConfig` | OTel 默认 | BatchSpanProcessor 参数 |
 
 `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。
+SDK 不提供 Logs/Metrics 开关或 Provider，所有 RUM 原始事件只走 `/v1/rum`。
 
 更多行为见[传输与采样](./transport-sampling.md)。
 
@@ -132,19 +105,9 @@ URL matcher 支持字符串包含、`RegExp` 或 `(url) => boolean`。字符串
 | --- | --- | --- | --- |
 | `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 |
+| `beforeSend` | `(event, context) => boolean \| void` | 无 | 修改请求属性；返回 `false` 丢弃 Span |
 
-默认不采集 Body。Body 只在 Log 信号开启时生效，不支持 FormData、ArrayBuffer 等不可安全文本化的内容。
+SDK 不读取或上报请求/响应 Body。
 
 ## tracking 内置能力
 
@@ -156,7 +119,7 @@ Request Body：
 | `blankScreen` | `boolean \| BkOTBlankScreenPluginOptions` | `true` | 见下表 |
 | `device` | `boolean \| BkOTDevicePluginOptions` | `true` | 见下表 |
 | `action` | `boolean \| BkOTActionPluginOptions` | `true` | 见下表 |
-| `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50`、`warningThreshold=100` ms |
+| `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50` ms |
 | `websocket` | `boolean` | `false` | 无 |
 | `cspViolation` | `boolean` | `false` | 无，内置同指纹 60 秒最多 5 条 |
 
@@ -196,7 +159,7 @@ tracking: {
 }
 ```
 
-该 Hook 在 Span/Log 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning。它不处理 Metric；请求专属逻辑优先使用 `tracking.request.beforeSend`。
+该 Hook 在 Span 进入底层 processor 前执行，可原地修改属性或返回 `false` 丢弃。异常会被吞掉，`debug: true` 时输出 warning；请求专属逻辑优先使用 `tracking.request.beforeSend`。
 
 ## context
 
@@ -204,11 +167,10 @@ tracking: {
 | --- | --- | --- | --- |
 | `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()` 附加属性 |
 
-自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。Metric Hook 禁止放用户 ID、订单 ID、完整 URL 等高基数字段。
+自定义 `page` Hook 会替换默认 host/path Hook，不是合并默认实现。
 
 ## privacy
 
@@ -216,7 +178,7 @@ tracking: {
 | --- | --- | --- | --- |
 | `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
 | `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
-| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span/Log 和内置插件属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span 和内置插件属性脱敏 |
 
 第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
 
@@ -238,11 +200,8 @@ new BkOpenTelemetry({
     endpoint: 'https://collector.example.com',
     token: 'token',
     headers: {},
-    signals: {
-      traces: { processor: 'batch', batch: {} },
-      metrics: { intervalMillis: 60_000 },
-      logs: {},
-    },
+    processor: 'batch',
+    batch: {},
   },
   session: { sampleRate: 1 },
   tracking: {

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

@@ -52,9 +52,9 @@ await bkOT.start();
 
 ## 使用 runtime context
 
-`init(context)` 中可以访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()`、`getRuntimeAttributes()` 等能力。
+`init(context)` 中可以访问 `tracer`、`startSpan()`、`getRuntimeAttributes()` 等能力。
 
-优先使用 `context.startSpan()` 和 `context.emitLog()`：它们会合并事件发生时的运行时上下文并应用 SDK 脱敏。直接调用 `context.logger.emit()` 的 Log 不会自动获得这些能力，可能因缺少有效 Session/View 被导出过滤器丢弃。
+优先使用 `context.startSpan()`：它会合并事件发生时的运行时上下文并应用 SDK 脱敏。
 
 ```ts
 let teardownVisibility = () => {};
@@ -63,13 +63,12 @@ const visibilityPlugin = createPlugin({
   name: 'visibility-change',
   init(context) {
     const onVisibilityChange = () => {
-      context.emitLog({
-        severityText: 'INFO',
-        body: 'document.visibilitychange',
-        attributes: {
+      const occurredAt = Date.now();
+      context.startSpan('document.visibilitychange', {
+          'event.type': 'custom',
+          'event.timestamp': occurredAt,
           'document.visibility_state': document.visibilityState,
-        },
-      });
+      }, { startTime: occurredAt }).end(occurredAt);
     };
 
     document.addEventListener('visibilitychange', onVisibilityChange);
@@ -164,10 +163,8 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 await bkOT.start();
 ```
 
-> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束；第三方 instrumentation Metric 因没有公开采样 helper，默认会被过滤。
-
-## 自定义 Metric 注意事项
+> Extension instrumentation 与采集生命周期一致：未授权或 SDK 停止时不会注册；授权后注册。它产生的 Span 受 Session sampler 和导出过滤约束。
 
-内置 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，而不是绕过当前过滤约束。
+SDK 插件上下文不提供 Meter、Logger 或 `emitLog()`。具体业务行为使用 Span；计数、分布和分位数由服务端从 Span 派生。

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

@@ -2,110 +2,38 @@
 
 # 数据模型
 
-SDK 的数据模型遵循“浏览器 SDK 负责低成本原始数据和单事件归一，跨事件聚合交给后端”的边界。
+数据模型遵循“浏览器上报原始事件，服务端派生聚合”的边界。
 
-## 分层模型
+## 四层字段
 
-1. OpenTelemetry 原生字段：trace、span、resource、metric、log 的标准字段。
-2. RUM 归一字段：`span_type`、`span_subtype`、`result`、`error_type` 等。
-3. 运行时上下文：`user.id`、`session.id`、`view.id`、`view.url`、`view.url_path_group` 等。
-4. 后端派生字段：session/view duration、count、地理信息、影响用户数、trace tree 分析等。
+1. OpenTelemetry Resource/Span 标准字段。
+2. RUM 事件字段：`event.id/type/phase/timestamp`。
+3. 关联上下文：`user.id`、`session.id`、`view.id`、`action.id`。
+4. 单事件语义：`span_type`、`span_subtype`、`result`、`error_type` 和插件原始字段。
 
 ## Span 类型
 
-| 类型 | 说明 | 常见来源 |
-| --- | --- | --- |
-| `document` | 文档加载 | View 管理器（初始加载） |
-| `resource` | Fetch/XHR 请求与静态资源 | request、resource 采集 |
-| `vital` | Web Vitals | webVitals 插件 |
-| `error` | 浏览器与体验错误 | error 插件、blankScreen 插件、cspViolation 插件 |
-| `longtask` | 长任务 | longTask 插件 |
-| `action` | 用户动作 | action 插件、reportAction |
-| `route` | 路由切换 | View 管理器（SPA/手动 View） |
-| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件；`reportCustomEvent({ error })` 仍属于此类型 |
+`document`、`route`、`session`、`resource`、`vital`、`error`、`longtask`、`action`、`websocket`、`custom`。
 
-> 每种 span 的具体 span 名、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
+## 浏览器直接产生
 
-示例：自定义业务事件归一为 `custom`。
+- Session/View/Action 标识和生命周期；
+- URL、HTTP 状态、资源体积与 Resource Timing；
+- Error/CSP 原始字段和标准 exception event；
+- Web Vitals 值与 attribution；
+- WebSocket 连接生命周期；
+- 设备、浏览器、系统和网络上下文。
 
-```ts
-import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
+## 浏览器本地语义
 
-const span = bkOT.startSpan('custom.search', {
-  ...buildRumSpanAttributes({
-    spanType: RUM_SPAN_TYPE.custom,
-    spanSubtype: 'search',
-  }),
-  'biz.keyword_length': 6,
-});
+CLS、INP、View Loading Time、Action Loading Time、挫败信号和白屏判断依赖 DOM、Performance API 或页面活动窗口，由 SDK 计算后上报。
 
-span.end();
-```
+## 服务端派生
 
-## Result 与 Error Type
+- Session/View duration 和各类 count；
+- 错误率、错误 fingerprint/group；
+- Histogram 与 P50/P75/P95/P99；
+- 影响用户数、地理信息和采样修正；
+- 迟到/乱序关联和 View 版本合并。
 
-`result` 描述事件结果，取值包括：
-
-- `success`
-- `warning`
-- `error`
-- `timeout`
-- `abort`
-
-请求 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',
-  error: new Error('request timeout'),
-  attributes: {
-    'biz.file_size': 1024 * 1024,
-  },
-});
-```
-
-## SDK 直接采集
-
-以下字段由浏览器 API、接入方配置或 SDK 运行期上下文直接提供：
-
-- 应用与环境：`service.name`、`deployment.environment.name`、`service.version`
-- 用户与会话：`user.id`、`session.id`
-- 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`、`resource.size`
-- Web Vitals：`vital.metric`、`vital.value`、`vital.rating`
-- Error Span 属性：`exception.message_short`、`exception.stack_top_frame`、`exception.fingerprint`；完整异常位于标准 `exception` Span Event
-
-## 后端派生
-
-以下字段不在浏览器 SDK 中直接生成：
-
-- Session 聚合：`session.duration`、`view_count`、`trace_count`、`error_count`、`action_count`
-- View 聚合：`view.duration`、`request_count`、`resource_count`、`longtask_count`
-- Trace 树：`relative_start`、`hierarchy_level`、`parent_span_name`、`is_critical_path`
-- 影响面：`affected_user_count`
-- 地理信息：`geo.country`、`geo.city`
-
-## 高基数字段策略
-
-高基数字段可以进入 span/log，但不应进入 metric 维度。比如订单 ID、用户输入、完整 URL query 都应谨慎使用。
-
-```ts
-bkOT.reportCustomEvent({
-  name: 'order_submit',
-  attributes: {
-    'biz.order_id': '202605270001',
-    'biz.order_type': 'normal',
-  },
-});
-```
-
-上例中 `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。
+服务端应使用 `event.id` 去重，使用 `view.id + view.version` 幂等处理 View 更新。

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

@@ -2,7 +2,7 @@
 
 # 简介
 
-`@blueking/open-telemetry` 是面向浏览器真实用户监控（RUM）的 OpenTelemetry 封装 SDK。它基于 OpenTelemetry Web SDK，将页面访问、资源加载、接口请求、JavaScript 错误、Web Vitals、空白屏、会话、用户动作等浏览器事件统一转成 trace、metric、log 三类信号，并通过 OTLP HTTP 协议上报。
+`@blueking/open-telemetry` 是面向浏览器真实用户监控（RUM）的 OpenTelemetry 封装 SDK。它将页面访问、资源加载、接口请求、JavaScript 错误、Web Vitals、空白屏、会话和用户动作等浏览器事件统一转成原始 RUM Span，通过单一 OTLP HTTP 通道上报。
 
 ## 适合解决什么问题
 

package/skills/bk-rum-otele/references/plugins-basic.md

@@ -8,7 +8,7 @@
 
 ## session
 
-`session` 维护 `session.id`，并在会话开始和轮换时写入 log。它是所有 RUM 信号的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
+`session` 维护 `session.id`，并在会话开始、轮换和结束时写入 `browser.session` 生命周期 Span。它是所有 RUM 事件的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
 
 默认规则：
 
@@ -26,9 +26,9 @@ new BkOpenTelemetry({
 });
 ```
 
-超时固定为 15 分钟无活动、4 小时最长生命周期，不开放配置。过期会结束当前 View、刷新旧 session 的待发送数据，并丢弃此后所有不带有效 `session.id` 的 span/log/metric；下一次用户交互续期时，同时创建新的 Session 和 View。Metric 使用 DELTA temporality，避免累计值跨 session 重复上报。
+超时固定为 15 分钟无活动、4 小时最长生命周期，不开放配置。过期会结束当前 View、刷新旧 Session 的待发送数据，并丢弃此后所有不带有效 `session.id` 的 Span；下一次用户交互续期时，同时创建新的 Session 和 View。
 
-**产出遥测**：log `session.start` / `session.rotate`，并维护运行时属性 `session.id`。
+**产出遥测**：`browser.session` start/rotate/end Span，并维护 `session.id`、`session.start_time`、`session.type`。
 
 ## device
 
@@ -45,11 +45,11 @@ new BkOpenTelemetry({
 });
 ```
 
-稳定的浏览器、系统和硬件能力写入三类信号共享的 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 span/log 会自动携带，便于按浏览器、系统、网络类型下钻。
+稳定的浏览器、系统和硬件能力写入 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 Span 会自动携带。
 
 `device.id` 默认只在当前 SDK 实例内稳定；只有显式设置 `persistentId: true` 才写入 localStorage，并按应用名隔离默认 storage key。
 
-**产出遥测**：写入 Resource 属性（如 `browser.name`、`os.name`、`device.type`、`device.memory_gib`）和运行时属性（如 `device.id`、`browser.viewport.*`、`network.effective_type`），本身不单独产生 span/metric/log。
+**产出遥测**：写入 Resource 属性（如 `browser.name`、`os.name`、`device.type`、`device.memory_gib`）和运行时属性（如 `device.id`、`browser.viewport.*`、`network.effective_type`），本身不单独产生 Span。
 
 ## View
 
@@ -97,11 +97,11 @@ bkOT.startView({
 bkOT.setViewName('订单详情-只读');
 ```
 
-`view.id` 始终由 SDK 生成，`attributes` 不能覆盖 Session/View 等保留字段。普通 span/log 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路；metric 只保留 `view.url_path_group` 等低基数维度，不携带唯一 `view.id`。手动模式在首次 `startView()` 前不会导出普通 RUM 数据。
+`view.id` 始终由 SDK 生成，`attributes` 不能覆盖 Session/View 等保留字段。普通 Span 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路。手动模式在首次 `startView()` 前不会导出普通 RUM 数据。
 
 View Loading Time 默认开启：初始加载取 `loadEventEnd` 与页面活动结束时间的较大值，SPA 路由取 View 创建到页面活动结束的耗时。请求、静态资源和 DOM 变更都属于页面活动，连续 100ms 无活动视为稳定。长轮询或埋点请求应配置到 `view.excludedActivityUrls`；业务也可在真正渲染完成时调用 `setViewLoadingTime()` 覆盖自动结果。
 
-**产出遥测**：长 span `browser.view`（包含 `view.loading_time`）与 body 为 `browser.view` 的 create/update/final Snapshot Log，metric `browser.view.loading_time`，并维护 `view.*` 运行时属性。
+**产出遥测**：`browser.view` start/update/end 原始生命周期 Span。每次事件携带 `view.version`，Loading Time 就绪或 View 名称变化时产生 update。
 
 ## action
 

package/skills/bk-rum-otele/references/plugins-error-security.md

@@ -16,7 +16,7 @@
 
 插件会生成 error span，并使用 fingerprint 做窗口内节流，避免相同错误在短时间内刷屏。
 
-**产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带异常摘要、`error.source`、`error.window_occurrence_index`；精确总量由 `browser.error.count` 记录。
+**产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带原始 `error.message`、`error.source` 和标准 exception event。SDK 不做错误指纹、计数或节流。
 
 ```ts
 new BkOpenTelemetry({

package/skills/bk-rum-otele/references/plugins-experience.md

@@ -42,9 +42,9 @@ new BkOpenTelemetry({
 
 ## webVitals
 
-`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。FCP/LCP/TTFB 按指标发生时刻归属 View，CLS 使用每个 View 独立的 1 秒间隔/5 秒窗口，INP 使用候选交互的近似 p98，而不是简单最大值。它会同时产生 metric 和 span：metric 用于低基数聚合，span 用于通过 `session.id`、`view.id` 定位具体页面和归因信息。
+`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。FCP/LCP/TTFB 按指标发生时刻归属 View，CLS 使用每个 View 独立的 1 秒间隔/5 秒窗口，INP 使用候选交互的近似 p98，而不是简单最大值。它只产生带 `session.id`、`view.id` 和 attribution 的原始 Span，聚合由服务端完成。
 
-**产出遥测**：metric `browser.web_vital.cls`（unit `1`）、`browser.web_vital.duration`（unit `ms`，FCP/INP/LCP/TTFB 共用）+ span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
+**产出遥测**：span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
 
 ```ts
 new BkOpenTelemetry({
@@ -74,7 +74,7 @@ new BkOpenTelemetry({
 
 SPA 应用建议配置 `rootSelector`。根节点在确认阶段仍不存在时会以 `missing_root` 原因上报；loading 和骨架屏样本不进入空白比例分母。
 
-**产出遥测**（仅判定为白屏时）：metric `browser.blank_screen.count` + error span `browser.blank_screen`（`span_type=error`）。
+**产出遥测**（仅判定为白屏时）：error span `browser.blank_screen`（`span_type=error`）。
 
 ## longTask
 
@@ -85,7 +85,6 @@ new BkOpenTelemetry({
   tracking: {
     longTask: {
       threshold: 50,
-      warningThreshold: 100,
     },
   },
 });
@@ -93,7 +92,7 @@ new BkOpenTelemetry({
 
 LoAF 会补充 blocking duration、render/style/layout 阶段、最重脚本归因，并把每个脚本作为 `long_task.script` Span Event。初始化阶段的 buffered entries 延迟到后续宏任务批量处理，避免 SDK 启动自身制造阻塞。不支持 LoAF 和 Long Tasks API 的浏览器会跳过插件。
 
-**产出遥测**：metric `browser.long_task.count` / `browser.long_task.duration` / `browser.long_task.blocking_duration`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
+**产出遥测**：span `browser.long_task`（`span_type=longtask`），计数与耗时分布由服务端派生。
 
 ## View Loading Time