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

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

@@ -2,60 +2,162 @@
 
 # 架构与数据流
 
-SDK 只负责采集浏览器事实和必须在浏览器本地完成的体验语义计算，所有数据统一编码为 RUM Span，通过 `<transport.endpoint>/v1/rum` 上报。
+本页解释 SDK 从构造、启动、采集到导出的完整路径。它面向需要理解运行机制、排查数据缺失或开发扩展插件的读者；配置字段见[配置参考](./configuration.md)，上报字段见[遥测字段字典](./telemetry-reference.md)。
 
-## 模块边界
+## 设计边界
 
-| 模块 | 职责 |
+SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、错误、Web Vitals、Action 等浏览器事件都编码为 Span，经唯一的 OTLP/HTTP 通道发送到 `<transport.endpoint>/v1/rum`。
+
+浏览器端负责：
+
+- 从浏览器 API 读取单次事件事实；
+- 建立 Session、View、Action 关联；
+- 计算必须依赖浏览器状态的 View/Action Loading Time、CLS、INP、挫败信号和白屏结果；
+- 完成 Session 采样、URL/属性脱敏、过滤和发送。
+
+浏览器端不负责：
+
+- 创建 Metric 或 Log Provider；
+- 计算跨事件 Counter、Histogram、分位数或错误率；
+- 生成错误指纹、错误组、地理信息或影响用户数；
+- 采集请求或响应 Body；
+- 保存 Session Replay 或 Browser Profile。
+
+## 模块职责
+
+| 模块 | 主要职责 |
 | --- | --- |
