@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
|
@@ -2,180 +2,110 @@
|
|
|
2
2
|
|
|
3
3
|
# 白屏检测
|
|
4
4
|
|
|
5
|
-
Blank Screen
|
|
5
|
+
Blank Screen 插件检测主要内容区域是否疑似缺少渲染内容。默认开启；DOM 采样提供证据，View 内的活动、文档就绪和可见性决定检查时机。它不做截图或像素扫描，也不把业务可用性等同于 DOM 存在。
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 状态与事件
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
采样结果分为四种：
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
| state | 含义 |
|
|
12
|
+
| --------- | ------------------------------------------------------ |
|
|
13
|
+
| `blank` | 至少 5 个采样点有可解释证据，空白比例达到 threshold |
|
|
14
|
+
| `content` | 有效采样足够，空白比例低于 threshold |
|
|
15
|
+
| `loading` | 大多数采样点被 loading/skeleton 覆盖，或活动长期未结束 |
|
|
16
|
+
| `unknown` | 文档尚未就绪、采样不足、不支持判断的媒体或检测不可用 |
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
- Canvas/WebGL 内部是否真正渲染成功；
|
|
15
|
-
- 内容存在但文本与背景同色；
|
|
16
|
-
- iframe 内部内容；
|
|
17
|
-
- 业务数据错误但页面仍有结构。
|
|
18
|
+
只有稳定窗口中的两次 `blank` 才产生白屏 Error。`loading` 与 `unknown` 是观测状态，不能记为健康，也不计为白屏错误。
|
|
18
19
|
|
|
19
|
-
|
|
20
|
+
每次持续故障生成一个 `blank_screen.id`，只报告一次 `detected`。之后采样恢复为 `content` 时发送 `recovered`，再变白可以生成新故障。View 切换会销毁旧状态，不会把旧 View 的确认或恢复挂到新 View；没有观察到恢复时，不伪造恢复事件。
|
|
20
21
|
|
|
21
|
-
##
|
|
22
|
+
## 配置
|
|
22
23
|
|
|
23
24
|
```ts
|
|
24
25
|
tracking: {
|
|
25
26
|
blankScreen: {
|
|
26
|
-
rootSelector: '
|
|
27
|
+
rootSelector: '#app',
|
|
27
28
|
threshold: 0.8,
|
|
28
29
|
checkDelay: 1000,
|
|
29
30
|
confirmationDelay: 200,
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
}
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
| 字段 | 默认 | 解析规则 |
|
|
36
|
-
| --- | ---: | --- |
|
|
37
|
-
| `rootSelector` | `body` | 空字符串回退 `body` |
|
|
38
|
-
| `threshold` | `0.8` | 有限值限制到 `0..1`，非法值回退默认 |
|
|
39
|
-
| `checkDelay` | `1000ms` | 非负有限值；非法值回退默认 |
|
|
40
|
-
| `confirmationDelay` | `200ms` | 非负有限值；非法值回退默认 |
|
|
41
|
-
| `ignoreSelectors` | `[]` | 追加到内置列表，不替换 |
|
|
42
|
-
|
|
43
|
-
SPA 应优先指定在页面生命周期内稳定存在、且承载主要内容的容器，例如 `#app` 或 `#root`。如果框架会替换初始挂载元素，应让组件根元素保留该 selector，或使用默认的 `body` 检测。
|
|
44
|
-
|
|
45
|
-
## 检测时机
|
|
46
|
-
|
|
47
|
-
每次 View 变化：
|
|
48
|
-
|
|
49
|
-
1. 取消旧 View 的 Timer 和活动监听。
|
|
50
|
-
2. 等待新 View 页面活动结束。
|
|
51
|
-
3. 再等待 `checkDelay`。
|
|
52
|
-
4. 执行第一次九点采样。
|
|
53
|
-
5. 比例达到阈值后，等待 `confirmationDelay`。
|
|
54
|
-
6. 第二次采样仍达到阈值，才上报。
|
|
55
|
-
|
|
56
|
-
页面 hidden 时取消检测；恢复 visible 后，如果当前 View 尚未上报，会重新调度。View 切换会使旧回调失效，避免异步 Timer 把旧结果报到新 View。
|
|
57
|
-
|
|
58
|
-
## 九点采样
|
|
59
|
-
|
|
60
|
-
采样点是视口宽高的 20%、50%、80% 交叉位置：
|
|
61
|
-
|
|
62
|
-
```text
|
|
63
|
-
● ● ●
|
|
64
|
-
|
|
65
|
-
● ● ●
|
|
66
|
-
|
|
67
|
-
● ● ●
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
每个点使用 `elementsFromPoint()` 获取层叠元素；浏览器不支持时退回 `elementFromPoint()`。
|
|
71
|
-
|
|
72
|
-
一个点判为有内容需要满足：
|
|
73
|
-
|
|
74
|
-
- 命中的 Element 位于检测根节点内部（优先 `rootSelector`，缺失时为 `body`）；
|
|
75
|
-
- 不是 root 自身、body 或 documentElement；
|
|
76
|
-
- `display` 不是 `none`；
|
|
77
|
-
- `visibility` 不是 `hidden`；
|
|
78
|
-
- opacity 大于 0。
|
|
79
|
-
|
|
80
|
-
空白比例为：
|
|
81
|
-
|
|
82
|
-
```text
|
|
83
|
-
emptyCount / (9 - ignoredCount)
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
有效采样点为 0 时不判白屏。
|
|
87
|
-
|
|
88
|
-
## Loading 与 Skeleton 忽略
|
|
89
|
-
|
|
90
|
-
以下选择器内置忽略：
|
|
91
|
-
|
|
92
|
-
- `[data-loading="true"]`
|
|
93
|
-
- `[aria-busy="true"]`
|
|
94
|
-
- `.loading`
|
|
95
|
-
- `.is-loading`
|
|
96
|
-
- `.spinner`
|
|
97
|
-
- `.skeleton`
|
|
98
|
-
- `.bk-loading`
|
|
99
|
-
|
|
100
|
-
命中元素本身或祖先匹配任一选择器时，该采样点不进入分母。业务配置会追加：
|
|
101
|
-
|
|
102
|
-
```ts
|
|
103
|
-
tracking: {
|
|
104
|
-
blankScreen: {
|
|
105
|
-
rootSelector: '#app',
|
|
106
|
-
ignoreSelectors: ['.global-loading-mask', '.order-skeleton'],
|
|
31
|
+
maxWait: 10000,
|
|
32
|
+
ignoreSelectors: ['.order-skeleton'],
|
|
107
33
|
},
|
|
108
34
|
}
|
|
109
35
|
```
|
|
110
36
|
|
|
111
|
-
|
|
37
|
+
| 配置 | 默认 | 含义 |
|
|
38
|
+
| ------------------- | --------- | ------------------------------------------------------- |
|
|
39
|
+
| `rootSelector` | `body` | 检测主要业务内容；节点不存在时回退 body/documentElement |
|
|
40
|
+
| `threshold` | `0.8` | 有效采样点中的空白比例，限制到 0..1 |
|
|
41
|
+
| `checkDelay` | `1000ms` | 最后一次相关活动后的稳定等待 |
|
|
42
|
+
| `confirmationDelay` | `200ms` | 空白候选的确认间隔；新活动取消候选 |
|
|
43
|
+
| `maxWait` | `10000ms` | 文档/活动最长等待和低频复检间隔，最小 100ms |
|
|
44
|
+
| `ignoreSelectors` | `[]` | 追加到内置 loading 选择器 |
|
|
112
45
|
|
|
113
|
-
|
|
46
|
+
内置忽略选择器：`[data-loading="true"]`、`[aria-busy="true"]`、`.loading`、`.is-loading`、`.spinner`、`.skeleton`、`.bk-loading`。非法 ignore selector 被忽略；非法 root selector 导致 `unknown/detection_unavailable`。
|
|
114
47
|
|
|
115
|
-
`
|
|
48
|
+
`tracking.view.excludedActivityUrls` 同样排除不相关的请求和资源活动；不要让长轮询无限阻塞稳定判断。
|
|
116
49
|
|
|
117
|
-
|
|
118
|
-
- `body` 中存在足够的可见内容时不报告白屏；
|
|
119
|
-
- 只有回退采样的空白比例仍达到阈值，才进入二次确认；
|
|
120
|
-
- `blank_screen.reason=missing_root`
|
|
121
|
-
- empty ratio 和 `empty_sample_count` 来自回退后的实际检测结果，不是固定 `1`
|
|
122
|
-
- 二次确认仍为空白才上报
|
|
50
|
+
## MPA、SPA 与检查时机
|
|
123
51
|
|
|
124
|
-
|
|
52
|
+
- 首次文档仍为 `readyState=loading` 时不确认白屏；DOMContentLoaded 后重新等待稳定。超出 maxWait 只报告 `unknown/document_not_ready`，不把尚未返回的正文判成白屏。
|
|
53
|
+
- SDK 持续订阅共享活动总线。请求、资源、DOM 变化及错误可触发新检查；首次正常或全被 loading 忽略后不会永久停止。
|
|
54
|
+
- 新活动会取消 check/confirmation 候选并重新等待；pending 请求未完成时不能因切回前台而跳过等待。
|
|
55
|
+
- 等待超过 maxWait，报告 `loading/activity_timeout` 或文档未知；此时不强行把采样空白转成 Error。
|
|
56
|
+
- 没有新活动时也以 maxWait 低频复检，以覆盖 CSS/可见状态变化。连续相同观测状态只报告一次。
|
|
57
|
+
- hidden/freeze 取消检查和未确认候选；恢复可见/resume 重新进入相同稳定规则。检测和复检不会通知 Session 用户活动，不给 Session 续期。
|
|
58
|
+
- SPA 同 View 内的 query 更新、组件崩溃或内容清空仍可以通过活动触发检查。新 View 则重新建立自己的故障状态。
|
|
125
59
|
|
|
126
|
-
|
|
60
|
+
SDK 只能观察它开始运行之后的活动，不能知道此前未被仪器记录的 pending 请求。关键业务内容是否就绪仍可结合业务信号、框架错误与 View Loading Time 诊断。
|
|
127
61
|
|
|
128
|
-
|
|
62
|
+
## 采样证据与成本边界
|
|
129
63
|
|
|
130
|
-
|
|
131
|
-
| --- | --- |
|
|
132
|
-
| `blank_screen.reason` | `missing_root` / `empty_viewport` |
|
|
133
|
-
| `blank_screen.empty_ratio` | 空白有效点比例，即 `emptyCount / validCount` |
|
|
134
|
-
| `blank_screen.empty_sample_count` | 空白点数 |
|
|
64
|
+
对主要内容根节点的可见矩形做 20%、50%、80% 九点采样；根节点缺失或没有尺寸时使用视口。每个点按 `elementsFromPoint()` 从上到下分析：
|
|
135
65
|
|
|
136
|
-
|
|
66
|
+
- 根节点自身的直接文本也可作为内容，通过 Range 判断采样位置是否命中文本。
|
|
67
|
+
- 空布局 div/main 不作为内容，嵌套空壳也一样。
|
|
68
|
+
- 检查祖先的 display/opacity，避免把透明应用容器内的子元素当成可见内容。
|
|
69
|
+
- 不透明的空顶层覆盖会阻止继续使用被遮挡的底层内容；被它挡住的 loading 也不能排除采样。
|
|
70
|
+
- 正常加载的图片、文本及常用原生输入控件可以提供内容证据。
|
|
71
|
+
- Canvas、iframe、WebGL 容器、SVG、背景图和伪元素等无法可靠判断的内容采用 `unknown`，不直接当健康或空白。
|
|
72
|
+
- loading 点不进入有效分母；至少需要 5 个有效点，避免一个空点和八个被忽略点构成白屏结论。
|
|
137
73
|
|
|
138
|
-
|
|
139
|
-
- `outcome.type=error`
|
|
74
|
+
每点最多处理 32 层命中元素、24 层祖先、32 个直接文本节点与 32 个文字矩形。超过可解释范围时保守使用 unknown，不遍历整棵业务 DOM。
|
|
140
75
|
|
|
141
|
-
|
|
76
|
+
这仍是启发式。稀疏页面、复杂裁剪/混合/滤镜、pointer-events 对命中测试的影响、文本与背景同色等不能保证识别。配置 rootSelector 应指向主要业务主体，而不是仅有菜单/导航栏的页面外壳；不要据自动采样单独证明业务不可用。
|
|
142
77
|
|
|
143
|
-
##
|
|
78
|
+
## 上报协议
|
|
144
79
|
|
|
145
|
-
|
|
80
|
+
不保留旧版“每个 View 最多一次、仅三个白屏字段”的兼容分支。
|
|
146
81
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
transport: { endpoint: 'https://rum.example.com' },
|
|
153
|
-
tracking: {
|
|
154
|
-
blankScreen: {
|
|
155
|
-
rootSelector: '#app',
|
|
156
|
-
threshold: 0.8,
|
|
157
|
-
checkDelay: 3000,
|
|
158
|
-
confirmationDelay: 500,
|
|
159
|
-
ignoreSelectors: ['.global-loading', '.skeleton-page'],
|
|
160
|
-
},
|
|
161
|
-
},
|
|
162
|
-
});
|
|
163
|
-
```
|
|
82
|
+
| phase | Span 名 | span_type / outcome.type |
|
|
83
|
+
| ------------- | ------------------------------------------------------------ | ------------------------ |
|
|
84
|
+
| `detected` | `blank_screen.empty_viewport` 或 `blank_screen.missing_root` | `error` / `error` |
|
|
85
|
+
| `recovered` | `blank_screen.recovered` | `custom` / `success` |
|
|
86
|
+
| `observation` | `blank_screen.observation` | `custom` / `unknown` |
|
|
164
87
|
|
|
165
|
-
|
|
166
|
-
- 页面切换有短暂卸载：增加 `confirmationDelay`。
|
|
167
|
-
- 页面布局天然稀疏：提高 `threshold`。
|
|
168
|
-
- Loading 长时间存在：不要简单忽略所有内容；否则有效点可能为 0，真正卡死也不会上报。
|
|
88
|
+
所有事件携带公共 Session/View 上下文；时间戳是本次观测时刻，均为瞬时 Span。detected 不伪造 exception 堆栈。
|
|
169
89
|
|
|
170
|
-
|
|
90
|
+
| 字段 | 含义 |
|
|
91
|
+
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| `blank_screen.phase` / `state` | 生命周期阶段与采样/等待状态 |
|
|
93
|
+
| `blank_screen.strategy_version` | 当前为 2 |
|
|
94
|
+
| `blank_screen.trigger` | view、document_ready、visible 或活动类型 |
|
|
95
|
+
| `blank_screen.reason` | empty_viewport / missing_root，或 loading_visible / insufficient_evidence / activity_timeout / document_not_ready / detection_unavailable |
|
|
96
|
+
| `blank_screen.empty_ratio` | empty / valid；有实际采样时提供 |
|
|
97
|
+
| `blank_screen.empty_sample_count` | 空白点数 |
|
|
98
|
+
| `blank_screen.valid_sample_count` | 空白与内容证据点数 |
|
|
99
|
+
| `blank_screen.ignored_sample_count` | loading 忽略点数 |
|
|
100
|
+
| `blank_screen.unknown_sample_count` | 无法判断的点数 |
|
|
101
|
+
| `blank_screen.id` | 已确认故障及对应恢复共用的关联 ID |
|
|
102
|
+
| `blank_screen.first_detected_at` | 第一次空白候选的 epoch ms |
|
|
103
|
+
| `blank_screen.detected_at` | 二次确认的 epoch ms |
|
|
104
|
+
| `blank_screen.recovered_at` | 恢复观测的 epoch ms，仅 recovered |
|
|
105
|
+
| `blank_screen.duration` | 首次候选到恢复观测的 ms，仅 recovered；包含这期间的后台时间，不代表精确可见故障时长 |
|
|
171
106
|
|
|
172
|
-
|
|
107
|
+
loading/unknown 观测不写入白屏错误计数。恢复事件不增加 Error 数；服务端可以按故障 ID 关联恢复，按 View 聚合故障数量。
|
|
173
108
|
|
|
174
|
-
|
|
175
|
-
2. `rootSelector` 是否指向真正承载内容的稳定节点。
|
|
176
|
-
3. `empty_ratio` 是否只是略高于阈值。
|
|
177
|
-
4. 页面是否用 Canvas、iframe 或背景图承载主要内容。
|
|
178
|
-
5. 异步渲染是否晚于 `checkDelay + confirmationDelay`。
|
|
179
|
-
6. View Loading Activity 是否没有覆盖业务的异步过程。
|
|
109
|
+
## 无法覆盖的启动失败
|
|
180
110
|
|
|
181
|
-
|
|
111
|
+
SDK 和主业务包一起加载且 SDK 尚未执行时，主包下载/执行失败无法由本地白屏插件自报。MPA HTML 本身没有加载 SDK、History 深链接返回错误页面，也有同类盲区。需要独立启动路径、业务启动信号或外部合成探测覆盖，不能靠降低 threshold 解决。
|
|
@@ -18,28 +18,28 @@ SDK 只产生原始 RUM Span：
|
|
|
18
18
|
|
|
19
19
|
## 全部能力
|
|
20
20
|
|
|
21
|
-
| 能力
|
|
22
|
-
|
|
|
23
|
-
| Session
|
|
24
|
-
| View / Router
|
|
25
|
-
| View Loading Time
|
|
26
|
-
| Fetch/XHR
|
|
27
|
-
| Trace Header
|
|
28
|
-
| 静态资源
|
|
29
|
-
| JS Error
|
|
30
|
-
| Promise rejection
|
|
31
|
-
| 资源加载错误
|
|
32
|
-
| Web Vitals
|
|
33
|
-
| 自动 Action
|
|
34
|
-
| 手动 Action
|
|
35
|
-
| Custom event
|
|
36
|
-
| Blank Screen
|
|
37
|
-
| Device
|
|
38
|
-
| Long Task
|
|
39
|
-
| CSP
|
|
40
|
-
| WebSocket
|
|
41
|
-
| RUM Plugin
|
|
42
|
-
| OTel Instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无
|
|
21
|
+
| 能力 | 配置/API | 默认 | 浏览器来源 | 主要 Span | 详情 |
|
|
22
|
+
| -------------------- | ------------------------------------------------------ | -------- | ----------------------------------------- | ----------------------------------------------- | ------------------------------------------- |
|
|
23
|
+
| Session | `session` | 基础能力 | localStorage、活动、visibility、storage | `session.<phase>` | [Session 上下文](./session-context.md) |
|
|
24
|
+
| View / Router | `tracking.view` | auto | Navigation Timing、History、hash、BFCache | `<view.name>` | [View 与路由](./views-routing.md) |
|
|
25
|
+
| View Loading Time | `tracking.view.loadingTime` | 开 | 请求/资源/DOM/`window.open` 活动 | `<view.name>` update | [View 与路由](./views-routing.md) |
|
|
26
|
+
| Fetch/XHR | `tracking.request` | 开 | fetch、XMLHttpRequest、Resource Timing | `<method> <url.template>` CLIENT | [网络](./network.md) |
|
|
27
|
+
| Trace Header | `allowedTracingUrls` | 无白名单 | W3C Trace Context | 被观测请求的 `traceparent` + Resource Span Link | [网络](./network.md) |
|
|
28
|
+
| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `GET <url.template>` CLIENT | [网络](./network.md) |
|
|
29
|
+
| JS Error | `tracking.error` | 开 | window error | `<exception.type>` | [错误与安全](./errors-security.md) |
|
|
30
|
+
| Promise rejection | `tracking.error` | 开 | unhandledrejection | `<exception.type>` | [错误与安全](./errors-security.md) |
|
|
31
|
+
| 资源加载错误 | `tracking.error` | 开 | capture error | `ResourceError` | [错误与安全](./errors-security.md) |
|
|
32
|
+
| Web Vitals | `tracking.webVitals` | 开 | web-vitals、PerformanceObserver | `<VITAL>` | [性能体验](./performance.md) |
|
|
33
|
+
| 自动 Action | `tracking.action` | 开 | click、Activity 总线 | `click <target>` | [用户操作](./actions.md) |
|
|
34
|
+
| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `<action.name>`（`action.type=custom`） | [用户操作](./actions.md) |
|
|
35
|
+
| Custom event | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | [API](./api.md) |
|
|
36
|
+
| Blank Screen | `tracking.blankScreen` | 开 | DOM 九点采样、页面活动 | `blank_screen.<reason>` | [白屏](./blank-screen.md) |
|
|
37
|
+
| Device | `tracking.device` | 开 | UA/UA-CH、Screen、Network Information | Resource/运行时属性 | [Session 上下文](./session-context.md) |
|
|
38
|
+
| Long Task | `tracking.longTask` | 关 | LoAF 或 Long Tasks | `<long_task.entry_type>` | [性能体验](./performance.md) |
|
|
39
|
+
| CSP | `tracking.cspViolation` | 关 | securitypolicyviolation | `csp.<effective_directive>` | [错误与安全](./errors-security.md) |
|
|
40
|
+
| WebSocket | `tracking.websocket` | 关 | WebSocket constructor/events | `websocket.<phase>` CLIENT | [网络](./network.md) |
|
|
41
|
+
| RUM Plugin | `extensions.plugins` / `use()` | 无 | 插件决定 | `context.startSpan()` | [扩展](./extensions.md) |
|
|
42
|
+
| OTel Instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | instrumentation 决定 | instrumentation Span | [扩展](./extensions.md) |
|
|
43
43
|
|
|
44
44
|
“默认开”仍要求 `enabled: true`、Consent 为 granted、SDK 已 start、Session 被采样。浏览器缺少所需 API 时对应插件通常静默降级。
|
|
45
45
|
|
|
@@ -70,15 +70,15 @@ Session、Activity、Page View 关联基础不提供整体关闭开关。`tracki
|
|
|
70
70
|
|
|
71
71
|
## Session 与公共上下文
|
|
72
72
|
|
|
73
|
-
| 项目
|
|
74
|
-
|
|
|
75
|
-
| 无活动超时
|
|
76
|
-
| 最大生命周期 | 固定 4 小时
|
|
77
|
-
| 跨 Tab
|
|
78
|
-
| 存储失败
|
|
79
|
-
| 采样
|
|
80
|
-
| 用户
|
|
81
|
-
| 设备 ID
|
|
73
|
+
| 项目 | 当前行为 |
|
|
74
|
+
| ------------ | ------------------------------------------ |
|
|
75
|
+
| 无活动超时 | 固定 15 分钟 |
|
|
76
|
+
| 最大生命周期 | 固定 4 小时 |
|
|
77
|
+
| 跨 Tab | localStorage + storage event |
|
|
78
|
+
| 存储失败 | 回退进程内存 |
|
|
79
|
+
| 采样 | `application.name + session.id` 稳定 hash |
|
|
80
|
+
| 用户 | 业务传 `user.id`，原样透传 |
|
|
81
|
+
| 设备 ID | 默认每次 Device 插件初始化生成；可选持久化 |
|
|
82
82
|
|
|
83
83
|
Session Span 包括 start/rotate/end；View、Action、Resource 等通过 ID 属性关联，不要求它们共享同一个 Trace。
|
|
84
84
|
|
|
@@ -91,9 +91,11 @@ View 类型：
|
|
|
91
91
|
- `bf_cache`：BFCache 恢复；
|
|
92
92
|
- `session_renewal`：Session 轮换后重建 View。
|
|
93
93
|
|
|
94
|
-
每个 View 产生 start/update/end 生命周期 Span，`view.version` 递增。Loading Time 等待页面活动安静后更新；隐藏页面会取消当前自动计算，业务可用 `setViewLoadingTime()`
|
|
94
|
+
每个 View 产生 start/update/end 生命周期 Span，`view.version` 递增。Loading Time 等待页面活动安静后更新；隐藏页面会取消当前自动计算，业务可用 `setViewLoadingTime()` 手动确认。每 60 秒、flush、隐藏和冻结时补充累计快照，包含 `view.time_spent`、`view.foreground_time`、`view.is_active` 和有界页面状态历史；这些检查点不会续期 Session。
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
自动跟踪支持 `routeMode: auto | hash | history | document`。query-only 更新 URL 上下文但不创建 View；Hash 模式的模板来自逻辑路由，History 来自 pathname，document 忽略同文档导航。默认 `view.url_template` 把数字 ID、UUID 和长十六进制段折叠为 `:id`，非数字动态段应通过 `getUrlTemplate` 或 `startView({ urlTemplate })` 显式提供。`trackVueRouterViews()` 可在手动模式下从成功导航及 matched 路由生成 View。
|
|
97
|
+
|
|
98
|
+
支持 `getViewContext()`、`setViewContext()`、`setViewContextProperty()` 和 `addTiming()`；运行期更新只从调用时刻生效，不改写历史事件归属。
|
|
97
99
|
|
|
98
100
|
## 网络与资源
|
|
99
101
|
|
|
@@ -122,37 +124,41 @@ SDK 不做错误节流、fingerprint 和分组。CSP 插件每次 violation 建
|
|
|
122
124
|
|
|
123
125
|
## Web Vitals 与 Long Task
|
|
124
126
|
|
|
125
|
-
Vitals：CLS、FCP、INP、LCP、TTFB
|
|
127
|
+
Vitals：CLS、FCP、INP、LCP、TTFB。Span 带 `vital.metric`、`vital.value`、稳定 `vital.id`、递增 `vital.version` 和 `vital.scope`；内部 rating 映射为 `outcome.type`。CLS/INP 按条目发生时间归属 View，结束后的有界状态可接收迟到条目；flush、隐藏和 shutdown 生成变更快照。文档 FCP/LCP/TTFB 固定归属初始 View，BFCache 使用 activation 作用域。提供 CLS/INP selector 与时间归因、LCP/TTFB 阶段归因。接收端取最新版本，不累加指标快照。详见[性能体验](./performance.md)。
|
|
126
128
|
|
|
127
129
|
Long Task 优先 Long Animation Frame 获取脚本归因，不支持时回退 Long Tasks。默认关闭，threshold 默认 50ms。
|
|
128
130
|
|
|
129
131
|
## Action 与白屏
|
|
130
132
|
|
|
131
|
-
Action
|
|
133
|
+
自动 Action 接收可见页面中的可信主键 click，保留键盘激活 click，以点击后的页面活动窗口建模。Resource/Error/Long Task 使用 `action.ids` 数组关联全部匹配区间，Action 自身仍是单个 `action.id`；未声明类型的通用 Span 不自动推测关联。可识别：
|
|
132
134
|
|
|
133
135
|
- rage click：短时间相近位置的点击链；
|
|
134
|
-
- error click
|
|
136
|
+
- error click：通过过滤进入发送流且关联该 Action 的错误；
|
|
135
137
|
- dead click：没有有效副作用且满足排除条件。
|
|
136
138
|
|
|
137
|
-
默认只从显式 data attribute 命名，不读取任意 DOM
|
|
139
|
+
默认只从显式 data attribute 命名，不读取任意 DOM 文本。可采集有界 selector/composed path、目标尺寸、相对坐标及名称来源。文本模式不读输入值；`data-bk-privacy=mask` 阻止文本/可访问名称，仍允许显式标签；hidden 目标或祖先使整个自动 Action 被跳过。
|
|
140
|
+
|
|
141
|
+
自动 Action 在 View/Session 边界及页面隐藏/退出时关闭，已开始请求晚到保留原关联。仅正常页面稳定时写 `action.loading_time`（毫秒）；无活动、超时和中断以 `action.end_reason` 区分。Error/Long Task 不延长加载窗口，Span 起止时间记录已观察时间。普通 flush 不强制结束动作。
|
|
142
|
+
|
|
143
|
+
Rage 仍为三次独立点击各自标记，不做合并或分组。`reportAction()` 是瞬时事件；持续型手动 Action API 尚未提供。错误、资源和长任务计数继续由服务端根据 `action.ids` 派生。
|
|
138
144
|
|
|
139
|
-
|
|
145
|
+
白屏等待文档就绪、页面可见和活动稳定，对主要内容区域九点采样并连续确认两次。持续复检，区分 blank/content/loading/unknown；每次故障有独立 ID，检测与恢复关联，恢复后可报告新故障。只有 detected 计入 Error，证据不足和加载态只发送 observation。它是启发式检测，Canvas/iframe 等无法判断的内容按 unknown 处理。
|
|
140
146
|
|
|
141
147
|
## 浏览器降级矩阵
|
|
142
148
|
|
|
143
|
-
| 缺失/限制
|
|
144
|
-
|
|
|
149
|
+
| 缺失/限制 | 降级结果 |
|
|
150
|
+
| ------------------------------------- | ------------------------------------------------- |
|
|
145
151
|
| `PerformanceObserver` 不支持 resource | Fetch/XHR 基础 Span仍可有；资源时序和静态资源跳过 |
|
|
146
|
-
| Long Animation Frame 不支持
|
|
147
|
-
| 两种长任务 API 都不支持
|
|
148
|
-
| Event Timing/指标 API 不支持
|
|
149
|
-
| 跨域资源无 TAO
|
|
150
|
-
| Network Information 不支持
|
|
151
|
-
| UA-CH 不支持
|
|
152
|
-
| localStorage 抛错
|
|
153
|
-
| `elementsFromPoint` 不支持
|
|
154
|
-
| 插件 init 抛错
|
|
155
|
-
| 页面快速退出
|
|
152
|
+
| Long Animation Frame 不支持 | 尝试 Long Tasks API |
|
|
153
|
+
| 两种长任务 API 都不支持 | 不产生 Long Task，不阻断页面 |
|
|
154
|
+
| Event Timing/指标 API 不支持 | 对应 Vital 缺失，不伪造 |
|
|
155
|
+
| 跨域资源无 TAO | 详细 timing/size 可能缺失 |
|
|
156
|
+
| Network Information 不支持 | network.\* 运行时字段缺失 |
|
|
157
|
+
| UA-CH 不支持 | 回退 userAgent 解析 |
|
|
158
|
+
| localStorage 抛错 | Session/Device 持久化退回内存 |
|
|
159
|
+
| `elementsFromPoint` 不支持 | 白屏使用单个 `elementFromPoint` |
|
|
160
|
+
| 插件 init 抛错 | 隔离插件；debug 模式警告 |
|
|
161
|
+
| 页面快速退出 | flush/keepalive 尽力发送，不保证交付 |
|
|
156
162
|
|
|
157
163
|
## SDK 明确不提供
|
|
158
164
|
|
|
@@ -170,16 +176,16 @@ Action 以点击后的副作用窗口建模，关联请求、DOM、错误和页
|
|
|
170
176
|
|
|
171
177
|
## 成本和风险选择
|
|
172
178
|
|
|
173
|
-
| 入口
|
|
174
|
-
|
|
|
175
|
-
| `session.sampleRate` | 全局 Span 量
|
|
176
|
-
| `resource`
|
|
177
|
-
| `longTask`
|
|
178
|
-
| `cspViolation`
|
|
179
|
-
| `websocket`
|
|
180
|
-
| Action `text`
|
|
181
|
-
| Device persistent ID | 跨 Session 关联
|
|
182
|
-
| traceparent
|
|
179
|
+
| 入口 | 主要影响 | 建议 |
|
|
180
|
+
| -------------------- | -------------------------- | --------------------------------- |
|
|
181
|
+
| `session.sampleRate` | 全局 Span 量 | 先测平均 Span/Session，再定比例 |
|
|
182
|
+
| `resource` | 页面资源多时事件量大 | 通常保留；用服务端采样/聚合 |
|
|
183
|
+
| `longTask` | 卡顿高时大量事件和脚本字段 | 问题驱动、小流量开启 |
|
|
184
|
+
| `cspViolation` | 策略异常时事件风暴 | 先评估并脱敏 original policy |
|
|
185
|
+
| `websocket` | 全局构造器 patch、长连接 | 只在连接可观测确有需求时开 |
|
|
186
|
+
| Action `text` | DOM 文本隐私 | 保持 explicit，使用稳定 data name |
|
|
187
|
+
| Device persistent ID | 跨 Session 关联 | 需 Consent/存储政策支持 |
|
|
188
|
+
| traceparent | CORS 与第三方泄露 | 精确 allowlist |
|
|
183
189
|
|
|
184
190
|
## 阅读路径
|
|
185
191
|
|