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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/dist/bk-rum.global.js +2 -2
  2. package/dist/bk-rum.global.js.map +1 -1
  3. package/dist/core/config.d.ts +6 -8
  4. package/dist/core/runtime-context.d.ts +1 -1
  5. package/dist/core/sdk.d.ts +1 -1
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.js +555 -539
  8. package/dist/index.js.map +1 -1
  9. package/dist/plugins/device.d.ts +2 -2
  10. package/dist/plugins/resource.d.ts +1 -0
  11. package/dist/plugins/web-vitals.d.ts +1 -3
  12. package/package.json +1 -1
  13. package/skills/bk-rum-otele/SKILL.md +9 -11
  14. package/skills/bk-rum-otele/references/api.md +1 -1
  15. package/skills/bk-rum-otele/references/configuration.md +3 -3
  16. package/skills/bk-rum-otele/references/plugins-error-security.md +4 -7
  17. package/skills/bk-rum-otele/references/plugins-experience.md +4 -4
  18. package/skills/bk-rum-otele/references/telemetry-reference.md +1 -1
package/dist/plugins/device.d.ts CHANGED
@@ -20,8 +20,8 @@ export declare const getDeviceResourceAttributes: () => Attributes;
20
20
  * - viewport 监听 `resize` / `orientationchange`，并经 250ms debounce 合并，避免拖窗口时高频触发；
21
21
  * 静默期结束后用最终值刷新 runtimeAttributes。
22
22
  * - network 监听 `connection.change`（本身低频，不需要 throttle）。
23
- * - 二者只更新 in-memory 的 runtimeAttributes，不会主动产生新的 span/log，cardinality 安全；
24
- * 但更新后续生成的 log/span 会带最新值。
23
+ * - 二者只更新 in-memory 的 runtimeAttributes，不会主动产生新的 Span；
24
+ * 更新后续生成的 Span 会带最新值。
25
25
  *
26
26
  * 与 session 插件的关系：device 跨会话持久（终身），session 有过期与续期（连续访问语义）。
27
27
  */
package/dist/plugins/resource.d.ts CHANGED
@@ -9,6 +9,7 @@ type ResourceTimingWithStatus = PerformanceResourceTiming & {
9
9
  responseStatus?: number;
10
10
  };
11
11
  export declare const getResourceTimingAttributes: (entry: ResourceTimingWithStatus) => Record<string, number>;
