@blueking/open-telemetry 0.0.33 → 0.0.35-beta.1
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.
- package/README.md +67 -57
- package/dist/bk-rum.global.js +2 -2
- package/dist/bk-rum.global.js.map +1 -1
- package/dist/core/action-activity.d.ts +5 -1
- package/dist/core/action-target.d.ts +19 -0
- package/dist/core/config.d.ts +15 -5
- package/dist/core/event-time.d.ts +7 -0
- package/dist/core/performance-timing.d.ts +13 -0
- package/dist/core/plugin.d.ts +37 -2
- package/dist/core/processor.d.ts +24 -2
- package/dist/core/request-timing.d.ts +3 -2
- package/dist/core/runtime-context.d.ts +62 -2
- package/dist/core/sdk.d.ts +23 -1
- package/dist/core/session-transition.d.ts +19 -0
- package/dist/core/trace-context.d.ts +6 -7
- package/dist/core/view-location.d.ts +10 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2955 -1483
- package/dist/index.js.map +1 -1
- package/dist/integrations/vue-router.d.ts +25 -0
- package/dist/plugins/action.d.ts +1 -1
- package/dist/plugins/blank-screen-detection.d.ts +11 -0
- package/dist/plugins/blank-screen.d.ts +10 -18
- package/dist/plugins/common.d.ts +4 -2
- package/dist/plugins/document-vitals.d.ts +25 -0
- package/dist/plugins/page-view.d.ts +1 -1
- package/dist/plugins/resource.d.ts +14 -1
- package/dist/plugins/session-state.d.ts +14 -2
- package/dist/plugins/session-store.d.ts +12 -0
- package/dist/plugins/session.d.ts +1 -0
- package/dist/plugins/web-vitals-metrics.d.ts +80 -0
- package/dist/plugins/web-vitals.d.ts +2 -59
- package/dist/schema/attributes.d.ts +63 -0
- package/dist/schema/span.d.ts +5 -2
- package/package.json +9 -4
- package/skills/bk-rum-otele/references/actions.md +54 -37
- package/skills/bk-rum-otele/references/api.md +72 -51
- package/skills/bk-rum-otele/references/architecture.md +16 -16
- package/skills/bk-rum-otele/references/blank-screen.md +72 -142
- package/skills/bk-rum-otele/references/capabilities.md +66 -60
- package/skills/bk-rum-otele/references/configuration.md +101 -98
- package/skills/bk-rum-otele/references/data-model.md +22 -17
- package/skills/bk-rum-otele/references/errors-security.md +13 -13
- package/skills/bk-rum-otele/references/extensions.md +5 -3
- package/skills/bk-rum-otele/references/framework-integration.md +7 -24
- package/skills/bk-rum-otele/references/network.md +62 -49
- package/skills/bk-rum-otele/references/performance.md +62 -30
- package/skills/bk-rum-otele/references/privacy.md +5 -5
- package/skills/bk-rum-otele/references/production.md +9 -13
- package/skills/bk-rum-otele/references/session-context.md +67 -38
- package/skills/bk-rum-otele/references/span-protocol.md +771 -315
- package/skills/bk-rum-otele/references/telemetry-reference.md +288 -213
- package/skills/bk-rum-otele/references/troubleshooting.md +2 -2
- package/skills/bk-rum-otele/references/views-routing.md +103 -27
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@ SDK 只创建一个 `WebTracerProvider`：
|
|
|
7
7
|
```text
|
|
8
8
|
Browser events
|
|
9
9
|
→ Session / View / Action runtime context
|
|
10
|
-
→ Span
|
|
10
|
+
→ Span 创建：按所属 Session 采样；Session 切换待定时暂存关联
|
|
11
11
|
→ FilteringSpanProcessor.onStart 补齐缺失的运行时属性
|
|
12
12
|
→ FilteringSpanProcessor.onEnd 校验 Session/View、丢弃标记、tracking.beforeSend
|
|
13
13
|
→ Simple/BatchSpanProcessor
|
|
@@ -62,21 +62,21 @@ CDN 入口只暴露 `window.BkOpenTelemetry` 这一个构造函数，不提供 `
|
|
|
62
62
|
|
|
63
63
|
## 默认能力
|
|
64
64
|
|
|
65
|
-
| 能力
|
|
66
|
-
|
|
|
67
|
-
| Session
|
|
68
|
-
| View / Router
|
|
69
|
-
| View Loading Time | 开
|
|
70
|
-
| Fetch/XHR
|
|
71
|
-
| 静态资源
|
|
72
|
-
| Error
|
|
73
|
-
| Web Vitals
|
|
74
|
-
| Action
|
|
75
|
-
| Blank Screen
|
|
76
|
-
| Device
|
|
77
|
-
| Long Task
|
|
78
|
-
| WebSocket
|
|
79
|
-
| CSP
|
|
65
|
+
| 能力 | 默认 | 浏览器来源 | 主要产出 |
|
|
66
|
+
| ----------------- | -------- | ----------------------------------------- | -------------------------------------------------- |
|
|
67
|
+
| Session | 基础能力 | localStorage、Web Locks、可见页面可信输入 | `session.start` / `session.rotate` / `session.end` |
|
|
68
|
+
| View / Router | auto | Navigation Timing、History、hash、BFCache | `<view.name>` start/update/end |
|
|
69
|
+
| View Loading Time | 开 | 请求、DOM、资源、`window.open` activity | `view.loading_time` |
|
|
70
|
+
| Fetch/XHR | 开 | fetch、XMLHttpRequest、Resource Timing | `<METHOD> <url.template>` CLIENT |
|
|
71
|
+
| 静态资源 | 开 | Resource PerformanceObserver | `GET <url.template>` CLIENT |
|
|
72
|
+
| Error | 开 | error、unhandledrejection、资源加载错误 | 三类 Error Span + exception event |
|
|
73
|
+
| Web Vitals | 开 | 原生 PerformanceObserver / Navigation Timing | CLS/FCP/INP/LCP/TTFB Span |
|
|
74
|
+
| Action | 开 | 主键 click 与 activity | `action.name`、挫败信号 |
|
|
75
|
+
| Blank Screen | 开 | 页面稳定 + DOM 九点采样 | `blank_screen.<reason>` |
|
|
76
|
+
| Device | 开 | UA/UA-CH、Screen、Network Information | Resource 与运行时属性 |
|
|
77
|
+
| Long Task | 关 | Long Animation Frame / Long Tasks | `long_task.entry_type` |
|
|
78
|
+
| WebSocket | 关 | WebSocket 生命周期 | `websocket.<phase>` |
|
|
79
|
+
| CSP | 关 | securitypolicyviolation | `csp.<effective_directive>` |
|
|
80
80
|
|
|
81
81
|
Session 和 View 是普通 Span 的必要关联边界，不能通过一个 `tracking.session: false` 关闭。精确默认值、降级行为和成本见[能力矩阵](./wikis/capabilities.md)。
|
|
82
82
|
|
|
@@ -107,9 +107,7 @@ export const rum = new BkOpenTelemetry({
|
|
|
107
107
|
},
|
|
108
108
|
request: {
|
|
109
109
|
excludedUrls: [/\/health(?:\?|$)/],
|
|
110
|
-
allowedTracingUrls: [
|
|
111
|
-
rawUrl => new URL(rawUrl, location.href).origin === 'https://api.example.com',
|
|
112
|
-
],
|
|
110
|
+
allowedTracingUrls: [rawUrl => new URL(rawUrl, location.href).origin === 'https://api.example.com'],
|
|
113
111
|
},
|
|
114
112
|
blankScreen: {
|
|
115
113
|
rootSelector: '#app',
|
|
@@ -181,7 +179,7 @@ session: {
|
|
|
181
179
|
- 范围 0–1，默认 1，越界截断；
|
|
182
180
|
- 根据 `application.name + session.id` 稳定 hash；
|
|
183
181
|
- 同一 Session 的决定一致，轮换后重新计算；
|
|
184
|
-
-
|
|
182
|
+
- 已确定未采样时 `startSpan()` 返回 non-recording Span，手动事件不导出；切换待定期间先采集，关联确定后再决定导出；
|
|
185
183
|
- 普通 Span 还必须有有效 `session.id` 与 `view.id`；
|
|
186
184
|
- `span_type=session` 是允许没有 View 的例外；
|
|
187
185
|
- SDK 自身 `/v1/rum` 请求、显式 discard 和 beforeSend 返回 false 的 Span 会被过滤。
|
|
@@ -215,9 +213,9 @@ rum.reportCustomEvent({
|
|
|
215
213
|
## 生命周期
|
|
216
214
|
|
|
217
215
|
```ts
|
|
218
|
-
await rum.start();
|
|
219
|
-
await rum.flush();
|
|
220
|
-
await rum.shutdown();
|
|
216
|
+
await rum.start(); // autoStart: false 时显式启动
|
|
217
|
+
await rum.flush(); // 尽力导出已结束 Span
|
|
218
|
+
await rum.shutdown(); // 卸载插件、flush、销毁 Provider
|
|
221
219
|
```
|
|
222
220
|
|
|
223
221
|
- `start()` 幂等；`enabled: false` 或 Consent 未授权时会标记为已启动但不安装采集；
|
|
@@ -233,9 +231,11 @@ rum.setUser({ id: undefined });
|
|
|
233
231
|
|
|
234
232
|
rum.setViewName('order-detail');
|
|
235
233
|
rum.setViewLoadingTime();
|
|
234
|
+
rum.setViewContextProperty('order.type', 'subscription');
|
|
235
|
+
rum.addTiming('content_ready'); // 相对当前 View 起点的毫秒耗时
|
|
236
236
|
```
|
|
237
237
|
|
|
238
|
-
SDK 不 hash `user.id`。View 默认自动监听 History/hash；query-only
|
|
238
|
+
SDK 不 hash `user.id`。View 默认自动监听 History/hash；query-only 变化更新 URL 上下文，不建新 View。可配置 `tracking.view.routeMode` 为 `hash`、`history` 或 `document`，明确区分 Hash SPA、History SPA 和 MPA；默认 `auto` 自动识别标准 Hash 路由。Hash 模板保留逻辑路径，原始 URL 仍遵循隐私配置。
|
|
239
239
|
|
|
240
240
|
需要完全由 Router 控制时：
|
|
241
241
|
|
|
@@ -248,10 +248,12 @@ const rum = new BkOpenTelemetry({
|
|
|
248
248
|
});
|
|
249
249
|
|
|
250
250
|
await rum.start();
|
|
251
|
-
rum.startView({ name: 'order-detail', url: location.href });
|
|
251
|
+
rum.startView({ name: 'order-detail', url: location.href, urlTemplate: '/orders/:orderId' });
|
|
252
252
|
```
|
|
253
253
|
|
|
254
|
-
先 start 建立 Session，再 startView；不要同时使用自动和手动路由边界。Vue
|
|
254
|
+
先 start 建立 Session，再 startView；不要同时使用自动和手动路由边界。Vue Router 可用导出的 `trackVueRouterViews(rum, router)` 在成功导航后创建 View，具体见 [View 与路由](./wikis/features/views-routing.md)。其他框架与微前端示例见[框架与路由集成](./wikis/framework-integration.md)。
|
|
255
|
+
|
|
256
|
+
View 快照增加累计停留/前台时长、页面状态和自定义 timing；定时、flush、隐藏与冻结只更新快照，不续期 Session。Vital 使用稳定 ID 与递增版本，接收端按最新版本合并；文档 FCP/LCP/TTFB 与 SPA View 的 CLS/INP 分开归属。白屏区分检测、恢复与未知观测，只有确认的检测事件计入 Error，详见[字段字典](./wikis/reference/telemetry.md)。
|
|
255
257
|
|
|
256
258
|
## Consent
|
|
257
259
|
|
|
@@ -293,7 +295,7 @@ await rum.start();
|
|
|
293
295
|
|
|
294
296
|
契约、生命周期和历史时间关联见[插件与 OpenTelemetry 扩展](./wikis/features/extensions.md)。
|
|
295
297
|
|
|
296
|
-
隐私 Hook
|
|
298
|
+
隐私 Hook 覆盖 Resource/Span 及 Span Event/Link 属性。全局 `tracking.beforeSend` 可修改 `events`、`links` 的导出副本；Hook 前后均执行属性脱敏，`redactAttributes` 应保持幂等。最终过滤失败时丢弃该条遥测。
|
|
297
299
|
|
|
298
300
|
SDK 默认不附加独立页面属性；页面地址使用经过 `redactUrl` 处理的 `view.url`，低基数路由聚合使用 `view.url_template`。业务需要额外页面维度时，可通过 `context.attributes.page` 添加。
|
|
299
301
|
|
|
@@ -304,25 +306,25 @@ OTLP 字段分五层：
|
|
|
304
306
|
1. Resource：`service.name`、`deployment.environment.name`、`service.version`、`telemetry.sdk.*`、`session.sample_rate`，以及 UA/UA-CH 派生的 `user_agent.*` 和 `device.type`；
|
|
305
307
|
2. Scope：`scope.name = "bk-rum"`（不带 version）；
|
|
306
308
|
3. Span envelope：`traceId` / `spanId`、纳秒起止时间、`kind`、`status`、`links`；
|
|
307
|
-
4. RUM attributes：`session.id` / `view.id` / `action.
|
|
309
|
+
4. RUM attributes：`session.id` / `tab.id` / `view.id` / `action.ids` / `user.id` 关联字段（Action 自身使用单个 `action.id`），加上分类字段 `span_type` 和 `outcome.type`；
|
|
308
310
|
5. Span events：`exception`、`long_task.script`、`long_task.attribution`。
|
|
309
311
|
|
|
310
312
|
分类只用 `span_type`（`session` / `view` / `resource` / `error` / `vital` / `long_task` / `action` / `websocket` / `custom`）和 `outcome.type`（`success` / `warning` / `error` / `timeout` / `abort`）两个字段。当前 SDK **不写** `outcome.reason`，也没有 `event.*` 或 `result` 字段。
|
|
311
313
|
|
|
312
314
|
主要 Span 及其实际产出的领域字段：
|
|
313
315
|
|
|
314
|
-
| Span
|
|
315
|
-
|
|
|
316
|
-
| `session.<phase>`
|
|
317
|
-
| `<view.name>`
|
|
318
|
-
| `<method> <url.template>` | `url.full` / `url.template`、`http.request.method` / `response.status_code`、`resource.type` / `size` / `protocol` / `cache.hit`、DNS/TCP/TLS/首字节/下载阶段
|
|
319
|
-
| Error Span
|
|
320
|
-
| `<VITAL_METRIC>`
|
|
321
|
-
| `click <target>`
|
|
322
|
-
| `blank_screen.<reason>`
|
|
323
|
-
| `<long_task.entry_type>`
|
|
316
|
+
| Span | 领域字段 |
|
|
317
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
318
|
+
| `session.<phase>` | `session.phase`、`session.id`、`session.type`、`session.has_replay`、`session.start_time`、`session.last_activity_time` |
|
|
319
|
+
| `<view.name>` | `view.phase`、`view.version`、`view.url` / `url_template` / `previous*`、`loading_type`、`loading_time` / `loading_time_source`、初始导航 timing、`view.end_reason` |
|
|
320
|
+
| `<method> <url.template>` | `url.full` / `url.template`、`http.request.method` / `response.status_code`、`resource.type` / `size` / `protocol` / `cache.hit`、DNS/TCP/TLS/首字节/下载阶段 |
|
|
321
|
+
| Error Span | `error.message` / `source` / `handled`、`code.filepath` / `lineno` / `column`、`exception` Event |
|
|
322
|
+
| `<VITAL_METRIC>` | `vital.metric` / `value` / `id`，以及 LCP/INP/TTFB 的部分 attribution |
|
|
323
|
+
| `click <target>` | `action.id` / `name` / `type` / `target.*` / `position.*` / `name_source` / `loading_time` / `end_reason` / `frustration.type` |
|
|
324
|
+
| `blank_screen.<reason>` | `blank_screen.reason` / `empty_ratio` / `empty_sample_count` |
|
|
325
|
+
| `<long_task.entry_type>` | `long_task.id` / `entry_type` / `name`，LoAF 的 `blocking_duration` 等，加 script/attribution Event |
|
|
324
326
|
|
|
325
|
-
|
|
327
|
+
Span 起止时间表达观察区间；自动 Action 正常稳定时额外写 `action.loading_time`（毫秒，不含尾部确认等待），中断时只写结束原因。Resource/Error/Long Task 使用 `action.ids` 数组关联，不双写旧单值字段；三个 Action count 继续由服务端派生。完整层级见[RUM 数据模型](./wikis/concepts/data-model.md)，逐字段定义和「当前不会出现的字段」清单见[遥测字段字典](./wikis/reference/telemetry.md)。
|
|
326
328
|
|
|
327
329
|
## 调试
|
|
328
330
|
|
|
@@ -353,23 +355,31 @@ await rum.flush();
|
|
|
353
355
|
|
|
354
356
|
如果有 debug Span、没有请求，检查 CORS/endpoint/exporter；如果没有 Span，检查 Consent、启动、采样、Session/View、能力开关和 beforeSend。完整诊断树见[调试与排障](./wikis/reference/troubleshooting.md)。
|
|
355
357
|
|
|
358
|
+
## Session 与 Action 回归验证
|
|
359
|
+
|
|
360
|
+
在当前包目录执行 `pnpm test:rum-context`，覆盖过期、跨 Tab 协调、事件归属、采样与真实 OTLP 导出。导出测试会短暂监听本机回环地址。
|
|
361
|
+
|
|
362
|
+
`pnpm test:session-browser` 会先构建 CDN 包，再使用独立 Chrome 临时配置运行双 Tab 测试。它以真实鼠标输入验证休眠后首次点击、立即路由和请求关联，以及共享 Session 只发送一次结束提示。默认使用 macOS 的 Chrome 路径，其他环境通过 `BK_RUM_TEST_CHROME` 指定浏览器可执行文件；测试完成后清理浏览器与临时数据。
|
|
363
|
+
|
|
364
|
+
`pnpm test:action-browser` 会构建 CDN 包，再验证真实 DOM 定位、Shadow/插槽隐私以及可信鼠标/键盘点击产生的 OTLP 字段、重叠关联、路由边界和过滤后错误。接收端需按 `action.ids` 数组更新关联与聚合，不保留旧协议双写。
|
|
365
|
+
|
|
356
366
|
## 文档导航
|
|
357
367
|
|
|
358
|
-
| 任务
|
|
359
|
-
|
|
|
360
|
-
| 首次安装和验证
|
|
361
|
-
| 用 AI 安装 Skill 并生成配置
|
|
362
|
-
| 上线检查和容量/隐私/CORS
|
|
363
|
-
| 判断支持范围、默认开关和降级
|
|
364
|
-
| Vue/React/Router/SSR/微前端
|
|
365
|
-
| 理解模块、启动、过滤和导出
|
|
366
|
-
| 理解 OTLP 层级和字段归属
|
|
367
|
-
| 深入单项采集算法和阈值
|
|
368
|
-
| 写自定义插件或接第三方 Instrumentation | [插件与 OpenTelemetry 扩展](./wikis/features/extensions.md)
|
|
369
|
-
| 查全部配置和默认值
|
|
370
|
-
| 查类、方法、类型和扩展 API
|
|
371
|
-
| 查 Span 名和逐字段定义
|
|
372
|
-
| 对齐前后端字段语义和稳定性承诺
|
|
373
|
-
| 查协议、batch、重试和采样
|
|
374
|
-
| 查 Consent 和脱敏边界
|
|
375
|
-
| 解决无数据、重复、缺字段和误报
|
|
368
|
+
| 任务 | 文档 |
|
|
369
|
+
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
370
|
+
| 首次安装和验证 | [快速上手](./wikis/getting-started.md) |
|
|
371
|
+
| 用 AI 安装 Skill 并生成配置 | [用 AI 接入](./wikis/ai-setup.md) |
|
|
372
|
+
| 上线检查和容量/隐私/CORS | [生产接入指南](./wikis/production.md) |
|
|
373
|
+
| 判断支持范围、默认开关和降级 | [能力矩阵](./wikis/capabilities.md) |
|
|
374
|
+
| Vue/React/Router/SSR/微前端 | [框架与路由集成](./wikis/framework-integration.md) |
|
|
375
|
+
| 理解模块、启动、过滤和导出 | [架构与数据流](./wikis/concepts/architecture.md) |
|
|
376
|
+
| 理解 OTLP 层级和字段归属 | [RUM 数据模型](./wikis/concepts/data-model.md) |
|
|
377
|
+
| 深入单项采集算法和阈值 | [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) |
|
|
378
|
+
| 写自定义插件或接第三方 Instrumentation | [插件与 OpenTelemetry 扩展](./wikis/features/extensions.md) |
|
|
379
|
+
| 查全部配置和默认值 | [配置参考](./wikis/reference/configuration.md) |
|
|
380
|
+
| 查类、方法、类型和扩展 API | [API 参考](./wikis/reference/api.md) |
|
|
381
|
+
| 查 Span 名和逐字段定义 | [遥测字段字典](./wikis/reference/telemetry.md) |
|
|
382
|
+
| 对齐前后端字段语义和稳定性承诺 | [RUM 语义约定](./wikis/reference/span-protocol.md) |
|
|
383
|
+
| 查协议、batch、重试和采样 | [上报协议、批处理与采样](./wikis/reference/transport.md) |
|
|
384
|
+
| 查 Consent 和脱敏边界 | [隐私、Consent 与字段治理](./wikis/reference/privacy.md) |
|
|
385
|
+
| 解决无数据、重复、缺字段和误报 | [调试与排障](./wikis/reference/troubleshooting.md) |
|