-| `core/config.ts` | 配置校验、Endpoint、Hook、Resource 属性 |
-| `core/sdk.ts` | TracerProvider、Exporter、生命周期和公开 API |
-| `core/runtime-context.ts` | User/Session/View/Action 当前快照与历史归属 |
-| `core/processor.ts` | 采样、上下文、自上报和 beforeSend 过滤 |
-| `plugins/` | 浏览器原始事件采集与本地体验语义 |
-| `schema/` | RUM 字段和 Span 分类 |
+| `core/config.ts` | 输入校验、默认值、Endpoint、Resource 属性与 Hook |
+| `core/sdk.ts` | Provider、Exporter、Processor、公开 API 和 SDK 生命周期 |
+| `core/runtime-context.ts` | User、Session、View、Action 当前快照与历史归属 |
+| `core/plugin.ts` | 插件契约、顺序启动、并行 flush、反向 shutdown |
+| `core/processor.ts` | 上下文补齐、自上报过滤、有效性过滤和 `beforeSend` |
+| `core/sampling.ts` | Session 级确定性采样 |
+| `core/page-activity.ts` | View Loading Time 共用的页面活动稳定判断 |
+| `core/action-activity.ts` | 请求、资源、DOM、错误、Long Task 等活动总线 |
+| `plugins/*.ts` | 浏览器 API 监听、事件归一和单项体验语义 |
+| `schema/*.ts` | RUM 公共字段、Span 类型和结果分类 |
+
+## 构造阶段
+
+`new BkOpenTelemetry(options)` 会同步完成以下工作：
+
+1. `resolveConfig()` 校验 `application.name` 和 `transport.endpoint`。
+2. 解析应用、传输、采样、Hook 和默认配置。
+3. 创建 OpenTelemetry Resource；默认 Device 开启时会在此同步读取 UA、OS、内存和逻辑处理器快照，这一步早于 Consent 插件生命周期。
+4. 创建 `OTLPTraceExporter`，目标固定为 `<endpoint>/v1/rum`。
+5. 按 `transport.processor` 创建 `BatchSpanProcessor` 或 `SimpleSpanProcessor`。
+6. 在外层包裹 `FilteringSpanProcessor`。
+7. 创建带 `RumSessionSampler` 的 `WebTracerProvider`。
+8. 创建空的 `RumRuntimeContext`；此时尚无有效 `session.id` 和 `view.id`。
+
+构造阶段不会同步安装 Fetch/XHR Patch 或事件监听。`autoStart` 默认为 `true`，构造函数会异步调用 `start()`；需要严格控制启动时机、Consent、Plugin 或 Instrumentation 注册时，应使用 `autoStart: false` 并显式 `await start()`。
+
+## 启动顺序
+
+获得 Consent 且 `enabled=true` 时，插件严格按以下顺序初始化：
+
+1. `session`：创建或恢复 Session，计算当前 Session 采样决定。
+2. `device`：写入设备、视口和网络上下文。
+3. `activity`：安装 DOM Mutation 页面活动观察器。
+4. `page-view`：建立初始或手动 View。
+5. `resource`：观察 Resource Timing；Fetch/XHR Entry 只用于回填请求 Span。
+6. `request`：Patch Fetch/XHR，负责请求 Span、Trace Header 和活动计数。
+7. `error`。
+8. `web-vitals`。
+9. `blank-screen`。
+10. `action`。
+11. 按配置启用 `websocket`、`long-task`、`csp-violation`。
+12. 初始化 `extensions.plugins`。
+13. 所有插件完成后注册 `extensions.instrumentations`。
+
+这个顺序保证大多数采集插件启动前已经存在 Session 和 View。单个插件初始化失败会被隔离：失败插件不会加入已启动列表；`debug: true` 时输出 warning，其余插件继续启动。
+
+## SDK 生命周期状态
+
+实例内部状态为 `idle → starting → started → stopped`：
+
+- 重复调用 `start()` 不会重复安装插件。
+- `enabled=false` 时 `start()` 进入 `started`，但不启动采集。
+- `shutdown()` 幂等；完成后 Provider 已销毁，同一实例不能重新启动。
+- `use()` 和 `useInstrumentation()` 只能在 `idle` 状态调用。
+- `setTrackingConsent()` 可以在 `started` 状态停止或重新启动采集插件。
+
+`shutdown()` 会按启动顺序的反方向关闭插件，再刷新并关闭 Trace Provider。插件因此必须在 `shutdown()` 中释放自己创建的监听、Observer、Timer、Patch 和未结束 Span。
+
+## 一条事件的处理链路
+
+内置插件生成事件时，公共路径如下：
+
+1. 从 DOM Event、Performance Entry、网络回调或业务调用中取得真实发生时间。
+2. 使用当前时间或 `getRuntimeAttributesAt(timestamp)` 查找事件发生时的 Session、View、Action。
+3. 写入 `span_type`、`outcome.*` 及对应领域字段，事件时间直接使用 Span start/end。
+4. 通过 `context.startSpan()` 创建 Span，并应用 `privacy.redactAttributes`。
+5. OpenTelemetry Provider 在 Span 创建时执行 Session sampler。
+6. `FilteringSpanProcessor.onStart()` 只补充 Span 尚未显式提供的运行时属性。
+7. Span 结束后，Processor 检查采样、Session/View、内部丢弃标记和自上报 URL。
+8. 执行 `tracking.beforeSend`；返回 `false` 时丢弃。
+9. 进入 Batch 或 Simple Processor。
+10. Exporter 序列化为 OTLP/HTTP JSON，通过 Fetch POST 到 `/v1/rum`。
+
+详细 HTTP 行为见[上报协议、批处理与采样](./transport-sampling.md)。
+
+## 运行时上下文
+
+`RumRuntimeContext` 保存后续 Span 自动继承的属性：
+
+- `user.id`
+- `session.id`、`session.start_time`、`session.type`、`session.has_replay`
+- `view.id`、`view.name`、`view.url`、`view.url_path_group`、`view.loading_type`
+- 活动窗口内的 `action.id`
+- Device 插件产生的视口、屏幕、网络和设备 ID
+- View 自定义属性
 
-SDK 不创建 `MeterProvider`、`LoggerProvider`、Metric Reader 或 Log Processor。
+`context.attributes.page` 不是持久运行时快照；内置插件在创建具体 Span 时读取，Instrumentation 则由 Processor 的补齐函数在 onStart 时读取。
 