12
+ export declare const getResourceDuration: (entry: ResourceTimingWithStatus) => number;
12
13
  export declare const getResourcePerformanceAttributes: (entry: ResourceTimingWithStatus) => {
13
14
  'resource.encoded_body_size': number;
14
15
  'resource.decoded_body_size': number;
package/dist/plugins/web-vitals.d.ts CHANGED
@@ -8,9 +8,7 @@
8
8
  * （LCP 元素 url / CLS shift target / INP interaction target 等高基数字段），
9
9
  * 方便按个例排查"哪个元素拖累了 LCP"
10
10
  *
11
- * Histogram 设计：
12
- * - browser.web_vital.cls：单位 '1'（无量纲），CLS 是累积分数，不能与 ms 混用
13
- * - browser.web_vital.duration：单位 'ms'，FCP/INP/LCP/TTFB 共享，靠 vital.metric 维度区分
11
+ * 数值语义：CLS 是无量纲分数，FCP/INP/LCP/TTFB 的 vital.value 单位为 ms。
14
12
  *
15
13
  * Navigation Type：
16
14
  * 优先使用 metric.navigationType（web-vitals 内部计算，含 'back-forward-cache' 等准确值），
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blueking/open-telemetry",
3
- "version": "0.0.22-beta.1",
3
+ "version": "0.0.22",
4
4
  "description": "OpenTelemetry browser SDK for BK RUM",
5
5
  "author": "TencentCloud Real User Monitoring",
6
6
  "main": "dist/index.js",
package/skills/bk-rum-otele/SKILL.md CHANGED
@@ -5,7 +5,7 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
5
5
 
6
6
  # 蓝鲸 RUM OpenTelemetry SDK 接入助手
7
7
 
8
- `@blueking/open-telemetry` 是蓝鲸 RUM 的浏览器上报 SDK，基于 OpenTelemetry Web SDK，把页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话、用户动作等浏览器事件统一转成 Trace / Metric / Log 三类信号，通过 OTLP HTTP 上报到 collector。
8
+ `@blueking/open-telemetry` 是蓝鲸 RUM 的浏览器上报 SDK，基于 OpenTelemetry Web SDK，把页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话、用户动作等浏览器事件统一转成 RUM Span，通过唯一的 OTLP HTTP Trace 通道上报到 collector。
9
9
 
10
10
  本 skill 面向**集成使用方**：帮助把 SDK 接入到自己的前端应用，包括安装、配置、按需开关采集能力、框架集成、隐私脱敏、排障和手动上报。不覆盖 SDK 源码本身的开发维护。
11
11
 
@@ -24,31 +24,29 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
24
24
  | 第一次接入、安装、最小示例、CDN、生产推荐配置 | `references/getting-started.md` |
25
25
  | 评估 SDK 能力边界、默认开关、浏览器 API、信号产出和降级行为 | `references/capabilities.md` |
26
26
  | 理解源码模块、初始化顺序、运行时上下文、过滤链路和 Hook 时机 | `references/architecture.md` |
27
- | 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文 | `references/concepts.md` |
27
+ | 搞懂单一 Trace 信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文 | `references/concepts.md` |
28
28
  | 查配置项、默认值、Endpoint、插件参数和 Hook | `references/configuration.md` |
29
- | 查 Transport、单信号开关、批量上报、Session 采样和 traceparent 透传 | `references/transport-sampling.md` |
29
+ | 查 Transport、批量上报、Session 采样和 traceparent 透传 | `references/transport-sampling.md` |
30
30
  | 了解插件默认组合、启用规则和能力分类 | `references/plugins.md` |
31
31
  | 配置 Session、Device、View、Action | `references/plugins-basic.md` |
32
32
  | 配置 Resource、Web Vitals、Blank Screen、Long Task、View Loading Time | `references/plugins-experience.md` |
33
33
  | 配置 Error、CSP Violation 和错误上报 | `references/plugins-error-security.md` |
34
- | 配置 Fetch/XHR Request、HTTP Body、Trace Header、WebSocket | `references/plugins-network.md` |
34
+ | 配置 Fetch/XHR Request、Trace Header、WebSocket | `references/plugins-network.md` |
35
35
  | 写自定义插件、接入第三方 OpenTelemetry instrumentation | `references/custom-plugin.md` |
36
36
  | 查公开 API（start/flush/shutdown/setUser/setView/reportAction/reportCustomEvent 等） | `references/api.md` |
37
37
  | Vue / React / Vue Router / 微前端 集成 | `references/framework-integration.md` |
38
38
  | URL 脱敏、属性脱敏、公共属性、低基数路由、user.id 处理 | `references/privacy.md` |
39
39
  | 了解上报字段、span_type/result、哪些字段是后端派生 | `references/data-model.md` |
40
- | 查具体的 span 名 / metric 名 / log 事件名、完整属性字典 | `references/telemetry-reference.md` |
40
+ | 查具体的 Span 名、事件字段和完整属性字典 | `references/telemetry-reference.md` |
41
41
  | 本地看不到数据、手动事件没上报、白屏误报、接口 span 太多等排障 | `references/troubleshooting.md` |
42
42
 
43
43
  > `references/` 由 `packages/open-telemetry/scripts/gen-skill-references.mjs` 从 SDK 的 `wikis/` 自动生成，请勿手改。如内容过期，让维护者重新执行 `pnpm --filter @blueking/open-telemetry skill:refs`。
44
44
 
45
45
  ## 核心心智模型
46
46
 
47
- ### 三类信号
47
+ ### 单一 Trace 信号
48
48
 
49
- - **Trace**：有起止时间的行为——页面访问、接口请求、资源加载、用户点击、长任务。
50
- - **Metric**：可聚合的数值——Web Vitals、长任务数、WebSocket 消息大小、白屏结果。
51
- - **Log**：离散事件——错误、CSP 违规、会话生命周期、HTTP body 错误路径。
49
+ SDK 只创建 Trace Provider。页面、请求、资源、错误、Vital、白屏和生命周期事件都编码为 RUM Span；计数、直方图、分位数、错误分组和跨事件聚合由服务端完成。
52
50
 
53
51
  ### 内置采集与扩展
54
52
 
@@ -59,11 +57,11 @@ SDK 把能力拆成两类：
59
57
 
60
58
  ### 会话级确定性采样
61
59
 
62
- `session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是 trace 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的 span/log/metric 决定一致。插件仍维护必要的浏览器生命周期，但未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
60
+ `session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是单条 Span 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的所有 Span 决定一致。插件仍维护必要的浏览器生命周期，但未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
63
61
 
64
62
  ### 运行时上下文
65
63
 
66
- SDK 维护公共上下文并自动挂到后续 span/log 上：`user.id`（业务方提供，SDK 原样透传、不 hash 不脱敏）、`session.id`（Session 生成/轮换）、`view.*`（View 管理器维护）。Metric 只保留 `view.url_path_group` 等低基数维度，不携带唯一 `session.id` / `view.id` / `action.id`；精确关联使用对应 span 或 View Snapshot Log。运行中可用 `setUser()` 更新用户；手动 View 使用 `startView()` 划界、`setViewName()` 改名。
64
+ SDK 维护公共上下文并自动挂到后续 Span 上：`user.id`（业务方提供，SDK 原样透传、不 hash 不脱敏）、`session.id`（Session 生成/轮换）、`view.*`（View 管理器维护）和活动窗口内的 `action.id`。运行中可用 `setUser()` 更新用户；手动 View 使用 `startView()` 划界、`setViewName()` 改名。
67
65
 
68
66
  ### 数据归一
69
67
 
package/skills/bk-rum-otele/references/api.md CHANGED
@@ -328,7 +328,7 @@ console.log(config.transport.endpoint);
328
328
  | 分类 | 类型 |
329
329
  | --- | --- |
330
330
  | 顶层配置 | `BkOTOptions`、`BkOTApplicationConfig`、`BkOTTransportConfig`、`BkOTTrackingConfig`、`BkOTTrackingConsent`、`BkOTContextConfig`、`BkOTPrivacyConfig`、`BkOTExtensionsConfig` |
331
- | Transport | `BkOTBatchConfig`、`SignalExporterConfig` |
331
+ | Transport | `BkOTBatchConfig`、`ResolvedTransportConfig` |
332
332
  | View/Session/User | `BkOTViewConfig`、`BkOTSessionConfig`、`BkOTStartViewOptions`、`BkOTViewContext`、`BkOTSessionLifecycleEvent`、`BkOTUserContext` |
333
333
  | Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTUrlMatcher` |
334
334
  | 事件与 Hook | `BkOTActionEventPayload`、`BkOTCustomEventPayload`、`BkOTBeforeSendEvent`、`BkOTAttributesConfig`、`BkOTAttributeValue` |
package/skills/bk-rum-otele/references/configuration.md CHANGED
@@ -114,14 +114,14 @@ SDK 不读取或上报请求/响应 Body。
114
114
  | 字段 | 类型 | 默认 | 参数 |
115
115
  | --- | --- | --- | --- |
116
116
  | `resource` | `boolean` | `true` | 无；`false` 只关闭静态资源 Span，Resource Observer 仍服务请求 timing/活动 |
117
- | `error` | `boolean \| BkOTErrorPluginOptions` | `true` | `windowMs=60_000`、`maxPerWindow=5` |
117
+ | `error` | `boolean` | `true` | 无；每条原始错误都生成 Span |
118
118
  | `webVitals` | `boolean` | `true` | 无 |
119
119
  | `blankScreen` | `boolean \| BkOTBlankScreenPluginOptions` | `true` | 见下表 |
120
120
  | `device` | `boolean \| BkOTDevicePluginOptions` | `true` | 见下表 |
121
121
  | `action` | `boolean \| BkOTActionPluginOptions` | `true` | 见下表 |
122
122
  | `longTask` | `boolean \| BkOTLongTaskPluginOptions` | `false` | `threshold=50` ms |
123
123
  | `websocket` | `boolean` | `false` | 无 |
124
- | `cspViolation` | `boolean` | `false` | 无，内置同指纹 60 秒最多 5 条 |
124
+ | `cspViolation` | `boolean` | `false` | 无；每条 CSP 违规都生成 Span |
125
125
 
126
126
  Blank Screen：
127
127
 
@@ -131,7 +131,7 @@ Blank Screen：
131
131
  | `threshold` | `0.8` | 九点采样的空白比例，限制到 `0..1` |
132
132
  | `checkDelay` | `1000` ms | 页面活动稳定后的首次检查延迟 |
133
133
  | `confirmationDelay` | `200` ms | 两次候选白屏的确认间隔 |
134
- | `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会替换内置数组 |
134
+ | `ignoreSelectors` | 内置 loading/skeleton 选择器 | 自定义数组会追加到内置数组 |
135
135
 
136
136
  Action：
137
137
 
package/skills/bk-rum-otele/references/plugins-error-security.md CHANGED
@@ -14,17 +14,14 @@
14
14
  - `unhandledrejection`
15
15
  - 资源加载错误
16
16
 
17
- 插件会生成 error span，并使用 fingerprint 做窗口内节流，避免相同错误在短时间内刷屏。
17
+ 插件对每条原始错误生成 error Span，不在浏览器做错误指纹、计数或节流。
18
18
 
19
- **产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带原始 `error.message`、`error.source` 和标准 exception event。SDK 不做错误指纹、计数或节流。
19
+ **产出遥测**：Span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带原始 `error.message`、`error.source` 和标准 exception event。
20
20
 
21
21
  ```ts
22
22
  new BkOpenTelemetry({
23
23
  tracking: {
24
- error: {
25
- maxPerWindow: 5,
26
- windowMs: 60_000,
27
- },
24
+ error: true,
28
25
  },
29
26
  });
30
27
  ```
@@ -51,7 +48,7 @@ try {
51
48
 
52
49
  `cspViolation` 插件默认关闭。开启后监听浏览器 `securitypolicyviolation` 事件，并写入 error span。
53
50
 
54
- **产出遥测**：span `csp.violation`（`span_type=error`），带 `csp.*` 字段；完整策略 `csp.original_policy` 仅在节流窗口首条携带。
51
+ **产出遥测**：Span `csp.violation`（`span_type=error`），每条都携带浏览器提供的 `csp.*` 字段和 `csp.original_policy`。
55
52
 
56
53
  ```ts
57
54
  new BkOpenTelemetry({
package/skills/bk-rum-otele/references/plugins-experience.md CHANGED
@@ -30,15 +30,15 @@ new BkOpenTelemetry({
30
30
 
31
31
  ## action 与挫败信号
32
32
 
33
- `action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time` 和子事件数量。
33
+ `action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time`，不在浏览器统计子事件数量。
34
34
 
35
35
  自动点击还会判断三类挫败信号：
36
36
 
37
- - `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。三次点击合并为一条 action。
37
+ - `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。每次原始点击都保留独立 Action Span，并附加 rage 语义。
38
38
  - `dead_click`：点击后没有页面活动、输入、滚动或文本选择；文本输入、链接、select、textarea、canvas、contenteditable 等无法可靠判断的元素会排除。
39
39
  - `error_click`：点击活动窗口内产生前端错误。
40
40
 
41
- 信号写入 `action.frustration.type`（string[]）和 `action.frustration.count`。为了完成连续点击判断，action span 最多延迟 1 秒创建；`action.id` 只在真实页面活动窗口内挂到关联事件上，不会因为这个上报等待期延长。
41
+ 信号写入 `action.frustration.type`（string[]），不生成挫败计数。为了完成连续点击判断，Action Span 最多延迟 1 秒创建；`action.id` 只在真实页面活动窗口内挂到关联事件上，不会因为这个上报等待期延长。
42
42
 
43
43
  ## webVitals
44
44
 
@@ -90,7 +90,7 @@ new BkOpenTelemetry({
90
90
  });
91
91
  ```
92
92
 
93
- LoAF 会补充 blocking duration、render/style/layout 阶段、最重脚本归因，并把每个脚本作为 `long_task.script` Span Event。初始化阶段的 buffered entries 延迟到后续宏任务批量处理，避免 SDK 启动自身制造阻塞。不支持 LoAF 和 Long Tasks API 的浏览器会跳过插件。
93
+ LoAF 会补充浏览器原生的 blocking duration、render/style/layout 阶段、最重脚本归因，并把每个脚本作为 `long_task.script` Span Event。回退到 Long Tasks API 时不伪造 blocking duration，每条浏览器 attribution 都作为 `long_task.attribution` Span Event 保留。初始化阶段的 buffered entries 延迟到后续宏任务批量处理，避免 SDK 启动自身制造阻塞。不支持 LoAF 和 Long Tasks API 的浏览器会跳过插件。
94
94
 
95
95
  **产出遥测**：span `browser.long_task`（`span_type=longtask`），计数与耗时分布由服务端派生。
96
96
 
package/skills/bk-rum-otele/references/telemetry-reference.md CHANGED
@@ -38,7 +38,7 @@ SDK 只产出 RUM Span，不产出 OpenTelemetry Metric 或 Log。计数、直
38
38
  | `action.click` | `action` | `action.loading_time`、目标和 `action.frustration.type`；不含资源/错误/长任务计数 |
39
39
  | `action.custom` | `action` | 手动 Action 名称和属性 |
40
40
  | `browser.blank_screen` | `error` | 白屏采样点、比例、根节点和原因 |
41
- | `browser.long_task` | `long_task` | Long Task/LoAF 原始耗时与脚本 span event |
41
+ | `browser.long_task` | `long_task` | Long Task/LoAF 原始耗时；LoAF 脚本和旧 API attribution span event；仅 LoAF 带原生 blocking duration |
42
42
  | `csp.violation` | `error` | CSP violation 原始字段；不做指纹或客户端节流 |
43
43
  | `browser.websocket` | `websocket` | `event.phase=connect\|open\|error\|close`、`websocket.connection.id`、关闭码；不采集消息 |
44
44
  | `custom.<name>` | `custom` | 手动自定义事件属性和可选异常 |