@blueking/open-telemetry 0.0.31 → 0.0.33

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,25 +40,43 @@ 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.32/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)。
 
 ## 默认能力
 
 | 能力 | 默认 | 浏览器来源 | 主要产出 |
 | --- | --- | --- | --- |
-| Session | 基础能力 | localStorage、用户活动、visibility | `browser.session` start/rotate/end |
-| View / Router | auto | Navigation Timing、History、hash、BFCache | `browser.view` start/update/end |
+| Session | 基础能力 | localStorage、用户活动、visibility | `session.start` / `session.rotate` / `session.end` |
+| View / Router | auto | Navigation Timing、History、hash、BFCache | `<view.name>` start/update/end |
 | View Loading Time | 开 | 请求、DOM、资源、`window.open` activity | `view.loading_time` |
-| Fetch/XHR | 开 | fetch、XMLHttpRequest、Resource Timing | `browser.resource` CLIENT |
-| 静态资源 | 开 | Resource PerformanceObserver | `browser.resource` CLIENT |
+| Fetch/XHR | 开 | fetch、XMLHttpRequest、Resource Timing | `<METHOD> <url.template>` CLIENT |
+| 静态资源 | 开 | Resource PerformanceObserver | `GET <url.template>` CLIENT |
 | Error | 开 | error、unhandledrejection、资源加载错误 | 三类 Error Span + exception event |
 | Web Vitals | 开 | web-vitals / PerformanceObserver | CLS/FCP/INP/LCP/TTFB Span |
-| Action | 开 | click 与 activity | `action.click`、挫败信号 |
-| Blank Screen | 开 | 页面稳定 + DOM 九点采样 | `browser.blank_screen` |
+| Action | 开 | 主键 click 与 activity | `action.name`、挫败信号 |
+| Blank Screen | 开 | 页面稳定 + DOM 九点采样 | `blank_screen.<reason>` |
 | Device | 开 | UA/UA-CH、Screen、Network Information | Resource 与运行时属性 |
-| Long Task | 关 | Long Animation Frame / Long Tasks | `browser.long_task` |
-| WebSocket | 关 | WebSocket 生命周期 | connect/open/error/close Span |
-| CSP | 关 | securitypolicyviolation | `csp.violation` |
+| Long Task | 关 | Long Animation Frame / Long Tasks | `long_task.entry_type` |
+| WebSocket | 关 | WebSocket 生命周期 | `websocket.<phase>` |
+| CSP | 关 | securitypolicyviolation | `csp.<effective_directive>` |
 
 Session 和 View 是普通 Span 的必要关联边界，不能通过一个 `tracking.session: false` 关闭。精确默认值、降级行为和成本见[能力矩阵](./wikis/capabilities.md)。
 
@@ -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 采样与导出条件
 
@@ -164,7 +183,7 @@ session: {
 - 同一 Session 的决定一致，轮换后重新计算；
 - 未采样时 `startSpan()` 返回 non-recording Span，手动事件不导出；
 - 普通 Span 还必须有有效 `session.id` 与 `view.id`；
-- `browser.session` 是允许没有 View 的例外；
+- `span_type=session` 是允许没有 View 的例外；
 - SDK 自身 `/v1/rum` 请求、显式 discard 和 beforeSend 返回 false 的 Span 会被过滤。
 
 ## 手动事件
@@ -186,13 +205,26 @@ rum.reportCustomEvent({
 });
 ```
 
-- `reportAction()` 立即创建 `action.custom`，不是持续关联后续请求的自动 Action；
+- `reportAction()` 立即创建并结束 `<action.name>`（上例为 `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 |
+| `session.<phase>` | `session.phase`、`session.id`、`session.type`、`session.has_replay` |
+| `<view.name>` | `view.phase`、`view.version`、`view.url` / `url_template` / `previous*`、`loading_type`、`loading_time` / `loading_time_source`、初始导航 timing、`view.end_reason` |
+| `<method> <url.template>` | `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 |
+| `<VITAL_METRIC>` | `vital.metric` / `value` / `id`，以及 LCP/INP/TTFB 的部分 attribution |
+| `click <target>` | `action.id` / `name` / `type` / `target.name` / `target.tag` / `frustration.type` |
+| `blank_screen.<reason>` | `blank_screen.reason` / `empty_ratio` / `empty_sample_count` |
+| `<long_task.entry_type>` | `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)。
 
 ## 调试
 
@@ -324,14 +358,18 @@ await rum.flush();
 | 任务 | 文档 |
 | --- | --- |
 | 首次安装和验证 | [快速上手](./wikis/getting-started.md) |
+| 用 AI 安装 Skill 并生成配置 | [用 AI 接入](./wikis/ai-setup.md) |
 | 上线检查和容量/隐私/CORS | [生产接入指南](./wikis/production.md) |
 | 判断支持范围、默认开关和降级 | [能力矩阵](./wikis/capabilities.md) |
 | 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) |