-## 生命周期
+上下文不仅保存当前值，还保留最多 100 个 Session、View、Action 生效区间。PerformanceObserver 可能在事件结束后才回调，插件可以按事件真实时间回查历史上下文，避免把旧页面的 Resource、Vital 或 Long Task 归到新 View。
 
-构造时只创建 Resource、TracerProvider、OTLP Trace Exporter 和运行时上下文。获得 Consent 后，插件依次建立 Session、View、请求、资源、错误、Vitals、Action 等采集。`flush()` 刷新插件和 Trace Provider；`shutdown()` 反向关闭插件并关闭 Trace Provider。
+## Span 导出条件
 
-## 原始事件模型
+普通 Span 必须同时满足：
 
-公共流程：
+- 当前 SDK `enabled=true`；
+- Session 命中 `session.sampleRate`；
+- Span 带有效 `session.id`；
+- Span 带有效 `view.id`；
+- 不是 SDK 自身 `/v1/rum` 请求；
+- 未被请求级 `beforeSend` 标记丢弃；
+- 未被全局 `tracking.beforeSend` 丢弃。
 
-1. 插件读取浏览器事件的真实时间。
-2. 按事件时间关联 `session.id`、`view.id`、`action.id`。
-3. 写入唯一 `event.id`、`event.type`、`event.timestamp`。
-4. 创建 RUM Span，应用 URL/属性脱敏。
-5. FilteringSpanProcessor 校验采样和有效上下文，执行 `tracking.beforeSend`。
-6. 通过 `/v1/rum` 批量上报。
+`browser.session` 生命周期 Span 是例外：它允许只有采样有效的 `session.id`，因为 Session start 可能早于 View 创建，Session end 可能发生在 View 已清理之后。
 
-Session 和 View 使用显式生命周期事件：
+## OpenTelemetry 全局对象
 
-- `browser.session`：`event.phase=start|rotate|end`。
-- `browser.view`：`event.phase=start|update|end`，并携带单调递增的 `view.version`。
-- `browser.websocket`：`event.phase=connect|open|error|close`，通过 `websocket.connection.id` 关联。
+SDK 使用 `ZoneContextManager` 和 `W3CTraceContextPropagator`。它们是页面级全局对象，多个 SDK 实例通过引用计数共享，最后一个实例退出时才释放。
 
-Session 生命周期允许只有 `session.id`；其他普通事件必须同时归属有效 Session 和 View。
+这不代表推荐多个实例。Fetch、XHR、WebSocket 和全局事件监听仍可能被多实例重复安装；同一页面应只运行一个 SDK 实例，微前端由主应用统一持有。
 
-## SDK 与服务端分工
+## Flush 时机
 
-SDK 保留浏览器端才可靠的计算：CLS、INP、Action Loading Time、View Loading Time、挫败信号和白屏判断。
+`flush()` 先并行调用已启动插件的 `flush()`，再调用 Trace Provider `forceFlush()`。SDK 自动在以下时机尽力刷新：
 
-服务端负责：
+- `window.pagehide`
+- `document.visibilityState` 变为 `hidden`
+- Session 过期并结束旧生命周期
+- 撤销 Tracking Consent
+- `shutdown()`
 
-- View/Session 时长、事件计数、错误率、吞吐量；
-- Counter、Histogram、P50/P75/P95/P99；
-- 错误指纹、分组和风暴控制；
-- 采样率修正、乱序/迟到事件合并；
-- 基于 `event.id` 去重，基于 `view.id + view.version` 幂等更新。
+页面生命周期触发的 flush 是尽力而为，不等于浏览器一定完成网络发送。关键业务流程可以显式 `await bkOT.flush()`。
 
-## 请求采集
+## SDK 与服务端契约
 
-Fetch/XHR 由 SDK 单层 patch：创建 `browser.resource` CLIENT Span、可选注入 `traceparent`、关联 Resource Timing，并通过活动总线参与 View/Action Loading Time。`excludedUrls` 完全排除请求，`request.beforeSend` 可修改或丢弃请求 Span。SDK 不读取请求或响应 Body。
+服务端至少需要：
 
