@blueking/open-telemetry 0.0.20 → 0.0.21

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

@@ -60,486 +60,3 @@ new BkOpenTelemetry({
 - 需要为请求增加业务字段或过滤请求：配置 `request.beforeSend` / `request.excludedUrls`。
 - 需要分析 CSP：开启 `cspViolation`。
 - 需要分析实时通信：开启 `websocket`，注意避免多个 SDK 实例重复 patch。
-
-# 基础采集插件
-
-基础插件负责建立 RUM 数据的关联上下文：哪个用户、哪个会话、哪个页面、哪个设备。
-
-以下片段聚焦对应的 `session` 或 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
-
-## session
-
-`session` 维护 `session.id`，并在会话开始和轮换时写入 log。它是所有 RUM 信号的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
-
-默认规则：
-
-- 不活跃超过 15 分钟后过期，下一次用户交互时轮换。
-- 会话最长 4 小时。
-- storage key 会按 endpoint host 隔离。
-- 页面重新可见只续期有效会话，不会复活已过期会话。
-- 跨 Tab 共享持久化状态，但已过期的 Tab 需要自身发生用户交互后才接管新会话。
-
-```ts
-new BkOpenTelemetry({
-  session: {
-    storageKey: 'bk-rum-session',
-  },
-});
-```
-
-超时固定为 15 分钟无活动、4 小时最长生命周期，不开放配置。过期会结束当前 View、刷新旧 session 的待发送数据，并丢弃此后所有不带有效 `session.id` 的 span/log/metric；下一次用户交互续期时，同时创建新的 Session 和 View。Metric 使用 DELTA temporality，避免累计值跨 session 重复上报。
-
-**产出遥测**：log `session.start` / `session.rotate`，并维护运行时属性 `session.id`。
-
-## device
-
-`device` 插件采集设备、浏览器、系统、视口和网络信息。默认开启。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    device: {
-      persistentId: true,
-      storageKey: 'bk-rum-device',
-    },
-  },
-});
-```
-
-稳定的浏览器、系统和硬件能力写入三类信号共享的 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 span/log 会自动携带，便于按浏览器、系统、网络类型下钻。
-
-`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。
-
-## View
-
-View 管理器负责初始页面、SPA 路由、手动 View、BFCache 和 Session 续期。它与 Session 一样不可关闭，并维护：
-
-- `view.id`
-- `view.name`
-- `view.url`
-- `view.url_path_group`
-- `view.loading_type`
-- `view.loading_time`
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    view: {
-      tracking: 'auto',
-      loadingTime: true,
-      excludedActivityUrls: [/\/events\/stream$/],
-      getPathGroup: url => {
-        const { pathname } = new URL(url, window.location.href);
-        return pathname.replace(/\/\d+/g, '/:id');
-      },
-    },
-  },
-});
-```
-
-自动模式只在 pathname 或非锚点 hash path 变化时切换 View；query-only 和页内锚点变化不会切换。手动模式使用 `view.tracking: 'manual'`，并调用 `startView({ name, url, attributes })`。
-
-```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'order-web' },
-  autoStart: false,
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: { view: { tracking: 'manual' } },
-});
-
-await bkOT.start();
-bkOT.startView({
-  name: '订单详情',
-  url: window.location.href,
-  attributes: { 'biz.owner': 'order-team' },
-});
-bkOT.setViewName('订单详情-只读');
-```
-
-`view.id` 始终由 SDK 生成，`attributes` 不能覆盖 Session/View 等保留字段。普通 span/log 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路；metric 只保留 `view.url_path_group` 等低基数维度，不携带唯一 `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.*` 运行时属性。
-
-## action
-
-`action` 插件默认开启。它自动监听 click，观察交互后的请求、DOM 变更、资源、错误和长任务，在页面活动稳定后生成一个 `action` span。
-
-**产出遥测**：span `action.<type>`（如 `action.click`，`span_type=action`）。`reportAction()` 走同一套字段。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    action: {
-      actionNameAttribute: 'data-bk-action-name',
-      maxDuration: 10000,
-      nameCollection: 'explicit',
-    },
-  },
-});
-```
-
-自动命名在默认 `explicit` 模式只向上查找 `data-bk-action-name`；没有显式名称时退回目标元素标签名。设置 `nameCollection: 'text'` 后才会继续读取 label、按钮值、`aria-label`、`alt`、`name`、`title`、`placeholder` 和 DOM 文本，并自行评估隐私风险。
-
-对关键业务动作，推荐使用 `reportAction()` 显式上报，字段更稳定。
-
-```ts
-bkOT.reportAction({
-  name: '立即支付',
-  attributes: {
-    'biz.order_id': '202605270001',
-  },
-});
-```
-
-# 体验与性能插件
-
-体验类插件关注页面加载、资源、核心 Web 指标、空白屏、主线程阻塞和 SPA 路由切换。
-
-以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
-
-## resource
-
-`resource` 插件默认开启，基于 PerformanceObserver 采集静态资源加载 span。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    resource: true,
-  },
-});
-```
-
-常见字段包括 `resource.type`、`resource.size`、`resource.protocol`、`url.full`、`server.address`。当 Resource Timing 数据可用时，还会上报：
-
-- `resource.redirect.*`、`resource.dns.*`、`resource.connect.*`、`resource.ssl.*`
-- `resource.first_byte.*`、`resource.download.*`、`resource.worker.*`
-- `resource.delivery_type`、`resource.render_blocking_status`
-
-每个网络阶段同时包含相对资源开始时刻的 `start` 与阶段 `duration`，单位均为 ms。跨域资源没有返回 `Timing-Allow-Origin` 时，浏览器不会暴露完整阶段数据，SDK 会保留资源总耗时，但不生成不可信的阶段字段。
-
-**产出遥测**：span `browser.resource`（`span_type=resource`）。
-
-## action 与挫败信号
-
-`action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time` 和子事件数量。
-
-自动点击还会判断三类挫败信号：
-
-- `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。三次点击合并为一条 action。
-- `dead_click`：点击后没有页面活动、输入、滚动或文本选择；文本输入、链接、select、textarea、canvas、contenteditable 等无法可靠判断的元素会排除。
-- `error_click`：点击活动窗口内产生前端错误。
-
-信号写入 `action.frustration.type`（string[]）和 `action.frustration.count`。为了完成连续点击判断，action span 最多延迟 1 秒创建；`action.id` 只在真实页面活动窗口内挂到关联事件上，不会因为这个上报等待期延长。
-
-## 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` 定位具体页面和归因信息。
-
-**产出遥测**：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 归因）。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    webVitals: true,
-  },
-});
-```
-
-## blankScreen
-
-`blankScreen` 插件默认开启。它会针对每个 View 等待页面活动稳定后执行九点分层采样；只有两次连续检测都超过阈值才上报。View 切换或页面隐藏会取消旧检测，恢复可见后重新调度。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    blankScreen: {
-      rootSelector: '#app',
-      checkDelay: 1000,
-      confirmationDelay: 200,
-      threshold: 0.8,
-      ignoreSelectors: ['.global-loading', '.skeleton'],
-    },
-  },
-});
-```
-
-SPA 应用建议配置 `rootSelector`。根节点在确认阶段仍不存在时会以 `missing_root` 原因上报；loading 和骨架屏样本不进入空白比例分母。
-
-**产出遥测**（仅判定为白屏时）：metric `browser.blank_screen.count` + error span `browser.blank_screen`（`span_type=error`）。
-
-## longTask
-
-`longTask` 插件默认关闭。开启后优先通过 Long Animation Frames API 采集主线程阻塞；浏览器不支持时自动回退到 Long Tasks API，两种入口不会重复观察。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    longTask: {
-      threshold: 50,
-      warningThreshold: 100,
-    },
-  },
-});
-```
-
-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`）。
-
-## View Loading Time
-
-View Loading Time 属于 View 管理器，默认启用，基于页面活动结束时间计算。
-
-自动计算规则：
-
-- 初始加载：取 `navigationStart → loadEventEnd` 与 `navigationStart → 页面活动结束` 的较大值。
-- SPA 路由：取 View 创建到页面活动结束的耗时。
-- Fetch/XHR 进行中、静态资源完成和 DOM Mutation 都属于活动；连续 100ms 无活动视为稳定。
-- SDK 自身上报、`view.excludedActivityUrls` 命中的请求，以及 `data-bk-excluded-activity-mutations` 节点下的 DOM 变更不参与计算。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    view: {
-      loadingTime: true,
-      excludedActivityUrls: [/\/events\/stream$/, '/analytics'],
-    },
-  },
-});
-```
-
-如果业务有明确的异步渲染完成点，可覆盖自动结果：
-
-```ts
-await loadAlarmDetail();
-bkOT.setViewLoadingTime();
-```
-
-# 错误与安全插件
-
-以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
-
-错误类插件帮助定位 JavaScript 异常、Promise 异常、资源加载失败、CSP 违规和空白屏等问题。
-
-## error
-
-`error` 插件默认开启，监听：
-
-- `window.error`
-- `unhandledrejection`
-- 资源加载错误
-
-插件会生成 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` 记录。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    error: {
-      maxPerWindow: 5,
-      windowMs: 60_000,
-    },
-  },
-});
-```
-
-## 手动上报错误事件
-
-业务捕获到错误后，可以通过 `reportCustomEvent()` 上报。
-
-```ts
-try {
-  await submitOrder();
-} catch (error) {
-  bkOT.reportCustomEvent({
-    name: 'submit_order_failed',
-    error: error instanceof Error ? error : new Error(String(error)),
-    attributes: {
-      'biz.order_id': '202605270001',
-    },
-  });
-}
-```
-
-## cspViolation
-
-`cspViolation` 插件默认关闭。开启后监听浏览器 `securitypolicyviolation` 事件，并写入 error span。
-
-**产出遥测**：span `csp.violation`（`span_type=error`），带 `csp.*` 字段；完整策略 `csp.original_policy` 仅在节流窗口首条携带。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    cspViolation: true,
-  },
-});
-```
-
-建议与站点 CSP 响应头一起使用。
-
-```http
-Content-Security-Policy: default-src 'self'; report-uri /csp-report
-```
-
-## blankScreen 与错误排查
-
-空白屏通常是错误、资源失败或首屏渲染失败的结果。建议同时开启 `blankScreen`、`error`、`resource`。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    blankScreen: {
-      rootSelector: '#app',
-    },
-    error: true,
-    resource: true,
-  },
-});
-```
-
-通过 `view.id` 和 `session.id` 可以把空白屏、JS 错误、资源失败关联到同一次页面访问。
-
-# 网络与扩展插件
-
-网络能力覆盖 Fetch/XHR 与 WebSocket。两者都会 patch 浏览器全局 API，同一页面只应运行一个 SDK 实例。
-
-以下片段聚焦 `tracking`，实际初始化仍需提供 `application.name` 和有效 Transport。
-
-## Fetch/XHR request
-
-`tracking.request` 默认开启。当前实现由 SDK 自己统一 patch `window.fetch` 与 `XMLHttpRequest.prototype.open/send`，不使用官方 Fetch/XHR instrumentation，也不会为同一请求叠加两套生命周期。
-
-### 请求生命周期
-
-一次请求按以下顺序处理：
-
-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。
-
-**产出遥测**：Span `browser.resource`，`span_type=resource`、`resource.type=fetch|xhr`，常用属性包括 `http.request.method`、`http.response.status_code`、`url.full`、`server.address`、网络阶段与响应体积。
-
-```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;
-      },
-    },
-  },
-});
-```
-
-`request.beforeSend` 在请求完成后执行，可修改 Span attributes；返回 `false` 会标记该 Span 在最终 processor 中丢弃，并立即跳过该请求的 Body Log。Hook 抛错不会中断业务请求，`debug: true` 时输出 warning。
-
-### 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)。

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

@@ -9,7 +9,7 @@
 ## 命名规则
 
 - **信号名**：`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`。
+- **属性 key**：标准字段与 RUM 领域字段均使用点号命名空间（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。公共与跨插件字段常量集中定义在 `src/schema/attributes.ts`，插件私有字段在对应插件内定义。
 
 ## 公共 Resource 与运行时上下文属性
 
@@ -42,21 +42,21 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 
 ## Span 清单
 
-| span 名 | span_type | 来源 | 关键属性 | 备注 |
-| --- | --- | --- | --- | --- |
-| `browser.view` | `document` / `route` | View 管理器 | `view.name`、`view.loading_time`、`view.loading_time.source`、`url.previous`、`event.source`、`view.end_reason` | 有持续时间，下一次 View 或 pagehide 时结束 |
-| `browser.resource` | `resource` | Fetch/XHR request 采集 | `resource.type=fetch\|xhr`、`url.full`、`http.request.method`、`http.response.status_code`、网络阶段属性 | span kind 为 CLIENT；Fetch/XHR 共用同一实现 |
-| `browser.resource` | `resource` | resource 插件 | `resource.type`、`url.full`、`resource.size`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
-| `browser.web_vital` | `vital` | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
-| `browser.blank_screen` | `error` | 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` | 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` | error 插件（Promise 异常） | `exception.fingerprint`、`error.source=unhandledrejection` | 完整异常写入标准 `exception` Span Event |
-| `browser.resource_error` | `error` | error 插件（资源加载失败） | `exception.fingerprint`、`error.source=resource`、`url.full`、`html.tag` | 完整异常写入标准 `exception` Span Event |
-| `browser.long_task` | `longtask` | 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` | 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` | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`network.protocol.name=websocket` | 长连接生命周期不绑定 span |
-| `action.click` / `action.custom` | `action` | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
-| `custom.<name>` | `custom` | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时记录 exception、设置错误 Status/Result，`span_type` 仍为 `custom` |
+| 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 清单
 
@@ -71,16 +71,16 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | `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`、`url.scheme`、`websocket.direction`（in/out） | websocket |
+| `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`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
-| `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`url.scheme` | 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 事件清单
 
