@blueking/open-telemetry 0.0.5 → 0.0.6

package/README.md

@@ -19,7 +19,7 @@ const bkOT = new BkOpenTelemetry({
 ### CDN 引入
 
 ```html
-<script src="https://unpkg.com/@blueking/open-telemetry@0.1.0/dist/bk-rum.global.js"></script>
+<script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
 <script>
   const bkOT = new BkOpenTelemetry({
     endpoint: 'https://your-otlp-collector',
@@ -75,6 +75,7 @@ new BkOpenTelemetry({
   enabled: true,
   debug: false,
   sampleRate: 1,
+  spanProcessor: 'batch',
   headers: {
     'X-Custom-Header': 'value',
   },
@@ -92,10 +93,13 @@ new BkOpenTelemetry({
 - `enabled`: 是否启用 SDK，默认 `true`。
 - `debug`: 是否在控制台打印上报数据，默认 `false`。
 - `sampleRate`: 采样率，范围 `0 - 1`，默认 `1`。
+- `spanProcessor`: trace 处理模式，默认 `batch`；可选 `simple` 用于本地调试。
 - `headers`: 附加上报请求头，显式传入的 header 可覆盖 token 生成的同名 header。
 - `signalEndpoints`: 分别配置 trace、metric、log 的完整上报地址，优先级高于统一 `endpoint`。
 - `traces` / `metrics` / `logs`: 分别配置 trace、metric、log 的高级请求参数；其中 `endpoint` 优先级低于 `signalEndpoints`。
 
+`spanProcessor: 'batch'` 会批量缓存并定时上报 trace，适合生产环境；`spanProcessor: 'simple'` 会在 span 结束后立即触发导出，适合本地调试，不建议生产环境使用。
+
 ## RUM 采集配置
 
 所有采集能力统一放在 `rum` 下配置：
@@ -139,7 +143,7 @@ new BkOpenTelemetry({
 - `pageView`: 采集页面访问和 SPA 路由变化。
 - `error`: 采集 JS 错误、未处理 Promise rejection、资源加载失败。
 - `webVitals`: 采集 LCP、CLS、INP、FCP、TTFB。
-- `blankScreen`: 检测白屏。
+- `blankScreen`: 检测白屏，SPA 项目建议显式配置 `rootSelector` 为应用挂载点（详见下文「白屏检测」）。
 - `device`: 采集浏览器、系统、网络等设备信息。
 - `session`: 维护匿名会话。
 - `websocket`: 采集 WebSocket 连接和消息事件。
@@ -148,6 +152,50 @@ new BkOpenTelemetry({
 - `cspViolation`: 采集 CSP violation。
 - `httpBody`: 采集请求/响应 body，建议配合 `redact` 做脱敏。
 
+### 白屏检测
+
+页面就绪后延迟一段时间，在视口的 5 个采样点用 `document.elementFromPoint` 判断这些点是否落在"根元素"或裸 body 上，命中比例超过阈值即视为白屏。命中后会同时上报：
+
+- metric: `browser.blank_screen.count`（仅带低基数维度 `bk.rum.blank_screen.root`）
+- log: `browser.blank_screen`（携带评分、命中元素、DOM 节点数等高基数信息）
+
+完整配置示例：
+
+```javascript
+new BkOpenTelemetry({
+  endpoint: 'https://your-otlp-collector',
+  token: 'your-report-token',
+  rum: {
+    blankScreen: {
+      // SPA 项目强烈建议设置为应用挂载点，例如 '#app' / '#root'
+      rootSelector: '#app',
+      // 页面 ready 后延迟多少毫秒开始检测，默认 3000
+      checkDelay: 3000,
+      // 命中比例阈值，范围 0 - 1，默认 0.8
+      threshold: 0.8,
+      // 自定义"加载中"占位选择器，命中样本会从分母里剔除，避免骨架屏被误判为白屏
+      ignoreSelectors: ['.app-loading', '.page-skeleton'],
+    },
+  },
+});
+```
+
+配置项说明：
+
+- `rootSelector`: 默认 `body`。**SPA 项目（React/Vue 等）必须显式配置为应用挂载点**，否则一旦应用成功 mount，采样点会落在挂载根（如 `#app`）的子节点上，永远不会判定为白屏；反之挂载失败时挂载根本身仍存在，配置成 `#app` 后才能正确命中。
+- `checkDelay`: 从 `DOMContentLoaded` 起算的延迟（毫秒），默认 `3000`。SPA 首屏渲染较慢的项目可以适当调大。
+- `threshold`: 命中比例阈值（0 - 1），默认 `0.8`。
+- `ignoreSelectors`: 项目自定义的"加载中"占位选择器。SDK 内置了一组通用兜底（`[data-loading="true"]`、`[aria-busy="true"]`、`.loading`、`.is-loading`、`.spinner`、`.skeleton`、`.bk-loading`），但**强烈建议项目按自己的骨架屏/loading 约定显式追加**，命中此选择器的样本既不算"空白"也不算"非空白"，会从分母里剔除。
+
+判定算法（伪代码）：
+
+```text
+score = empty_samples / (total_samples - loading_samples)
+isBlank = score >= threshold
+```
+
+如果所有采样点都命中 loading（说明页面整体还在加载），本次检测会被视为待定，不上报。
+
 ## 公共属性
 
 通过 `attributes` 给不同类型数据补充公共属性：