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

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

@@ -1,141 +1,32 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 网络与扩展插件
+# 网络扩展
 
-网络能力覆盖 Fetch/XHR 与 WebSocket。两者都会 patch 浏览器全局 API，同一页面只应运行一个 SDK 实例。
+## Fetch/XHR
 
-以下片段聚焦 `tracking`，实际初始化仍需提供 `application.name` 和有效 Transport。
+`tracking.request` 默认开启。SDK 使用单层 patch 创建 `browser.resource` CLIENT Span：
 
-## Fetch/XHR request
+1. `excludedUrls` 命中时完全跳过。
+2. 创建带 `event.id/event.timestamp/event.type=resource` 的请求 Span。
+3. `allowedTracingUrls` 命中时注入 W3C Trace Context。
+4. 请求完成后补充状态、错误和 Resource Timing。
+5. `request.beforeSend` 可修改属性或返回 `false` 丢弃 Span。
 
-`tracking.request` 默认开启。当前实现由 SDK 自己统一 patch `window.fetch` 与 `XMLHttpRequest.prototype.open/send`，不使用官方 Fetch/XHR instrumentation，也不会为同一请求叠加两套生命周期。
+SDK 不读取或上报请求/响应 Body。
 
-### 请求生命周期
+## 静态资源
 
-一次请求按以下顺序处理：
+`tracking.resource` 默认开启，使用 Resource PerformanceObserver 创建 `browser.resource` Span。Fetch/XHR 的 PerformanceEntry 只回填已有请求 Span，不重复上报。
 
-1. 转成绝对 URL，检查 SDK 自身 OTLP Endpoint 与 `excludedUrls`。
-2. 创建名为 `browser.resource`、kind 为 `CLIENT` 的 Span。
-3. 记录 View/Action 页面活动；`view.excludedActivityUrls` 可只排除活动等待，不丢弃 Span。
-4. `allowedTracingUrls` 命中且 Trace 开启时进入传播 Header 注入分支；默认 W3C propagator 注入 `traceparent`，宿主已有全局 propagator 时以实际实现为准。
-5. 请求完成后写入状态、结果、错误和 `request.beforeSend` 属性。
-6. 等待最多 200ms 匹配 Resource Timing，把网络阶段补回同一 Span。
-7. 如已配置 Body 且 Log 开启，异步生成关联原 `trace.id` / `span.id` 的诊断 Log。
+## WebSocket
 
