@blueking/open-telemetry 0.0.30 → 0.0.32

package/README.md

@@ -1,14 +1,15 @@
 # @blueking/open-telemetry
 
-面向浏览器真实用户监控（RUM）的 OpenTelemetry SDK。它把 Session、View、Fetch/XHR、静态资源、错误、Web Vitals、Action、白屏、Long Task、WebSocket、CSP 与设备上下文建模为原始 Span，并通过 OTLP/HTTP JSON 上报。
+面向浏览器真实用户监控（RUM）的 OpenTelemetry SDK。它把 Session、View、Fetch/XHR、静态资源、错误、Web Vitals、Action、白屏、Long Task、WebSocket、CSP 与设备上下文建模为原始 Span，并通过 OTLP/HTTP JSON 上报。其中 Long Task、WebSocket 和 CSP 默认关闭，见下方能力表。
 
 SDK 只创建一个 `WebTracerProvider`：
 
 ```text
 Browser events
   → Session / View / Action runtime context
-  → RUM Span
-  → Session sampling + context/filter hooks
+  → Span 创建：RumSessionSampler 决定是否记录（未采样即 non-recording）
+  → FilteringSpanProcessor.onStart 补齐缺失的运行时属性
+  → FilteringSpanProcessor.onEnd 校验 Session/View、丢弃标记、tracking.beforeSend
   → Simple/BatchSpanProcessor
   → POST <transport.endpoint>/v1/rum
 ```
