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

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

@@ -2,97 +2,189 @@
 
 # 能力矩阵
 
-本页回答四个问题：SDK 能采什么、默认是否启用、依赖哪个浏览器能力、最终上报什么。精确名称与属性请继续查[遥测参考](./telemetry-reference.md)。
-
-## 总览
-
-| 能力 | 配置入口 | 默认 | 浏览器入口 | 原始 RUM Span |
-| --- | --- | --- | --- | --- |
-| Session | `session` | 必选基础能力 | `localStorage`、用户活动、页面可见性 | `browser.session` start/rotate/end |
-| View | `tracking.view` | 自动模式 | Navigation Timing、History、hash、BFCache、DOM Mutation | `browser.view` start/update/end |
-| Fetch/XHR | `tracking.request` | 开 | `fetch`、`XMLHttpRequest`、Resource Timing | `browser.resource` |
-| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` |
-| JS / Promise / 资源错误 | `tracking.error` | 开 | `error`、`unhandledrejection` | 三类 `browser.*error` |
-| Web Vitals | `tracking.webVitals` | 开 | `web-vitals`、Layout Shift、Event Timing | `browser.web_vital` |
-| Action | `tracking.action` | 开 | click、DOM、请求与活动总线 | `action.click` |
-| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` |
-| 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` |
-| 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` |
-| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | Resource 与运行时公共属性 |
-| Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` |
-| WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `browser.websocket` connect/open/error/close |
-| CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` |
-| 自定义插件 | `extensions.plugins` / `use()` | 无 | 由插件决定 | `context.startSpan()` |
-| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | 由 instrumentation 决定 | 支持 |
-
-“默认开”表示获得 Consent 且 SDK 已启动后启用。是否真正导出还受 `enabled`、Session 采样和 Session/View 有效性控制。
-
-## 能力边界
-
-### SDK 直接负责
-
-- 创建和轮换 Session，划分初始加载、SPA、BFCache、手动和 Session 续期 View。
-- 统一 patch Fetch/XHR；请求 span、活动追踪、Trace Header 和 Resource Timing 共用同一生命周期。
-- 把浏览器事件归一为 `span_type`、`span_subtype`、`result`、`error_type` 等字段。
-- 自动为 Span 关联 `session.id`、`view.id` 和 `action.id`。
-- 在 exporter 前执行采样、有效上下文、自上报请求和 `tracking.beforeSend` 过滤。
-
-### SDK 不负责
-
-- 不聚合 `session.duration`、影响用户数、地理信息、Trace 关键路径等后端指标。
-- 不自动判断业务字段是否敏感，也不 hash `user.id`。
-- 不采集 HTTP 请求/响应 Body。
-- 不在浏览器生成 Counter、Histogram、分位数、错误指纹或跨事件计数。
-- 不保证浏览器未暴露的数据，例如缺少 `Timing-Allow-Origin` 的跨域资源网络阶段。
-
-## 默认开启与关闭
+本页用于快速判断：是否默认启用、监听什么浏览器来源、产出什么 Span、在哪些情况下退化。精确算法和字段继续进入对应专题页。
+
+## 总体边界
+
+SDK 只产生原始 RUM Span：
+
+- 一个 `WebTracerProvider`；
+- 一个 OTLP/HTTP JSON 出口 `<endpoint>/v1/rum`；
+- 不创建 Metric/Log Provider；
+- 不在浏览器聚合计数、分位数、直方图或错误指纹；
+- 服务端从原始 Session/View/Action/Resource/Error/Vital Span 派生统计。
+
+普通 Span 必须命中 Session 采样，并关联有效 `session.id` 与 `view.id` 才能导出；Session 生命周期 Span 可以没有 View。
+
+## 全部能力
+
+| 能力 | 配置/API | 默认 | 浏览器来源 | 主要 Span | 详情 |
+| --- | --- | --- | --- | --- | --- |
+| Session | `session` | 基础能力 | localStorage、活动、visibility、storage | `browser.session` | [Session 上下文](./session-context.md) |
+| View / Router | `tracking.view` | auto | Navigation Timing、History、hash、BFCache | `browser.view` | [View 与路由](./views-routing.md) |
+| View Loading Time | `tracking.view.loadingTime` | 开 | 请求/资源/DOM/`window.open` 活动 | `browser.view` update | [View 与路由](./views-routing.md) |
+| Fetch/XHR | `tracking.request` | 开 | fetch、XMLHttpRequest、Resource Timing | `browser.resource` CLIENT | [网络](./network.md) |
+| Trace Header | `allowedTracingUrls` | 无白名单 | W3C Trace Context | 被观测请求的 `traceparent` | [网络](./network.md) |
+| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` CLIENT | [网络](./network.md) |
+| JS Error | `tracking.error` | 开 | window error | `browser.error` | [错误与安全](./errors-security.md) |
+| Promise rejection | `tracking.error` | 开 | unhandledrejection | `browser.unhandledrejection` | [错误与安全](./errors-security.md) |
+| 资源加载错误 | `tracking.error` | 开 | capture error | `browser.resource_error` | [错误与安全](./errors-security.md) |
+| Web Vitals | `tracking.webVitals` | 开 | web-vitals、PerformanceObserver | `browser.web_vital` | [性能体验](./performance.md) |
+| 自动 Action | `tracking.action` | 开 | click、Activity 总线 | `action.click` | [用户操作](./actions.md) |
+| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` | [用户操作](./actions.md) |
+| Custom event | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | [API](./api.md) |
+| Blank Screen | `tracking.blankScreen` | 开 | DOM 九点采样、页面活动 | `browser.blank_screen` | [白屏](./blank-screen.md) |
+| Device | `tracking.device` | 开 | UA/UA-CH、Screen、Network Information | Resource/运行时属性 | [Session 上下文](./session-context.md) |
+| Long Task | `tracking.longTask` | 关 | LoAF 或 Long Tasks | `browser.long_task` | [性能体验](./performance.md) |
+| CSP | `tracking.cspViolation` | 关 | securitypolicyviolation | `csp.violation` | [错误与安全](./errors-security.md) |
+| WebSocket | `tracking.websocket` | 关 | WebSocket constructor/events | `browser.websocket` CLIENT | [网络](./network.md) |
+| RUM Plugin | `extensions.plugins` / `use()` | 无 | 插件决定 | `context.startSpan()` | [扩展](./extensions.md) |
+| OTel Instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | instrumentation 决定 | instrumentation Span | [扩展](./extensions.md) |
+
+“默认开”仍要求 `enabled: true`、Consent 为 granted、SDK 已 start、Session 被采样。浏览器缺少所需 API 时对应插件通常静默降级。
+
+## 默认开关配置展开
+
+以下配置与只传 application/transport 的能力开关等价：
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'capability-demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: {
-    request: true,
-    resource: true,
-    error: true,
-    webVitals: true,
-    action: true,
-    blankScreen: true,
-    device: true,
-    longTask: false,
-    websocket: false,
-    cspViolation: false,
+tracking: {
+  request: true,
+  resource: true,
+  error: true,
+  webVitals: true,
+  action: true,
+  blankScreen: true,
+  device: true,
+  longTask: false,
+  websocket: false,
+  cspViolation: false,
+  view: {
+    tracking: 'auto',
+    loadingTime: true,
   },
-});
+}
 ```
 
-Session 与 View 是导出有效性边界，不提供关闭开关。`tracking.view` 只配置自动/手动模式、稳定耗时和路由分组。
+Session、Activity、Page View 关联基础不提供整体关闭开关。`tracking.view` 可以改 manual，但仍需要 View 才能导出普通 Span。
 
-## 浏览器降级行为
+## Session 与公共上下文
 
-| 条件 | 行为 |
+| 项目 | 当前行为 |
 | --- | --- |
-| 无 `PerformanceObserver` 或不支持 `resource` | 跳过静态资源观察和请求网络阶段匹配；Fetch/XHR 本身仍可采集 |
-| 不支持 Long Animation Frames | Long Task 插件尝试回退 Long Tasks API |
-| 两种 Long Task API 都不支持 | 跳过 Long Task，不抛出业务异常 |
-| 跨域资源无 `Timing-Allow-Origin` | 只保留浏览器可见的总耗时/体积，不伪造网络阶段 |
-| 无 Network Information / UA-CH | 只写入可获得的设备字段 |
-| 无 `localStorage` 或访问失败 | Session/Device 持久化退回内存 |
-| 插件初始化抛错 | 隔离该插件；`debug: true` 时输出 warning，其余插件继续启动 |
+| 无活动超时 | 固定 15 分钟 |
+| 最大生命周期 | 固定 4 小时 |
+| 跨 Tab | localStorage + storage event |
+| 存储失败 | 回退进程内存 |
+| 采样 | `application.name + session.id` 稳定 hash |
+| 用户 | 业务传 `user.id`，原样透传 |
+| 设备 ID | 默认每次 Device 插件初始化生成；可选持久化 |
 
-## 成本与隐私提示
+Session Span 包括 start/rotate/end；View、Action、Resource 等通过 ID 属性关联，不要求它们共享同一个 Trace。
 
-| 能力 | 主要成本/风险 | 建议 |
+## View 与页面体验
+
+View 类型：
+
+- `initial_load`：首屏；
+- `route_change`：SPA/手动 route；
+- `bf_cache`：BFCache 恢复；
+- `session_renewal`：Session 轮换后重建 View。
+
+每个 View 产生 start/update/end 生命周期 Span，`view.version` 递增。Loading Time 等待页面活动安静后更新；隐藏页面会取消当前自动计算，业务可用 `setViewLoadingTime()` 手动确认。
+
+自动 mode 不因 query-only 改变创建 View。默认 path group 只是 pathname，不会自动模板化动态 ID。
+
+## 网络与资源
+
+Fetch/XHR 插件统一负责：
+
+- 建 `browser.resource` CLIENT Span；
+- 请求结果和 HTTP status；
+- 可选 W3C `traceparent`；
+- 与 Resource Timing 在最多 200ms 内匹配；
+- 向 View/Action activity 通知开始与结束。
+
+静态资源插件消费 Resource PerformanceEntry。跨域没有 `Timing-Allow-Origin` 时，只发送浏览器能看到的字段，不猜测 DNS/TCP/TLS。
+
+WebSocket 仅记录 connect/open/error/close，不记录 message、payload、数量或字节。
+
+## 错误与安全
+
+自动 Error 会记录：
+
+- 归一 Span 分类和 ERROR status；
+- error message/source/handled；
+- 可用时 exception type/message/stack；
+- JS 行列/文件或资源 URL/tag。
+
+SDK 不做错误节流、fingerprint 和分组。CSP 插件每次 violation 建原始 Span，可能产生高事件量并包含原始策略。
+
+## Web Vitals 与 Long Task
+
+Vitals：CLS、FCP、INP、LCP、TTFB。每个指标保留 value、rating 和浏览器可提供的 attribution。CLS 和 INP 按当前 View 聚合边界定稿，不是全站一个永久累计值。
+
+Long Task 优先 Long Animation Frame 获取脚本归因，不支持时回退 Long Tasks。默认关闭，threshold 默认 50ms。
+
+## Action 与白屏
+
+Action 以点击后的副作用窗口建模，关联请求、DOM、错误和页面活动。可识别：
+
+- rage click：短时间相近位置的点击链；
+- error click：Action 窗口内出现错误；
+- dead click：没有有效副作用且满足排除条件。
+
+默认只从显式 data attribute 命名，不读取任意 DOM 文本。
+
+白屏在页面活动稳定后，对视口九点采样并连续确认两次；每个 View 最多上报一次。它是启发式检测，不适合所有 Canvas/iframe/非常规布局。
+
+## 浏览器降级矩阵
+
+| 缺失/限制 | 降级结果 |
+| --- | --- |
+| `PerformanceObserver` 不支持 resource | Fetch/XHR 基础 Span仍可有；资源时序和静态资源跳过 |
+| Long Animation Frame 不支持 | 尝试 Long Tasks API |
+| 两种长任务 API 都不支持 | 不产生 Long Task，不阻断页面 |
+| Event Timing/指标 API 不支持 | 对应 Vital 缺失，不伪造 |
+| 跨域资源无 TAO | 详细 timing/size 可能缺失 |
+| Network Information 不支持 | network.* 运行时字段缺失 |
+| UA-CH 不支持 | 回退 userAgent 解析 |
+| localStorage 抛错 | Session/Device 持久化退回内存 |
+| `elementsFromPoint` 不支持 | 白屏使用单个 `elementFromPoint` |
+| 插件 init 抛错 | 隔离插件；debug 模式警告 |
+| 页面快速退出 | flush/keepalive 尽力发送，不保证交付 |
+
+## SDK 明确不提供
+
+- HTTP request/response Body；
+- WebSocket message；
+- OpenTelemetry Metric/Log；
+- 客户端 Counter/Histogram/分位数；
+- IP、geo、ASN；
+- 错误 fingerprint/group；
+- Session replay；`session.has_replay` 当前固定 false；
+- 自动 user.id hash；
+- 自动动态路由识别；
+- 离线持久队列和 exactly-once 交付；
+- 服务端 trace 聚合、留存、权限与删除。
+
+## 成本和风险选择
+
+| 入口 | 主要影响 | 建议 |
 | --- | --- | --- |
-| `session.sampleRate` | 决定 RUM Span 总体数据量 | 按应用容量设置；排障临时设为 `1` |
-| Action 文本命名 | DOM 文本可能包含用户输入 | 保持 `nameCollection: 'explicit'`，关键元素使用 `data-bk-action-name` |
-| Device 持久 ID | 支持跨 Session 关联 | 默认不持久化；需取得合规依据后再开启 |
-| Long Task | 产生 Span 与脚本归因信息 | 仅性能分析场景开启，结合采样控制 |
-| WebSocket | Proxy 全局构造器并监听连接生命周期 | 不包裹 `send()`，不采集消息内容、数量或字节数 |
-
-## 下一步
-
-- 配置每项能力：[配置参考](./configuration.md)
-- 理解启动与上报链路：[架构与数据流](./architecture.md)
-- 查看单个插件实现行为：[插件总览](./plugins.md)
-- 查看精确遥测名称和属性：[遥测参考](./telemetry-reference.md)
+| `session.sampleRate` | 全局 Span 量 | 先测平均 Span/Session，再定比例 |
+| `resource` | 页面资源多时事件量大 | 通常保留；用服务端采样/聚合 |
+| `longTask` | 卡顿高时大量事件和脚本字段 | 问题驱动、小流量开启 |
+| `cspViolation` | 策略异常时事件风暴 | 先评估并脱敏 original policy |
+| `websocket` | 全局构造器 patch、长连接 | 只在连接可观测确有需求时开 |
+| Action `text` | DOM 文本隐私 | 保持 explicit，使用稳定 data name |
+| Device persistent ID | 跨 Session 关联 | 需 Consent/存储政策支持 |
+| traceparent | CORS 与第三方泄露 | 精确 allowlist |
+
+## 阅读路径
+
+- 想先跑起来：[快速上手](./getting-started.md)
+- 准备上线：[生产接入指南](./production.md)
+- 查全部配置：[配置参考](./configuration.md)
+- 查 Span 和字段：[遥测字段字典](./telemetry-reference.md)
+- 理解内部流程：[架构与数据流](./architecture.md)