-## 隐私与扩展
+- 以 `traceId + spanId` 去重；
+- 以 `session.id`、`view.id`、`action.id` 关联事件；
+- 以 `view.id + view.version` 幂等合并 View start/update/end；
+- 容忍网络批处理导致的乱序和迟到；
+- 使用 `session.sample_rate` 修正聚合；
+- 从原始 Span 派生计数、分布、分位数和错误分组。
 
-`privacy.redactUrl` 处理 URL，`privacy.redactAttributes` 处理 Resource 和 SDK Span，`tracking.beforeSend` 是导出前最终兜底。自定义 RUM 插件使用 `context.startSpan()`；SDK 不提供 `meter`、`logger` 或 `emitLog()`。
+字段分层和服务端派生边界见[RUM 数据模型](./data-model.md)。

package/skills/bk-rum-otele/references/blank-screen.md

@@ -0,0 +1,190 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 白屏检测
+
+Blank Screen 插件用固定成本的视口九点采样判断页面是否缺少可见业务内容。它默认开启，但只在候选结果连续两次超过阈值时上报；每个 View 最多一条 `browser.blank_screen`。
+
+## 适用边界
+
+白屏检测回答的是“应用根节点及视口主要区域是否缺少可见子内容”，不是截图像素分析，也不等于业务页面一定不可用。
+
+它不能可靠识别：
+
+- 页面有大面积背景图但 DOM 层级简单；
+- Canvas/WebGL 内部是否真正渲染成功；
+- 内容存在但文本与背景同色；
+- iframe 内部内容；
+- 业务数据错误但页面仍有结构。
+
+这些场景需要业务自定义事件或更专用的可用性检测。
+
+## 默认配置
+
+```ts
+tracking: {
+  blankScreen: {
+    rootSelector: 'body',
+    threshold: 0.8,
+    checkDelay: 1000,
+    confirmationDelay: 200,
+    ignoreSelectors: [],
+  },
+}
+```
+
+| 字段 | 默认 | 解析规则 |
+| --- | ---: | --- |
+| `rootSelector` | `body` | 空字符串回退 `body` |
+| `threshold` | `0.8` | 有限值限制到 `0..1`，非法值回退默认 |
+| `checkDelay` | `1000ms` | 非负有限值；非法值回退默认 |
+| `confirmationDelay` | `200ms` | 非负有限值；非法值回退默认 |
+| `ignoreSelectors` | `[]` | 追加到内置列表，不替换 |
+
+SPA 应优先指定在页面生命周期内稳定存在、且承载主要内容的容器，例如 `#app` 或 `#root`。如果框架会替换初始挂载元素，应让组件根元素保留该 selector，或使用默认的 `body` 检测。
+
+## 检测时机
+
+每次 View 变化：
+
+1. 取消旧 View 的 Timer 和活动监听。
+2. 等待新 View 页面活动结束。
+3. 再等待 `checkDelay`。
+4. 执行第一次九点采样。
+5. 比例达到阈值后，等待 `confirmationDelay`。
+6. 第二次采样仍达到阈值，才上报。
+
+页面 hidden 时取消检测；恢复 visible 后，如果当前 View 尚未上报，会重新调度。View 切换会使旧回调失效，避免异步 Timer 把旧结果报到新 View。
+
+## 九点采样
+
+采样点是视口宽高的 20%、50%、80% 交叉位置：
+
+```text
+●   ●   ●
+
+●   ●   ●
+
+●   ●   ●
+```
+
+每个点使用 `elementsFromPoint()` 获取层叠元素；浏览器不支持时退回 `elementFromPoint()`。
+
+一个点判为有内容需要满足：
+
+- 命中的 Element 位于检测根节点内部（优先 `rootSelector`，缺失时为 `body`）；
+- 不是 root 自身、body 或 documentElement；
+- `display` 不是 `none`；
+- `visibility` 不是 `hidden`；
+- opacity 大于 0。
+
+空白比例为：
+
+```text
+emptyCount / (9 - ignoredCount)
+```
+
+有效采样点为 0 时不判白屏。
+
+## Loading 与 Skeleton 忽略
+
+以下选择器内置忽略：
+
+- `[data-loading="true"]`
+- `[aria-busy="true"]`
+- `.loading`
+- `.is-loading`
+- `.spinner`
+- `.skeleton`
+- `.bk-loading`
+
+命中元素本身或祖先匹配任一选择器时，该采样点不进入分母。业务配置会追加：
+
+```ts
+tracking: {
+  blankScreen: {
+    rootSelector: '#app',
+    ignoreSelectors: ['.global-loading-mask', '.order-skeleton'],
+  },
+}
+```
+
+非法 CSS Selector 会在匹配时被忽略，不会中断检测。
+
+## 根节点缺失
+
+`document.querySelector(rootSelector)` 返回空时：
+
+- 回退到 `body` 继续执行九点采样；
+- `body` 中存在足够的可见内容时不报告白屏；
+- 只有回退采样的空白比例仍达到阈值，才进入二次确认；
+- `blank_screen.reason=missing_root`
+- `blank_screen.root_found=false`
+- empty ratio 和采样计数来自 `body` 的实际检测结果；
+- 二次确认仍为空白才上报。
+
+根节点缺失本身不再作为白屏证据，避免 Vue 等框架替换初始挂载容器后，在 SPA View 切换时持续误报。`missing_root` 表示配置根节点缺失且回退后的视口也符合白屏条件；排障时仍应检查 selector 是否稳定。
+
+## 上报字段
+
+判定成功后创建瞬时 INTERNAL Span `browser.blank_screen`：
+
+| 字段 | 说明 |
+| --- | --- |
+| `blank_screen.reason` | `missing_root` / `empty_viewport` |
+| `blank_screen.empty_ratio` | 空白有效点比例 |
+| `blank_screen.sample_count` | 固定 9 |
+| `blank_screen.valid_sample_count` | 9 - ignored |
+| `blank_screen.empty_sample_count` | 空白点数 |
+| `blank_screen.ignored_sample_count` | Loading/Skeleton 点数 |
+| `blank_screen.root_selector` | 当前配置 |
+| `blank_screen.root_found` | 根节点是否存在 |
+| `blank_screen.center_element` | 中心点最上层元素的 `tag` 或 `tag#id` |
+
+分类固定：
+
+- `span_type=error`
+- `outcome.type=error`
+- `outcome.reason=blank_screen`
+
+Span 自动关联 Session 和 View，但插件本身不写 Error exception Event，也不设置 OpenTelemetry Status ERROR。
+
+## 每个 View 最多一次
+
+一旦某 View 上报成功，后续 DOM 变化或恢复可见都不会重复上报。新 View 会重置状态，即使 URL 相同也可以产生新的白屏事件。
+
+## 配置建议
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'order-web' },
+  transport: { endpoint: 'https://rum.example.com' },
+  tracking: {
+    blankScreen: {
+      rootSelector: '#app',
+      threshold: 0.8,
+      checkDelay: 3000,
+      confirmationDelay: 500,
+      ignoreSelectors: ['.global-loading', '.skeleton-page'],
+    },
+  },
+});
+```
+
+- 首屏异步渲染较慢：增加 `checkDelay`。
+- 页面切换有短暂卸载：增加 `confirmationDelay`。
+- 页面布局天然稀疏：提高 `threshold`。
+- Loading 长时间存在：不要简单忽略所有内容；否则有效点可能为 0，真正卡死也不会上报。
+
+## 排查误报
+
+按顺序检查：
+
+1. `reason` 是否为 `missing_root`。
+2. `rootSelector` 是否指向真正承载内容的稳定节点。
+3. `valid_sample_count` 是否太少。
+4. 页面是否用 Canvas、iframe 或背景图承载主要内容。
+5. `center_element` 是否显示遮罩或布局容器。
+6. 异步渲染是否晚于 `checkDelay + confirmationDelay`。
+7. View Loading Activity 是否没有覆盖业务的异步过程。
+
+完整字段见[遥测字段字典](./telemetry-reference.md#白屏字段)。