-**产出遥测**：Span `browser.resource`，`span_type=resource`、`resource.type=fetch|xhr`，常用属性包括 `http.request.method`、`http.response.status_code`、`url.full`、`server.address`、网络阶段与响应体积。
+`tracking.websocket` 默认关闭。启用后通过 Proxy 保持原生静态常量、`instanceof` 和子类行为，只监听连接生命周期：
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'request-demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: {
-    request: {
-      excludedUrls: [/\/health(?:\?|$)/],
-      beforeSend(event, context) {
-        event.attributes['request.transport'] = context.type;
-        return event.resource.statusCode !== 404;
-      },
-    },
-  },
-});
-```
+- `browser.websocket` `event.phase=connect`
+- `browser.websocket` `event.phase=open`
+- `browser.websocket` `event.phase=error`
+- `browser.websocket` `event.phase=close`
 
-`request.beforeSend` 在请求完成后执行，可修改 Span attributes；返回 `false` 会标记该 Span 在最终 processor 中丢弃，并立即跳过该请求的 Body Log。Hook 抛错不会中断业务请求，`debug: true` 时输出 warning。
+同一连接通过 `websocket.connection.id` 关联。SDK 不包裹 `send()`，不采集消息内容、数量或字节数，也不在客户端聚合建连时长。
 
-### excludedUrls 与 excludedActivityUrls
-
-| 配置 | 是否创建 Span | 是否计入 View/Action 活动 | 适用场景 |
-| --- | --- | --- | --- |
-| `tracking.request.excludedUrls` | 否 | 否 | 探活、埋点、无需采集的请求 |
-| `tracking.view.excludedActivityUrls` | 是 | 否 | 长轮询、SSE、流式接口，不应阻塞页面稳定 |
-
-两者都支持字符串包含、RegExp 和函数 matcher。
-
-### traceparent 注入条件
-
-只有 `allowedTracingUrls` 命中且 Trace 信号开启时才进入传播 Header 注入分支；默认 W3C propagator 会注入 `traceparent`，同源请求也不隐式放行。
-
-```ts
-tracking: {
-  request: {
-    allowedTracingUrls: [
-      url => new URL(url).origin === 'https://api.example.com',
-      /^https:\/\/[^/]+\.internal\.example\.com\//,
-    ],
-  },
-}
-```
-
-字符串 matcher 使用包含匹配，例如 `'https://api.example.com'` 也会命中 `https://api.example.com.evil/`，不适合作为安全 origin 边界。需要精确控制时使用上面的 URL-aware 函数或带 `/` 边界的正则。
-
-跨域注入会触发 CORS 预检，目标服务必须在 `Access-Control-Allow-Headers` 放行实际使用的 Trace Header。SDK 成功注册自己的默认 W3C propagator 时通常注入 `traceparent`，并可能透传已有 `tracestate`；如果宿主已注册全局 propagator，实际 Header 由该 propagator 决定，可能还包含其他传播字段。
-
-### Resource Timing
-
-Fetch/XHR 与静态资源共用一个 Resource PerformanceObserver：
-
-- `initiatorType=fetch|xmlhttprequest` 的 entry 只用于匹配请求 Span，不再创建静态资源 Span。
-- 通过 URL 与时间窗口匹配；找不到 entry 时请求 Span 仍正常结束。
-- 跨域接口缺少 `Timing-Allow-Origin` 时，浏览器不会提供完整阶段字段。
-- Trace 关闭时跳过 timing 等待，因为不存在可导出的请求 Span。
-
-### 请求/响应 Body
-
-Body 默认关闭。开启时必须提供 `redact`，默认只采集状态未知、0 或 `>=400` 的请求：
-
-```ts
-tracking: {
-  request: {
-    body: {
-      capture: 'errors',
-      maxSize: 10 * 1024,
-      allowedContentTypes: ['application/json', /^text\//],
-      redact({ body, kind }) {
-        if (kind === 'request') {
-          return body.replace(/("(?:password|token)"\s*:\s*)"[^"]*"/g, '$1"***"');
-        }
-        return body;
-      },
-    },
-  },
-}
-```
-
-**产出遥测**：Log `browser.request.body`，错误请求为 ERROR，`capture: 'all'` 下成功请求为 INFO。
-
-- Fetch 的 Request/Response 通过 clone 限量读取，不消费业务原始流。
-- XHR 支持文本与 JSON 响应。
-- string、URLSearchParams、Blob 等可文本化请求可读取；FormData、ArrayBuffer 和二进制响应跳过。
-- 默认 Content-Type：`text/*`、包含 `json`、`application/x-www-form-urlencoded`、`application/graphql`。
-- `redact` 返回 `undefined` 时只跳过当前 request 或 response Body。
-- Log 信号关闭时 Body 配置不生效。
-
-## websocket
-
-`tracking.websocket` 默认关闭。开启后用 Proxy 包装 `window.WebSocket`，保留静态常量、`instanceof` 与子类化行为。
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'realtime-demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: { websocket: true },
-});
-```
-
-**产出遥测**：
-
-- Span `websocket.connect`：只覆盖建连阶段，成功/失败后结束，不用长 Span 覆盖整个连接。
-- Metric `browser.websocket.message.count`、`browser.websocket.message.bytes`：按 `in/out` 分组。
-- Metric `browser.websocket.error.count`：按 `connect/runtime` 分组。
-- Metric `browser.websocket.connect.duration`：只记录成功建连耗时。
-- Log `websocket.error`、`websocket.close`：记录错误阶段和关闭详情。
-
-插件不读取消息内容，只计算数量和字节数。超过 64KB 的字符串使用 `string.length` 近似字节数，避免编码开销；CJK/emoji 会低估。相同 URL 的错误 Log 在 60 秒内最多 5 条，Error Counter 不受节流影响。
-
-SDK shutdown 后新建连接不再采集；已存在连接上的包装会保留，但回调立即返回。若其他库后来替换了 `window.WebSocket`，shutdown 不会强行覆盖后来者。
-
-## 与额外 instrumentation 的关系
-
-`extensions.instrumentations` 适合已有标准 OpenTelemetry instrumentation。不要再注册覆盖 Fetch/XHR 或用户交互的 instrumentation，否则可能与内置 request/action 重复 patch、重复 Span。
-
-需要 Session/View、`emitLog()`、页面活动或 RUM 归一字段时，优先写自定义插件，见[内置采集与扩展](./concepts.md)与[自定义插件](./custom-plugin.md)。
+需要 Session/View 关联或活动总线时使用自定义 RUM 插件和 `context.startSpan()`；标准第三方采集可通过 OpenTelemetry instrumentation 扩展。

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

@@ -28,10 +28,10 @@ new BkOpenTelemetry({
 
 | 分类       | 插件                                                              | 主要信号                      |
 | ---------- | ----------------------------------------------------------------- | ----------------------------- |
-| 基础上下文 | Session、View、`device`                                           | log、span、runtime attributes |
-| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span、metric、log          |
+| 基础上下文 | Session、View、`device`                                           | span、runtime attributes |
+| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span          |
 | 错误安全   | `error`、`cspViolation`                                           | span                          |
-| 网络扩展   | Fetch/XHR request patch、`websocket`                              | span、metric、log             |
+| 网络扩展   | Fetch/XHR request patch、`websocket`                              | span             |
 | 用户行为   | `action`、`reportAction()`                                        | span                          |
 
 ## 插件启用规则

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

@@ -24,7 +24,7 @@ new BkOpenTelemetry({
 
 ## 属性脱敏
 
-`privacy.redactAttributes` 会处理 Resource、通过 SDK `startSpan()`、`emitLog()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。Resource 在 SDK 构造时处理一次，后续不会动态更新。
+`privacy.redactAttributes` 会处理 Resource、通过 SDK `startSpan()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。Resource 在 SDK 构造时处理一次，后续不会动态更新。
 
 ```ts
 new BkOpenTelemetry({
@@ -40,16 +40,15 @@ new BkOpenTelemetry({
 });
 ```
 
-第三方 OpenTelemetry instrumentation 自己生成的 Span 属性不保证经过这一构造路径。需要统一清理第三方 Span 时，在 `tracking.beforeSend` 做最终兜底；该 Hook 作用于 Span/Log，不作用于 Metric。
+第三方 OpenTelemetry instrumentation 自己生成的 Span 属性不保证经过这一构造路径。需要统一清理第三方 Span 时，在 `tracking.beforeSend` 做最终兜底。
 
 `redactAttributes` 应返回完整可用的属性对象，不要只返回被修改的单个字段。
 
 ## 公共属性
 
-`context.attributes` 提供四类 hook：
+`context.attributes` 提供三类 hook：
 
 - `page`：页面、动作、错误等需要页面上下文的事件。
-- `metric`：metric 维度，必须避免高基数字段。
 - `error`：错误事件补充属性。
 - `custom`：手动自定义事件补充属性。
 
@@ -61,9 +60,6 @@ new BkOpenTelemetry({
         'biz.space_id': window.__BK_SPACE_ID__,
         'biz.project_id': window.__BK_PROJECT_ID__,
       }),
-      metric: () => ({
-        'biz.app_code': 'bk-monitor',
-      }),
       error: () => ({
         'biz.release_channel': window.__BK_RELEASE_CHANNEL__,
       }),
@@ -91,24 +87,7 @@ new BkOpenTelemetry({
 
 ## 请求数据边界
 
-SDK 默认不采集请求/响应 body。显式开启 `request.body` 时必须提供 `redact`，建议保持默认的 `capture: 'errors'`，并限制 Content-Type 和最大长度。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    request: {
-      body: {
-        capture: 'errors',
-        maxSize: 4096,
-        allowedContentTypes: ['application/json'],
-        redact: ({ body }) => {
-          return body.replace(/"password"\s*:\s*"[^"]+"/g, '"password":"***"');
-        },
-      },
-    },
-  },
-});
-```
+SDK 不读取或上报请求/响应 Body。
 
 ## 低基数路由
 

package/skills/bk-rum-otele/references/telemetry-reference.md

@@ -2,285 +2,55 @@
 
 # 遥测参考
 
-本页是 SDK **实际产出**的 span 名、metric 名、log 事件名和属性字段的权威速查表，供数据看板、告警规则、后端建模对齐。所有名称都与 SDK 源码保持一致，随版本更新。
-
-> 概念与设计边界见[数据模型](./data-model.md)；本页只做「叫什么名字、带哪些字段」的查询。
-
-## 命名规则
-
-- **信号名**：`browser.*` 表示内置浏览器事件（如 `browser.web_vital`）；`action.<type>`、`custom.<name>` 是运行期动态拼接；`csp.violation`、`websocket.*` 使用领域前缀。
-- **属性 key**：标准字段与 RUM 领域字段均使用点号命名空间（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。公共与跨插件字段常量集中定义在 `src/schema/attributes.ts`，插件私有字段在对应插件内定义。
-
-## 公共 Resource 与运行时上下文属性
-
-Resource 属性由三类信号共享；运行时上下文属性自动挂到**几乎所有** span / log 上（metric 视插件而定）。后续各清单不再重复列出：
-
-| key | 归属 | 类型 | 说明 | 低基数 |
-| --- | --- | --- | --- | --- |
-| `service.name` | Resource | string | 应用名（`application.name`） | 是 |
-| `service.version` | Resource | string | 应用版本（`application.version`，可选） | 是 |
-| `deployment.environment.name` | Resource | string | 环境（`application.environment`） | 是 |
-| `rum.schema.version` | Resource | string | 当前固定 `2` | 是 |
-| `telemetry.sdk.name` / `telemetry.sdk.language` / `telemetry.sdk.version` | Resource | string | SDK 名、语言和包版本 | 是 |
-| `device.type` | Resource | string | `mobile` / `desktop` | 是 |
-| `browser.name` / `browser.version` | Resource | string | 归一化浏览器信息 | 是 |
-| `os.name` | Resource | string | 操作系统 | 是 |
-| `device.memory_gib` | Resource | number | 浏览器暴露的近似设备内存（GiB） | 是 |
-| `device.logical_processor_count` | Resource | number | 浏览器暴露的逻辑处理器数量 | 是 |
-| `user.id` | Runtime | string | 接入方提供，原样透传 | 否 |
-| `session.id` | Runtime | string | session 插件生成/轮换 | 否 |
-| `session.has_replay` | Runtime | boolean | 当前固定 `false` | 是 |
-| `view.id` | Runtime | string | View 管理器生成的实例 ID | 否 |
-| `view.name` | Runtime | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
-| `view.url` | Runtime | string | 当前 view URL（已脱敏） | 否 |
-| `view.url_path_group` | Runtime | string | 低基数路由模板 | 是 |
-| `view.loading_type` | Runtime | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
-| `device.id` | Runtime | string | 当前实例或持久化匿名设备 ID | 否 |
-| `network.effective_type` | Runtime | string | 网络质量（`4g` 等） | 是 |
-
-> span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` 等归一字段（见下方[归一字段](#归一字段)）。接入方可通过 `context.attributes.page` 注入额外的页面属性。
+SDK 只产出 RUM Span，不产出 OpenTelemetry Metric 或 Log。计数、直方图、分位数和错误分组由服务端从原始 Span 派生。
+
+## 公共字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `event.id` | string | 每条原始事件的唯一 ID，服务端去重键 |
+| `event.type` | string | `session`、`view`、`resource`、`error`、`vital`、`action`、`websocket` 等 |
+| `event.phase` | string | 生命周期事件阶段；非生命周期事件可不带 |
+| `event.timestamp` | number | 浏览器事件发生的 epoch ms |
+| `session.id` | string | Session 关联 ID |
+| `session.start_time` | number | Session 开始时间 |
+| `session.type` | string | 当前为 `user` |
+| `session.sample_rate` | number | Resource 字段，范围 `0..1` |
+| `view.id` | string | View 关联 ID |
+| `view.name` | string | View 名称 |
+| `view.url` | string | 脱敏后的 URL |
+| `view.url_path_group` | string | 服务端聚合用路由模板 |
+| `action.id` | string/string[] | Action 关联 ID |
+| `span_type` / `span_subtype` | string | RUM 分类 |
+| `result` / `error_type` | string | 单事件结果分类 |
 
 ## Span 清单
 
-| span 名 | span_type | kind | 来源 | 关键属性 | 备注 |
-| --- | --- | --- | --- | --- | --- |
-| `browser.view` | `document` / `route` | INTERNAL | View 管理器 | `view.name`、`view.loading_time`、`view.loading_time.source`、`url.previous`、`event.source`、`view.end_reason` | 有持续时间，由下一次 View、pagehide、Session 过期或 SDK shutdown 结束 |
-| `browser.resource` | `resource` | CLIENT | Fetch/XHR request 采集 | `resource.type=fetch\|xhr`、`url.full`、`http.request.method`、`http.response.status_code`、网络阶段属性 | Fetch/XHR 共用同一实现 |
-| `browser.resource` | `resource` | CLIENT | resource 插件 | `resource.type`、`url.full`、`resource.size`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
-| `browser.web_vital` | `vital` | INTERNAL | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
-| `browser.blank_screen` | `error` | INTERNAL | blankScreen 插件（二次确认白屏时） | `blank_screen.empty_ratio`、`blank_screen.reason`、`blank_screen.root_selector`、`blank_screen.root_found`、`blank_screen.*_sample_count`、`blank_screen.center_element` | 每个 View 最多一条 |
-| `browser.error` | `error` | INTERNAL | error 插件（`window.error`） | `exception.fingerprint`、`exception.message_short`、`exception.stack_top_frame`、`error.source=window.error`、`error.window_occurrence_index`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | 完整异常写入标准 `exception` Span Event |
-| `browser.unhandledrejection` | `error` | INTERNAL | error 插件（Promise 异常） | `exception.fingerprint`、`error.source=unhandledrejection` | 完整异常写入标准 `exception` Span Event |
-| `browser.resource_error` | `error` | INTERNAL | error 插件（资源加载失败） | `exception.fingerprint`、`error.source=resource`、`url.full`、`html.tag` | 完整异常写入标准 `exception` Span Event |
-| `browser.long_task` | `longtask` | INTERNAL | longTask 插件 | `long_task.id`、`long_task.entry_type`、`long_task.start_time`、`long_task.duration`、`long_task.blocking_duration`、`long_task.culprit`、`long_task.script.count` | LoAF 脚本详情写入 `long_task.script` Span Event |
-| `csp.violation` | `error` | INTERNAL | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_occurrence_index`、`csp.original_policy`（窗口首条） | |
-| `websocket.connect` | `custom` | CLIENT | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`server.port`、`network.protocol.name=websocket` | 长连接生命周期不绑定 span |
-| `action.click` / `action.custom` | `action` | INTERNAL | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
-| `custom.<name>` | `custom` | INTERNAL | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时记录 exception、设置错误 Status/Result，`span_type` 仍为 `custom` |
-
-## Metric 清单
-
-| 名称 | 类型 | 单位 | 主要维度 | 来源 |
-| --- | --- | --- | --- | --- |
-| `browser.web_vital.cls` | Histogram | `1` | `vital.metric`、`vital.rating`、`rum.navigation.type`、`view.url_path_group` | webVitals |
-| `browser.web_vital.duration` | Histogram | `ms` | 同上（FCP/INP/LCP/TTFB 靠 `vital.metric` 区分） | webVitals |
-| `browser.view.loading_time` | Histogram | `ms` | `view.url_path_group`、`view.loading_type` | View 管理器，View 结束时记录最终值 |
-| `browser.blank_screen.count` | Counter | - | `view.url_path_group`、`blank_screen.root_selector`、`blank_screen.reason` | blankScreen |
-| `browser.error.count` | Counter | - | `view.url_path_group`、`error.source`、`error.subtype` | error，span 节流前精确累计 |
-| `browser.csp_violation.count` | Counter | - | `view.url_path_group`、`csp.disposition`、`csp.effective_directive` | cspViolation，span 节流前精确累计 |
-| `browser.long_task.count` | Counter | - | `view.url_path_group`、`long_task.entry_type` | longTask |
-| `browser.long_task.duration` | Histogram | `ms` | 同上 | longTask |
-| `browser.long_task.blocking_duration` | Histogram | `ms` | 同上 | longTask，仅 LoAF |
-| `browser.websocket.message.count` | Counter | - | `server.address`、`server.port`、`url.scheme`、`websocket.direction`（in/out） | websocket |
-| `browser.websocket.message.bytes` | Counter | `By` | 同上 | websocket |
-| `browser.websocket.error.count` | Counter | - | `server.address`、`server.port`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
-| `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`server.port`、`url.scheme` | websocket，仅成功建连 |
-
-> 各 metric 只会合并 `context.attributes.metric` hook 返回的自定义低基数维度，不会合并 `context.attributes.page`，也不会携带 `session.id`、`view.id` 或 `action.id`。`view.url_path_group` 中明显的数字 ID、UUID、长十六进制段会归一为 `:id`。精确 View 关联请查询对应 span 或 View Snapshot Log。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
-
-## Log 事件清单
-
-| eventName / body | severity | 来源 | 关键属性 |
-| --- | --- | --- | --- |
-| `session.start` | INFO | session 插件（首次新建） | `session.id`、`session.start_time`、`session.rotate.reason=init` |
-| `session.rotate` | INFO | session 插件（轮换） | + `session.previous_id`、`session.rotate.reason`（`inactivity` / `maxLifetime`） |
-| `browser.view` | INFO | View 管理器 | `view.snapshot.type=create\|update\|final`、`view.document_version`、`view.duration`、`view.is_active`、`view.loading_time` |
-| `browser.request.body` | ERROR（错误请求）/ INFO（`capture: 'all'` 的成功请求） | Fetch/XHR request patch（仅显式配置 `request.body`） | 通过 OTel Log Context 关联 Trace/Span；属性含 `request.body` / `response.body`、`*.body.content_type`、`*.body.truncated` |
-| `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_occurrence_index` |
-| `websocket.close` | INFO | websocket 插件 | `websocket.close.code`、`websocket.close.reason`、`websocket.close.was_clean` |
-
-> 内置 Log 的 `eventName` 与 `body` 当前使用同一个事件名；查询与 `tracking.beforeSend` 应优先使用 `eventName`。
-
-> 错误主数据统一走 `error` span（见 Span 清单），SDK **不再**为同一个错误额外 emit error log，避免重复计数。
-
-## 属性字典
-
-### 归一字段
-
-由 `buildRumSpanAttributes` 等构造器写入，用于跨事件类型统一检索。
-
-| key | 类型 | 说明 | 低基数 |
-| --- | --- | --- | --- |
-| `span_type` | string | `document`/`resource`/`vital`/`error`/`longtask`/`action`/`route`/`custom` | 是 |
-| `span_subtype` | string | 子类型，如 `fetch`/`xhr`/`js`/`promise`/`lcp` | 是 |
-| `result` | string | `success`/`warning`/`error`/`timeout`/`abort` | 是 |
-| `error_type` | string | 错误细分，如 `http_5xx`/`network_timeout`/`slow`/`none` | 是 |
-
-### View / Navigation
-
-| key | 类型 | 出现位置 | 说明 |
-| --- | --- | --- | --- |
-| `view.id` / `view.name` / `view.url` / `view.url_path_group` | string | Span / Log | View 标识、名称、脱敏 URL 与低基数路由模板 |
-| `view.loading_type` | string | Span / Log / Metric | `initial_load` / `route_change` / `session_renewal` / `bf_cache` |
-| `view.loading_time` | number | Span / Log；同时作为 Metric 值 | View 从开始到页面活动稳定的耗时（ms） |
-| `view.loading_time.source` | string | Span / Log | `auto` / `manual` |
-| `view.first_byte` | number | 初始 View Span / Log | Navigation Timing 的 `responseStart`（相对 `performance.timeOrigin`，ms） |
-| `view.dom_interactive` / `view.dom_content_loaded` | number | 初始 View Span / Log | DOM interactive / DOMContentLoaded 时间（相对 `performance.timeOrigin`，ms） |
-| `view.dom_complete` / `view.load_event` | number | 初始 View Span / Log | DOM complete / load event 时间（相对 `performance.timeOrigin`，ms） |
-| `url.previous` | string | Span / Log | 前一个 View URL（已脱敏） |
-| `document.referrer` | string | 初始 View Span / Log | 页面 referrer（已脱敏） |
-| `event.source` | string | Span / Log | View 创建触发源，如 `load`、`pushState`、`popstate`、`manual`、`bfCache`、`sessionRenewal` |
-| `view.end_reason` | string | Span / final Log | 下一 View 的触发源，或 `pagehide` / `session_expired` / `shutdown` |
-| `event.type` | string | Log | 固定 `view` |
-| `view.snapshot.type` | string | Log | `create` / `update` / `final` |
-| `view.document_version` | number | Log | 当前 View Snapshot 的递增版本号 |
-| `view.duration` | number | Log | 从 View 开始到 Snapshot 的耗时（ms） |
-| `view.is_active` | boolean | Log | 非 final Snapshot 为 `true` |
-
-### HTTP / Resource
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `http.request.method` | string | 请求方法（大写） |
-| `http.response.status_code` | number | 响应状态码 |
-| `url.full` | string | 完整 URL（已脱敏） |
-| `server.address` | string | 目标主机名 |
-| `server.port` | number | 目标显式端口（存在时） |
-| `resource.type` | string | `fetch`/`xhr` 或静态资源 initiator type |
-| `resource.redirect.start/duration` | number | 重定向阶段相对开始时间 / 耗时（ms） |
-| `resource.dns.start/duration` | number | DNS 阶段相对开始时间 / 耗时（ms） |
-| `resource.connect.start/duration` | number | TCP 建连阶段相对开始时间 / 耗时（ms） |
-| `resource.ssl.start/duration` | number | TLS 握手阶段相对开始时间 / 耗时（ms） |
-| `resource.first_byte.start/duration` | number | 等待首字节阶段相对开始时间 / 耗时（ms） |
-| `resource.download.start/duration` | number | 响应下载阶段相对开始时间 / 耗时（ms） |
-| `resource.worker.start/duration` | number | Service Worker 阶段相对开始时间 / 耗时（ms） |
-| `resource.delivery_type` | string | `cache` / `navigational-prefetch` 等浏览器交付类型 |
-| `resource.render_blocking_status` | string | `blocking` / `non-blocking` |
-| `resource.size` | number | 传输字节数 |
-| `url.previous` | string | 跳转前 URL |
-| `resource.cache.hit` | boolean | 是否命中缓存 |
-| `resource.protocol` | string | 协议，如 `h2` |
-| `resource.encoded_body_size` / `resource.decoded_body_size` | number | 资源体积 |
-| `request.body` / `response.body` | string | 仅 `browser.request.body` Log；经过接入方 `redact` 且受长度限制 |
-| `request.body.content_type` / `response.body.content_type` | string | body Content-Type（可获取时） |
-| `request.body.truncated` / `response.body.truncated` | boolean | body 是否因长度限制而截断 |
-
-### Web Vitals
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `vital.metric` | string | `cls`/`fcp`/`inp`/`lcp`/`ttfb` |
-| `vital.value` | number | 指标值 |
-| `vital.rating` | string | `good`/`needs-improvement`/`poor` |
-| `vital.id` | string | 单条度量唯一 ID（仅 span） |
-| `rum.navigation.type` | string | 导航类型，含 `back-forward-cache` 等 |
-| `vital.lcp.*` / `vital.cls.*` / `vital.inp.*` / `vital.fcp.*` / `vital.ttfb.*` | mixed | attribution 归因明细（仅 span） |
-
-### 错误 / 异常
-
-以下字段位于 Error Span 顶层属性：
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `exception.message_short` | string | 消息前 80 字符 |
-| `exception.stack_top_frame` | string | 栈顶帧 |
-| `exception.fingerprint` | string | 节流分组指纹（djb2 hash） |
-| `error.source` | string | `window.error`/`unhandledrejection`/`resource`/`csp` |
-| `error.handled` | boolean | 是否被业务捕获（自动采集恒为 `false`） |
-| `error.window_occurrence_index` | number | 当前节流窗口内该已上报 span 的触发序号；总量查询 `browser.error.count` |
-| `error.cross_origin` | boolean | 跨域脚本错误（`Script error.`） |
-| `code.filepath` / `code.lineno` / `code.column` | string/number | JS 错误位置 |
-| `html.tag` | string | 资源错误的元素标签 |
-
-`error.subtype` 仅作为 `browser.error.count` Metric 维度，取值为 `js` / `promise` / `resource_load`，不写入 Error Span 顶层属性。
-
-完整异常由 `recordException()` 写入名为 `exception` 的标准 Span Event，不在 Span 顶层属性中：
-
-| Event 属性 | 类型 | 说明 |
-| --- | --- | --- |
-| `exception.type` | string | 异常类型/名称 |
-| `exception.message` | string | 异常消息 |
-| `exception.stacktrace` | string | 堆栈（存在时） |
-
-### 设备 / 浏览器 / 网络
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `device.id` | string | 匿名设备标识；默认仅当前 SDK 实例稳定，`tracking.device.persistentId=true` 时持久化 |
-| `device.memory_gib` | number | Resource 中的近似设备内存（GiB） |
-| `device.logical_processor_count` | number | Resource 中的逻辑处理器数量 |
-| `browser.viewport.width` / `browser.viewport.height` | number | 视口尺寸 |
-| `browser.screen.width` / `browser.screen.height` | number | 屏幕尺寸 |
-| `network.effective_type` | string | 网络质量，如 `4g` |
-| `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data` | mixed | 网络信息 |
-| `browser.name` / `browser.version` / `os.name` | string | Resource 中的 UA 解析结果 |
-| `device.type` | string | Resource 中的 `mobile` / `desktop` |
-
-### 用户动作 / 会话
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `action.type` | string | 动作类型 |
-| `action.id` | string / string[] | action 自身 ID；关联事件上为 action ID 数组 |
-| `action.name` | string | 可读动作名称 |
-| `action.target.name` | string | 自动 action 的目标元素名称 |
-| `action.target.tag` | string | 自动 action 的目标元素标签 |
-| `action.loading_time` | number | 点击后页面活动稳定耗时（ms） |
-| `action.resource.count` | number | action 关联资源数 |
-| `action.error.count` | number | action 关联错误数 |
-| `action.long_task.count` | number | action 关联长任务数 |
-| `action.frustration.type` | string[] | `rage_click` / `dead_click` / `error_click` |
-| `action.frustration.count` | number | 当前 action 的挫败信号数量 |
-| `session.start_time` | number | 会话开始时间戳 |
-| `session.previous_id` | string | 轮换前的 session.id |
-| `session.rotate.reason` | string | `init`/`inactivity`/`maxLifetime` |
-
-### Long Task
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `long_task.id` | string | 长任务或长动画帧 ID |
-| `long_task.entry_type` | string | `long-animation-frame` / `long-task` |
-| `long_task.start_time` | number | LoAF 相对 `performance.timeOrigin` 的开始时间（ms） |
-| `long_task.duration` / `long_task.blocking_duration` | number | 总耗时 / 主线程阻塞耗时（ms） |
-| `long_task.is_frozen_frame` | boolean | 总耗时是否达到 700ms |
-| `long_task.culprit` | string | 最重脚本 URL、函数或 legacy attribution |
-| `long_task.script.count` | number | LoAF 脚本数 |
-| `long_task.first_ui_event_timestamp` | number | LoAF 首个 UI Event 时间戳 |
-| `long_task.render_start` / `long_task.style_and_layout_start` | number | LoAF 渲染与样式布局阶段起点 |
-| `long_task.culprit.*` | mixed | 最重脚本的耗时、强制布局耗时、函数名与 invoker 类型 |
-| `long_task.script.*` | mixed | `long_task.script` Span Event 上的脚本耗时、URL、函数、invoker 和强制布局归因 |
-
-### CSP
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `csp.blocked_uri` | string | 被拦截资源（URL 类值已脱敏） |
-| `csp.violated_directive` / `csp.effective_directive` | string | 违反的指令 |
-| `csp.disposition` | string | `enforce` / `report` |
-| `csp.source_file` | string | 触发脚本（已脱敏） |
-| `csp.line_number` / `csp.column_number` | number | 位置 |
-| `csp.status_code` | number | 状态码 |
-| `csp.fingerprint` / `csp.window_occurrence_index` | string/number | 节流指纹与该已上报 span 的窗口触发序号 |
-| `csp.original_policy` | string | 完整策略，仅窗口首条携带 |
-
-### WebSocket
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `url.scheme` | string | `ws` / `wss` |
-| `server.address` | string | 目标 hostname，不包含端口 |
-| `server.port` | number | 目标显式端口（存在时） |
-| `network.protocol.name` | string | 固定 `websocket` |
-| `websocket.direction` | string | `in` / `out`（仅 metric） |
-| `websocket.error.phase` | string | `connect` / `runtime` |
-| `websocket.error.window_occurrence_index` | number | 该已上报错误日志在节流窗口内的触发序号；总量查询 `browser.websocket.error.count` |
-| `websocket.close.code` / `websocket.close.reason` / `websocket.close.was_clean` | mixed | 关闭事件详情 |
-
-### 白屏
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `blank_screen.empty_ratio` | number | 有效样本中的空白比例 |
-| `blank_screen.reason` | string | `empty_viewport` / `missing_root` |
-| `blank_screen.root_selector` / `blank_screen.root_found` | string/boolean | 根选择器与是否存在 |
-| `blank_screen.sample_count` / `blank_screen.valid_sample_count` | number | 总样本数 / 有效样本数 |
-| `blank_screen.empty_sample_count` / `blank_screen.ignored_sample_count` | number | 空白样本数 / loading 忽略样本数 |
-| `blank_screen.center_element` | string | 视口中心元素选择器 |
-
-### 自定义事件
-
-| key | 类型 | 说明 |
-| --- | --- | --- |
-| `rum.custom.name` | string | `reportCustomEvent()` 的事件名 |
-| `rum.page.host` / `rum.page.path` | string | 默认 `context.attributes.page` 页面上下文；配置自定义 page hook 后由接入方决定字段 |
+| Span 名 | `event.type` | 关键字段 |
+| --- | --- | --- |
+| `browser.session` | `session` | `event.phase=start\|rotate\|end`、`session.lifecycle.reason`、`session.previous_id` |
+| `browser.view` | `view` | `event.phase=start\|update\|end`、`view.version`、`view.started_at`、`view.loading_type`、`view.loading_time`、`view.end_reason` |
+| `browser.resource` | `resource` | `url.full`、`resource.type`、HTTP 状态、体积和 Resource Timing 阶段 |
+| `browser.error` | `error` | `error.source=window.error`、`error.message`、代码位置；完整异常写入标准 exception event |
+| `browser.unhandledrejection` | `error` | `error.source=unhandledrejection`、`error.message`、标准 exception event |
+| `browser.resource_error` | `error` | `error.source=resource`、`url.full`、`html.tag` |
+| `browser.web_vital` | `vital` | `vital.metric`、`vital.value`、`vital.rating`、`vital.id` 和 attribution |
+| `action.click` | `action` | `action.loading_time`、目标和 `action.frustration.type`；不含资源/错误/长任务计数 |
+| `action.custom` | `action` | 手动 Action 名称和属性 |
+| `browser.blank_screen` | `error` | 白屏采样点、比例、根节点和原因 |
+| `browser.long_task` | `long_task` | Long Task/LoAF 原始耗时与脚本 span event |
+| `csp.violation` | `error` | CSP violation 原始字段；不做指纹或客户端节流 |
+| `browser.websocket` | `websocket` | `event.phase=connect\|open\|error\|close`、`websocket.connection.id`、关闭码；不采集消息 |
+| `custom.<name>` | `custom` | 手动自定义事件属性和可选异常 |
+
+## View 本地语义
+
+`view.loading_time`、CLS、INP、Action Loading Time、挫败信号和白屏必须依赖浏览器活动窗口或 DOM/Performance API，在 SDK 本地计算后作为事件语义上报。View 的每次 start/update/end 都增加 `view.version`；服务端应按 `view.id + view.version` 幂等合并，并容忍乱序到达。
+
+## 服务端派生要求
+
+- 使用 `event.id` 去重。
+- 通过 `session.id`、`view.id`、`action.id` 关联事件。
+- 从原始事件计算 View/Session 时长、资源/错误/Action 数量和错误率。
+- 从 `vital.value`、资源/长任务耗时计算 Histogram 与分位数。
+- 在服务端生成错误指纹、错误组和风暴控制，不在浏览器丢弃原始错误。