@@ -39,6 +40,24 @@ export const rum = new BkOpenTelemetry({
 
 `application.name` 和 `transport.endpoint` 必填。endpoint 是根地址，SDK 去掉末尾斜杠后固定追加 `/v1/rum`。构造后默认自动启动。
 
+ESM 构建把 OpenTelemetry 依赖保留为外部 package dependencies，由应用的构建工具解析。所有插件在没有 `window` / `document` 的环境里会跳过初始化，因此可以安全地在 SSR 产物中被 import。
+
+### CDN
+
+无构建流程的页面可以用全局包，依赖已打进 bundle：
+
+```html
+<script src="https://unpkg.com/@blueking/open-telemetry@0.0.29/dist/bk-rum.global.js"></script>
+<script>
+  window.rum = new window.BkOpenTelemetry({
+    application: { name: 'legacy-portal', environment: 'production' },
+    transport: { endpoint: 'https://rum-collector.example.com' },
+  });
+</script>
+```
+
+CDN 入口只暴露 `window.BkOpenTelemetry` 这一个构造函数，不提供 `createXxxPlugin()`、`RUM_ATTRIBUTES` 等具名导出和 TypeScript 类型；需要这些请走 npm ESM 构建。生产环境应固定版本号并配合自有 CDN/SRI 策略，不要长期跟随 latest。
+
 完整接入步骤见[快速上手](./wikis/getting-started.md)，上线前请继续阅读[生产接入指南](./wikis/production.md)。
 
 ## 默认能力
@@ -52,7 +71,7 @@ export const rum = new BkOpenTelemetry({
 | 静态资源 | 开 | Resource PerformanceObserver | `browser.resource` CLIENT |
 | Error | 开 | error、unhandledrejection、资源加载错误 | 三类 Error Span + exception event |
 | Web Vitals | 开 | web-vitals / PerformanceObserver | CLS/FCP/INP/LCP/TTFB Span |
-| Action | 开 | click 与 activity | `action.click`、挫败信号 |
+| Action | 开 | 主键 click 与 activity | `action.click`、挫败信号 |
 | Blank Screen | 开 | 页面稳定 + DOM 九点采样 | `browser.blank_screen` |
 | Device | 开 | UA/UA-CH、Screen、Network Information | Resource 与运行时属性 |
 | Long Task | 关 | Long Animation Frame / Long Tasks | `browser.long_task` |
@@ -147,9 +166,9 @@ Authorization: Bearer <token>  # 配置 token 时
 }
 ```
 
-当前使用 `@opentelemetry/exporter-trace-otlp-http@0.217.0` 的浏览器 JSON exporter：默认请求超时 10 秒、并发出口上限 30、不压缩；429/502/503/504 和部分网络错误可重试，并支持 `Retry-After`。
+当前使用 `@opentelemetry/exporter-trace-otlp-http@0.217.0` 的浏览器 JSON exporter：429/502/503/504 和部分网络错误可重试，并支持 `Retry-After`。
 
-默认 BatchSpanProcessor：queue 2048、batch 512、delay 5000ms、export timeout 30000ms。队列满后新结束的 Span 被丢弃。详细重试、keepalive、flush 与 CORS 规则见[上报协议、批处理与采样](./wikis/reference/transport.md)。
+超时、并发和批处理参数本包不硬编码，未配置时沿用锁定依赖的默认值：请求超时 10 秒、并发出口上限 30、BatchSpanProcessor queue 2048 / batch 512 / delay 5000ms / export timeout 30000ms。队列满后新结束的 Span 被丢弃。升级 OTel 依赖时需重新核对这些数值。详细重试、keepalive、flush 与 CORS 规则见[上报协议、批处理与采样](./wikis/reference/transport.md)。
 
 ## Session 采样与导出条件
 
@@ -186,13 +205,26 @@ rum.reportCustomEvent({
 });
 ```
 
-- `reportAction()` 立即创建 `action.custom`，不是持续关联后续请求的自动 Action；
+- `reportAction()` 立即创建并结束 `action.<name>`（上例为 `action.submit-order`，`action.type=custom`），不是持续关联后续请求的自动 Action；
 - `reportCustomEvent()` 创建 `custom.<name>`；带 Error 时记录 exception 和 ERROR status；
 - name 是检索维度，必须有限枚举，不能拼用户/订单/随机 ID；
 - 两者都受当前 Session 采样约束。
 
 默认 `autoStart: true` 是异步启动，构造后立即同步调用的手动事件不会排队，可能因为 View 尚未建立而丢失。首个手动事件不能丢时，使用 `autoStart: false`，先 `await rum.start()`，manual View 再调用 `startView()`，之后才开放业务上报。
 
+## 生命周期
+
+```ts
+await rum.start();     // autoStart: false 时显式启动
+await rum.flush();     // 尽力导出已结束 Span
+await rum.shutdown();  // 卸载插件、flush、销毁 Provider
+```
+
+- `start()` 幂等；`enabled: false` 或 Consent 未授权时会标记为已启动但不安装采集；
+- 单个插件初始化失败被隔离，不会让 `start()` reject，`debug: true` 时打印 warning；
+- `flush()` 只等待 SDK 完成导出调用，不代表服务端已持久化；SDK 也会在 `pagehide` 和页面转入 hidden 时自动尽力 flush；
+- `shutdown()` 后实例**不可重启**，再次 `start()` 会抛错，需要重新 `new`；临时停止采集应用 `setTrackingConsent('not-granted')`。
+
 ## 用户和 View
 
 ```ts
@@ -236,7 +268,7 @@ await rum.setTrackingConsent('not-granted');
 
 未授权时不安装插件/instrumentation。撤销会关闭采集、清理 Session 上下文并 flush 已结束的队列数据，但不会删除服务端已经接收的数据，也不会删除 localStorage 中仍有效的 Session 记录；再次授权后可能复用该 Session。
 
-`trackingConsent: 'not-granted'` 控制的是采集和发送，不会推迟构造阶段的所有浏览器读取：只要 `tracking.device !== false`，`new BkOpenTelemetry()` 仍会读取 UA/UA-CH、内存和逻辑处理器等 Device Resource 快照，但此时不会发送。合规要求“授权前不能读取”时，应在授权后再构造实例。完整边界见[隐私、Consent 与字段治理](./wikis/reference/privacy.md)。
+`trackingConsent: 'not-granted'` 控制的是采集和发送，不会推迟构造阶段的所有浏览器读取：只要 `tracking.device !== false`，`new BkOpenTelemetry()` 仍会读取 `navigator.userAgent` 与 UA-CH，生成 `user_agent.*` 和 `device.type` 四个 Device Resource 字段，但此时不会发送。SDK 不读取设备内存或逻辑处理器数。合规要求“授权前不能读取 User-Agent”时，应在授权后再构造实例。完整边界见[隐私、Consent 与字段治理](./wikis/reference/privacy.md)。
 
 ## 扩展
 
@@ -269,26 +301,28 @@ SDK 默认不附加独立页面属性；页面地址使用经过 `redactUrl` 处
 
 OTLP 字段分五层：
 
-1. Resource：`service.name`、环境、版本、SDK、设备和 `session.sample_rate`；
-2. Scope：instrumentation name/version；
-3. Span envelope：trace/span ID、时间、kind、status；
-4. RUM attributes：Session/View/Action 关联、`event.*`、`span_type`、`result` 等；
-5. Span events：exception、Long Task script/attribution。
+1. Resource：`service.name`、`deployment.environment.name`、`service.version`、`telemetry.sdk.*`、`session.sample_rate`，以及 UA/UA-CH 派生的 `user_agent.*` 和 `device.type`；
+2. Scope：`scope.name = "bk-rum"`（不带 version）；
+3. Span envelope：`traceId` / `spanId`、纳秒起止时间、`kind`、`status`、`links`；
+4. RUM attributes：`session.id` / `view.id` / `action.id` / `user.id` 关联字段，加上分类字段 `span_type` 和 `outcome.type`；
+5. Span events：`exception`、`long_task.script`、`long_task.attribution`。
+
+分类只用 `span_type`（`session` / `view` / `resource` / `error` / `vital` / `long_task` / `action` / `websocket` / `custom`）和 `outcome.type`（`success` / `warning` / `error` / `timeout` / `abort`）两个字段。当前 SDK **不写** `outcome.reason`，也没有 `event.*` 或 `result` 字段。
 
-主要分类：
+主要 Span 及其实际产出的领域字段：
 
-| Span | 关键字段 |
+| Span | 领域字段 |
 | --- | --- |
-| `browser.session` | phase、session.id/start_time、reason、previous_id |
-| `browser.view` | phase、version、name、URL group、loading type/time、navigation timings |
-| `browser.resource` | URL、method/status、resource type、size/protocol、DNS/TCP/TLS/TTFB/download |
-| Error spans | message/source/handled、code location、exception event |
-| `browser.web_vital` | metric/value/rating 与 attribution |
-| `action.click` | action ID/name/target/loading time/frustration |
-| `browser.blank_screen` | reason/score/sample counts/root/center element |
-| `browser.long_task` | duration/blocking、entry type、script/attribution events |
+| `browser.session` | `session.phase`、`session.id`、`session.type`、`session.has_replay` |
+| `browser.view` | `view.phase`、`view.version`、`view.url` / `url_template` / `previous*`、`loading_type`、`loading_time` / `loading_time_source`、初始导航 timing、`view.end_reason` |
+| `browser.resource` | `url.full` / `url.template`、`http.request.method` / `response.status_code`、`resource.type` / `size` / `protocol` / `cache.hit`、DNS/TCP/TLS/首字节/下载阶段 |
+| Error Span | `error.message` / `source` / `handled`、`code.filepath` / `lineno` / `column`、`exception` Event |
+| `browser.web_vital` | `vital.metric` / `value` / `id`，以及 LCP/INP/TTFB 的部分 attribution |
+| `action.click` | `action.id` / `type` / `target.name` / `target.tag` / `frustration.type` |
+| `browser.blank_screen` | `blank_screen.reason` / `empty_ratio` / `empty_sample_count` |
+| `browser.long_task` | `long_task.id` / `entry_type` / `name`，LoAF 的 `blocking_duration` 等，加 script/attribution Event |
 
-完整层级见[RUM 数据模型](./wikis/concepts/data-model.md)，所有精确字段见[遥测字段字典](./wikis/reference/telemetry.md)。
+持续时间统一用 Span 起止时间表达，没有 `action.loading_time`、`long_task.duration` 这类耗时 Attribute。完整层级见[RUM 数据模型](./wikis/concepts/data-model.md)，逐字段定义和「当前不会出现的字段」清单见[遥测字段字典](./wikis/reference/telemetry.md)。
 
 ## 调试
 
@@ -329,9 +363,12 @@ await rum.flush();
 | Vue/React/Router/SSR/微前端 | [框架与路由集成](./wikis/framework-integration.md) |
 | 理解模块、启动、过滤和导出 | [架构与数据流](./wikis/concepts/architecture.md) |
 | 理解 OTLP 层级和字段归属 | [RUM 数据模型](./wikis/concepts/data-model.md) |
+| 深入单项采集算法和阈值 | [Session](./wikis/features/session-context.md)、[View](./wikis/features/views-routing.md)、[网络](./wikis/features/network.md)、[Action](./wikis/features/actions.md)、[性能](./wikis/features/performance.md)、[错误与 CSP](./wikis/features/errors-security.md)、[白屏](./wikis/features/blank-screen.md) |
+| 写自定义插件或接第三方 Instrumentation | [插件与 OpenTelemetry 扩展](./wikis/features/extensions.md) |
 | 查全部配置和默认值 | [配置参考](./wikis/reference/configuration.md) |
 | 查类、方法、类型和扩展 API | [API 参考](./wikis/reference/api.md) |
 | 查 Span 名和逐字段定义 | [遥测字段字典](./wikis/reference/telemetry.md) |
+| 对齐前后端字段语义和稳定性承诺 | [RUM 语义约定](./wikis/reference/span-protocol.md) |
 | 查协议、batch、重试和采样 | [上报协议、批处理与采样](./wikis/reference/transport.md) |
 | 查 Consent 和脱敏边界 | [隐私、Consent 与字段治理](./wikis/reference/privacy.md) |
 | 解决无数据、重复、缺字段和误报 | [调试与排障](./wikis/reference/troubleshooting.md) |