-| body | severity | 来源 | 关键属性 |
+| 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`） |
@@ -89,6 +89,8 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | `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，避免重复计数。
 
 ## 属性字典
@@ -104,6 +106,27 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | `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 | 类型 | 说明 |
@@ -145,12 +168,11 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 
 ### 错误 / 异常
 
+以下字段位于 Error Span 顶层属性：
+
 | key | 类型 | 说明 |
 | --- | --- | --- |
-| `exception.type` | string | 异常类型/名称 |
-| `exception.message` | string | 异常消息 |
 | `exception.message_short` | string | 消息前 80 字符 |
-| `exception.stacktrace` | string | 堆栈 |
 | `exception.stack_top_frame` | string | 栈顶帧 |
 | `exception.fingerprint` | string | 节流分组指纹（djb2 hash） |
 | `error.source` | string | `window.error`/`unhandledrejection`/`resource`/`csp` |
@@ -160,6 +182,16 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | `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 | 类型 | 说明 |
@@ -169,6 +201,7 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | `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` |
@@ -203,7 +236,9 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | `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
@@ -224,7 +259,8 @@ Resource 属性由三类信号共享；运行时上下文属性自动挂到**几
 | key | 类型 | 说明 |
 | --- | --- | --- |
 | `url.scheme` | string | `ws` / `wss` |
-| `server.address` | string | 目标 host |
+| `server.address` | string | 目标 hostname，不包含端口 |
+| `server.port` | number | 目标显式端口（存在时） |
 | `network.protocol.name` | string | 固定 `websocket` |
 | `websocket.direction` | string | `in` / `out`（仅 metric） |
 | `websocket.error.phase` | string | `connect` / `runtime` |