@blueking/open-telemetry 0.0.23 → 0.0.24
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 +1 -3
- package/dist/bk-rum.global.js +2 -2
- package/dist/bk-rum.global.js.map +1 -1
- package/dist/core/processor.d.ts +2 -2
- package/dist/core/runtime-context.d.ts +4 -0
- package/dist/core/sampling.d.ts +0 -1
- package/dist/index.js +348 -360
- package/dist/index.js.map +1 -1
- package/dist/plugins/common.d.ts +1 -2
- package/dist/plugins/web-vitals.d.ts +0 -5
- package/dist/schema/attributes.d.ts +0 -1
- package/package.json +1 -1
- package/skills/bk-rum-otele/references/api.md +2 -2
- package/skills/bk-rum-otele/references/configuration.md +1 -1
- package/skills/bk-rum-otele/references/data-model.md +2 -3
- package/skills/bk-rum-otele/references/extensions.md +0 -1
- package/skills/bk-rum-otele/references/performance.md +0 -1
- package/skills/bk-rum-otele/references/privacy.md +1 -1
- package/skills/bk-rum-otele/references/production.md +0 -2
- package/skills/bk-rum-otele/references/session-context.md +1 -1
- package/skills/bk-rum-otele/references/telemetry-reference.md +5 -26
- package/skills/bk-rum-otele/references/transport-sampling.md +0 -3
package/dist/plugins/common.d.ts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import { REQUEST_DISCARD_ATTRIBUTE } from '../core/processor';
|
|
2
1
|
import type { BkOTRequestConfig, BkOTRequestContext, BkOTRequestOutcome } from '../core/config';
|
|
3
2
|
import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
|
|
4
3
|
import type { Span } from '@opentelemetry/api';
|
|
@@ -7,6 +6,6 @@ interface RequestDetails {
|
|
|
7
6
|
startedAt?: number;
|
|
8
7
|
url?: string;
|
|
9
8
|
}
|
|
10
|
-
export { REQUEST_DISCARD_ATTRIBUTE };
|
|
11
9
|
export declare const decorateRequestSpan: (context: BkOTRuntimeContext, span: Span, subtype: "fetch" | "xhr", domainContext: BkOTRequestContext, outcome: BkOTRequestOutcome, details?: RequestDetails) => void;
|
|
12
10
|
export declare const createCommonInstrumentationsPlugin: (option: BkOTRequestConfig | boolean | undefined) => BkOTPlugin;
|
|
11
|
+
export {};
|
|
@@ -10,11 +10,6 @@
|
|
|
10
10
|
*
|
|
11
11
|
* 数值语义:CLS 是无量纲分数,FCP/INP/LCP/TTFB 的 vital.value 单位为 ms。
|
|
12
12
|
*
|
|
13
|
-
* Navigation Type:
|
|
14
|
-
* 优先使用 metric.navigationType(web-vitals 内部计算,含 'back-forward-cache' 等准确值),
|
|
15
|
-
* fallback 到 PerformanceNavigationTiming.type(注意 web-vitals 用连字符 'back-forward',
|
|
16
|
-
* PerformanceNavigationTiming 用下划线 'back_forward',统一成连字符)。
|
|
17
|
-
*
|
|
18
13
|
* View 边界:FCP/LCP/TTFB 使用 web-vitals 的条目时间回查历史 View;CLS/INP 按 SDK View 重置,
|
|
19
14
|
* CLS 使用 session window,INP 使用当前 View 的 p98 交互候选。
|
|
20
15
|
*
|
|
@@ -27,7 +27,6 @@ export declare const RUM_ATTRIBUTES: {
|
|
|
27
27
|
readonly nextHopProtocol: "resource.protocol";
|
|
28
28
|
readonly outcomeReason: "outcome.reason";
|
|
29
29
|
readonly outcomeType: "outcome.type";
|
|
30
|
-
readonly rumSchemaVersion: "rum.schema.version";
|
|
31
30
|
readonly serviceName: "service.name";
|
|
32
31
|
readonly serviceVersion: "service.version";
|
|
33
32
|
readonly osName: "os.name";
|
package/package.json
CHANGED
|
@@ -206,9 +206,9 @@ interface BkOTCustomEventPayload {
|
|
|
206
206
|
}
|
|
207
207
|
```
|
|
208
208
|
|
|
209
|
-
产出 Span 名为 `custom.<name>`,同时写 `
|
|
209
|
+
产出 Span 名为 `custom.<name>`,同时写 `span_type=custom`。有 `error` 时记录 exception Event,将 `outcome.type` 和 Span Status 设为 error;没有 error 时 `outcome.type=success`。
|
|
210
210
|
|
|
211
|
-
`name` 会进入 Span name
|
|
211
|
+
`name` 会进入 Span name,必须使用非空的有限枚举,不要拼订单号、URL、用户输入等高基数内容。运行时没有非空校验:空字符串会生成 `custom.` Span,不会仅因 name 为空抛错或自动丢弃,但这类数据没有可用语义。未采样时静默丢弃;`debug: true` 会额外打印 dropped warning。
|
|
212
212
|
|
|
213
213
|
## 扩展注册 API
|
|
214
214
|
|
|
@@ -110,7 +110,7 @@ context: {
|
|
|
110
110
|
|
|
111
111
|
Hook 每次调用都应返回新的普通对象,且不能抛异常。SDK 不 hash、不改写 `user.id`。如果 ID 敏感,接入方必须在传入前完成不可逆处理。
|
|
112
112
|
|
|
113
|
-
未配置 `attributes.page`
|
|
113
|
+
未配置 `attributes.page` 时默认返回空对象。页面地址由 `view.url` 表达,低基数路由由 `view.url_path_group` 表达;该 Hook 只用于补充业务自定义的页面维度。
|
|
114
114
|
|
|
115
115
|
属性合并优先级不是全局统一的:各插件会先组合公共字段、Hook 字段和事件字段,`startSpan()` 再用运行时上下文作为底层。精确字段请以对应能力页和[RUM 数据模型](./data-model.md)为准。
|
|
116
116
|
|
|
@@ -27,7 +27,7 @@ resourceSpans[]
|
|
|
27
27
|
|
|
28
28
|
| 层级 | 示例 | 生命周期 | 负责方 |
|
|
29
29
|
| ------------------ | ----------------------------------------------------------- | ------------- | -------------------------- |
|
|
30
|
-
| Resource | `service.name`、`
|
|
30
|
+
| Resource | `service.name`、`telemetry.sdk.version`、`session.sample_rate` | SDK 实例固定 | 配置解析和 Device Resource |
|
|
31
31
|
| OpenTelemetry Span | `traceId`、`spanId`、`kind`、开始/结束时间、Status | 单个 Span | OpenTelemetry Provider |
|
|
32
32
|
| RUM 运行时上下文 | `session.id`、`view.id`、`action.id`、`user.id` | 随运行时变化 | `RumRuntimeContext` |
|
|
33
33
|
| RUM 分类与结果 | `span_type`、`outcome.type`、`outcome.reason` | 单个原始 Span | 内置插件或手动 API |
|
|
@@ -44,7 +44,6 @@ Resource 在构造时创建,同一 SDK 实例的全部 Span 共用。基础字
|
|
|
44
44
|
| `service.name` | `application.name` |
|
|
45
45
|
| `service.version` | `application.version`,未配置时不存在 |
|
|
46
46
|
| `deployment.environment.name` | `application.environment`,默认 `production` |
|
|
47
|
-
| `rum.schema.version` | 固定 `3` |
|
|
48
47
|
| `session.sample_rate` | 解析后的 `session.sampleRate` |
|
|
49
48
|
| `telemetry.sdk.name` | 固定 `@blueking/open-telemetry` |
|
|
50
49
|
| `telemetry.sdk.language` | 固定 `webjs` |
|
|
@@ -135,7 +134,7 @@ HTTP Result 规则:
|
|
|
135
134
|
|
|
136
135
|
- `startView({ attributes })` 会删除所有 SDK 保留字段,不能覆盖 Session、View、分类和采样字段。
|
|
137
136
|
- `reportAction()` 的固定 Action/分类字段在自定义 attributes 之后写入,不能被 payload 覆盖。
|
|
138
|
-
- `reportCustomEvent()`
|
|
137
|
+
- `reportCustomEvent()` 的固定分类字段在 payload attributes 之后写入,业务不能覆盖;事件名称只写入 Span name。
|
|
139
138
|
- 直接调用 `startSpan()` 属于高级 API,调用方对字段正确性负责。
|
|
140
139
|
|
|
141
140
|
## URL 与属性脱敏
|
|
@@ -111,7 +111,6 @@ const visibilityPlugin = createPlugin({
|
|
|
111
111
|
...buildRumSpanAttributes({
|
|
112
112
|
spanType: RUM_SPAN_TYPE.custom,
|
|
113
113
|
}),
|
|
114
|
-
'rum.custom.name': 'visibility_change',
|
|
115
114
|
'document.visibility_state': document.visibilityState,
|
|
116
115
|
},
|
|
117
116
|
{ startTime: occurredAt },
|
|
@@ -102,7 +102,7 @@ tracking: {
|
|
|
102
102
|
- `redactUrl`:隐私和敏感数据边界;
|
|
103
103
|
- `getPathGroup`:聚合维度和查询基数。
|
|
104
104
|
|
|
105
|
-
|
|
105
|
+
未配置 `context.attributes.page` 时默认返回空对象,不存在独立的默认页面属性路径。页面地址统一由经过 `redactUrl` 的 `view.url` 表达,聚合维度使用 `view.url_path_group`;业务通过该 Hook 添加的属性仍需自行确保不包含敏感信息。
|
|
106
106
|
|
|
107
107
|
## 属性脱敏
|
|
108
108
|
|
|
@@ -109,7 +109,6 @@ SDK 不在浏览器做错误指纹。服务端应基于 stack/message 归一规
|
|
|
109
109
|
至少审查:
|
|
110
110
|
|
|
111
111
|
- URL path/query/fragment;
|
|
112
|
-
- 默认 `rum.page.path`(它不经过 `redactUrl` / `getPathGroup`);
|
|
113
112
|
- `user.id`;
|
|
114
113
|
- Error message 和 stack;
|
|
115
114
|
- Action 显式名称或 DOM 文本;
|
|
@@ -245,7 +244,6 @@ SDK 设计为:
|
|
|
245
244
|
- 资源网络阶段只在浏览器可见时出现;
|
|
246
245
|
- IP/geo、错误指纹、聚合数不是 SDK 字段;
|
|
247
246
|
- 事件时间直接使用 OTLP envelope 的 `startTimeUnixNano/endTimeUnixNano` 纳秒字符串;
|
|
248
|
-
- Schema version 当前是 Resource `rum.schema.version=3`。
|
|
249
247
|
|
|
250
248
|
字段级规则见[遥测字段字典](./telemetry-reference.md)。
|
|
251
249
|
|
|
@@ -174,7 +174,7 @@ context: {
|
|
|
174
174
|
}
|
|
175
175
|
```
|
|
176
176
|
|
|
177
|
-
|
|
177
|
+
未配置时默认返回空对象。页面地址使用 `view.url`,低基数路由使用 `view.url_path_group`;业务需要额外页面维度时可自行返回。
|
|
178
178
|
|
|
179
179
|
Hook 每次执行,应保持低成本且不要抛错。它可能包含高基数字段,但服务端聚合维度应只选择稳定、低基数属性。
|
|
180
180
|
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
| 层级 | 主要字段 | 适合回答的问题 |
|
|
12
12
|
| ---- | -------- | -------------- |
|
|
13
|
-
| SDK 与应用 Resource | `service.*`、`deployment.environment.name`、`
|
|
13
|
+
| SDK 与应用 Resource | `service.*`、`deployment.environment.name`、`telemetry.sdk.*` | 哪个应用、环境、版本和 SDK 产生了数据? |
|
|
14
14
|
| RUM 运行时上下文 | `session.id`、`view.id`、`action.id`、`user.id`、设备和网络字段 | 事件属于哪个 Session、View、Action 和用户上下文? |
|
|
15
15
|
| 公共分类 | `span_type`、`outcome.type`、`outcome.reason` | 这是什么信号,结果是否正常,失败属于哪类原因? |
|
|
16
16
|
| 领域属性 | `resource.*`、`error.*`、`vital.*`、`long_task.*` 等 | 具体发生了什么,耗时、来源和诊断细节是什么? |
|
|
@@ -70,7 +70,6 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境,同一实
|
|
|
70
70
|
| `service.name` | string | 必有 | 来自 `application.name`。标识被监控的前端应用,是按应用聚合、路由和授权的主维度。 |
|
|
71
71
|
| `service.version` | string | 配置 `application.version` 时 | 来自应用版本配置,通常填写发布版本或构建号,用于比较发布前后性能和错误变化。 |
|
|
72
72
|
| `deployment.environment.name` | string | 必有 | 来自 `application.environment`,未配置时为 `production`。用于区分生产、预发布、测试等环境。 |
|
|
73
|
-
| `rum.schema.version` | string | 必有 | 当前固定为 `3`。这是 SDK 的 RUM 字段模型版本,不是 npm 包版本。 |
|
|
74
73
|
| `session.sample_rate` | number | 必有 | 解析后的 `session.sampleRate`,范围 `0..1`。表示配置的 Session 采样概率,不表示当前某条 Span 的采样结果。 |
|
|
75
74
|
| `telemetry.sdk.name` | string | 必有 | 固定为 `@blueking/open-telemetry`,用于识别数据生产 SDK。 |
|
|
76
75
|
| `telemetry.sdk.language` | string | 必有 | 固定为 `webjs`,表示浏览器 JavaScript SDK。 |
|
|
@@ -112,14 +111,7 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境,同一实
|
|
|
112
111
|
| `network.rtt` | number | Network Information API 支持 | 浏览器估算的往返时延,单位 ms,通常经过舍入;不是当前某个 Resource 请求的实测 RTT。 |
|
|
113
112
|
| `network.save_data` | boolean | Network Information API 支持 | 用户是否开启节省流量偏好;`true` 可用于解释图片降质或资源加载策略差异。 |
|
|
114
113
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
| 字段 | 类型 | 条件 | 来源与详细说明 |
|
|
118
|
-
| --------------- | ------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
119
|
-
| `rum.page.host` | string | 未自定义 `context.attributes.page` | 当前 `location.host`,包含显式端口,不包含协议、路径、query 或 hash。适合区分域名/端口部署。 |
|
|
120
|
-
| `rum.page.path` | string | 未自定义 `context.attributes.page` | 当前原始 `location.pathname`,不含 query/hash,但不会自动模板化动态路径段。高基数聚合应优先使用 `view.url_path_group`。 |
|
|
121
|
-
|
|
122
|
-
自定义 `context.attributes.page()` 会完全替换这两个默认字段。`rum.page.path` 不等于 `view.url`:前者是创建 Span 时读取的原始 pathname,只经过 `redactAttributes`;后者是 View 创建时冻结并经过 `redactUrl` 的完整 URL。
|
|
114
|
+
默认 `context.attributes.page()` 返回空对象,不附加独立页面属性。页面地址使用 View 创建时冻结并经过 `redactUrl` 的 `view.url`,低基数路由聚合使用 `view.url_path_group`;业务需要额外页面维度时可自定义该 Hook。
|
|
123
115
|
|
|
124
116
|
## RUM 公共分类字段
|
|
125
117
|
|
|
@@ -148,7 +140,7 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境,同一实
|
|
|
148
140
|
| `browser.long_task` | INTERNAL | `long_task` | `long_task.entry_type` | `tracking.longTask`,默认关闭 | Long Animation Frame,或不支持时回退的 Long Task。 |
|
|
149
141
|
| `csp.violation` | INTERNAL | `error` | `error.source=csp` | `tracking.cspViolation`,默认关闭 | 浏览器 `securitypolicyviolation` 事件。 |
|
|
150
142
|
| `browser.websocket` | CLIENT | `websocket` | `websocket.phase` | `tracking.websocket`,默认关闭 | 同一 WebSocket 连接的四类生命周期事件。 |
|
|
151
|
-
| `custom.<name>` | INTERNAL | `custom` |
|
|
143
|
+
| `custom.<name>` | INTERNAL | `custom` | Span 名 | `reportCustomEvent` | 主动上报的业务事件。 |
|
|
152
144
|
|
|
153
145
|
## Session 字段
|
|
154
146
|
|
|
@@ -277,7 +269,6 @@ Session Span 允许没有 `view.id`:SDK 先建立 Session,再创建初始 Vi
|
|
|
277
269
|
| `vital.value` | number | 必有 | 指标值。CLS 是无量纲分数;FCP、INP、LCP、TTFB 单位均为 ms。非有限值不会上报。 |
|
|
278
270
|
| `vital.rating` | string | 必有 | `good`、`needs-improvement` 或 `poor`。当前 good/needs-improvement/poor 分界:CLS `≤0.1/≤0.25/>0.25`;INP `≤200/≤500/>500ms`;FCP `≤1800/≤3000/>3000ms`;LCP `≤2500/≤4000/>4000ms`;TTFB `≤800/≤1800/>1800ms`。 |
|
|
279
271
|
| `vital.id` | string | 必有 | 单条 Vital 的唯一 ID。FCP/LCP/TTFB 沿用 `web-vitals` ID;按 View 汇总的 CLS/INP 由 SDK 生成。 |
|
|
280
|
-
| `rum.navigation.type` | string | 必有 | 导航类型,可能为 `navigate`、`reload`、`back-forward`、`back-forward-cache`、`prerender`、`restore`、`unknown`。优先取 metric 值,否则回退到 Navigation Timing 并统一连字符。 |
|
|
281
272
|
|
|
282
273
|
`vital.rating=good` 映射为 `outcome.type=success`;其他评级映射为 `outcome.type=warning`。具体体验评级由 `vital.rating` 表达,不重复写入 `outcome.reason`。
|
|
283
274
|
|
|
@@ -457,17 +448,16 @@ Legacy Long Task 的每个 attribution 条目生成一个 Event,Event 时间
|
|
|
457
448
|
|
|
458
449
|
| 字段 | 类型 | 条件 | 来源与详细说明 |
|
|
459
450
|
| ----------------- | ------ | ------------------- | ----------------------------------------------------------------------------------------- |
|
|
460
|
-
| `rum.custom.name` | string | 必有 | 调用方传入的 `name`,同时用于 Span 名后缀。应使用稳定低基数名称,不要放用户 ID 或随机值。 |
|
|
461
451
|
| `span_type` | string | 必有,固定 `custom` | 将主动业务事件归入 Custom 类别。 |
|
|
462
452
|
| `outcome.type` | string | 必有 | 没有 `error` 时为 `success`;传入 Error 时为 `error`。 |
|
|
463
453
|
|
|
464
|
-
Custom Event 还会依次合并 `context.attributes.page()`、`context.attributes.custom()` 和 payload `attributes`,最后统一经过 `redactAttributes`。业务自定义值必须符合 OpenTelemetry Attribute 类型:string、number、boolean 或相应数组;不要传对象、函数或嵌套 JSON。业务应避免覆盖 `span_type`、`outcome.*` 等保留字段。
|
|
454
|
+
调用方传入的 `name` 只进入 Span 名 `custom.<name>`,应使用稳定低基数名称,不要放用户 ID、随机值或其他用户输入。Custom Event 还会依次合并 `context.attributes.page()`、`context.attributes.custom()` 和 payload `attributes`,最后统一经过 `redactAttributes`。业务自定义值必须符合 OpenTelemetry Attribute 类型:string、number、boolean 或相应数组;不要传对象、函数或嵌套 JSON。业务应避免覆盖 `span_type`、`outcome.*` 等保留字段。
|
|
465
455
|
|
|
466
456
|
## 业务扩展与外部 Instrumentation 字段
|
|
467
457
|
|
|
468
458
|
固定字典无法穷举以下接入方字段:
|
|
469
459
|
|
|
470
|
-
- `context.attributes.page()`:合并到 SDK 创建的多数 Span
|
|
460
|
+
- `context.attributes.page()`:合并到 SDK 创建的多数 Span;未配置时默认返回空对象。
|
|
471
461
|
- `context.attributes.error()`:合并到三类自动错误 Span。
|
|
472
462
|
- `context.attributes.custom()`:合并到 `custom.<name>`。
|
|
473
463
|
- `startView({ attributes })`:合并到该 View 的生命周期 Span 和运行时上下文,但 SDK 会过滤 RUM 保留字段,避免覆盖核心关联关系。
|
|
@@ -478,17 +468,6 @@ Custom Event 还会依次合并 `context.attributes.page()`、`context.attribute
|
|
|
478
468
|
|
|
479
469
|
过滤器会读取第三方 HTTP Instrumentation 常用的 `http.url`,以识别并丢弃指向 SDK Collector 的自身上报请求;BK RUM 内置请求插件实际写入的是 `url.full`,不会主动产生 `http.url`。
|
|
480
470
|
|
|
481
|
-
## SDK 内部但不会上报的属性
|
|
482
|
-
|
|
483
|
-
源码中还存在以下内部控制属性,它们不是对外遥测协议:
|
|
484
|
-
|
|
485
|
-
| 内部属性 | 用途 | 为什么不会出现在 Collector 数据中 |
|
|
486
|
-
| ------------------------ | --------------------------------------------------- | ---------------------------------------------------------- |
|
|
487
|
-
| `bk.rum.sampled` | 在运行时上下文中传递当前 Session 的确定性采样结果 | SpanProcessor 在调用业务 `beforeSend` 和 Exporter 前删除。 |
|
|
488
|
-
| `bk.rum.request.discard` | 标记被请求级 `beforeSend` 主动丢弃的 Fetch/XHR Span | SpanProcessor 识别后直接不导出整条 Span。 |
|
|
489
|
-
|
|
490
|
-
看到这两个名称不应为后端创建索引或查询规则。
|
|
491
|
-
|
|
492
471
|
## 当前不会出现的字段和信号
|
|
493
472
|
|
|
494
473
|
当前源码不会产生:
|
|
@@ -35,7 +35,6 @@ https://rum.example.com/collector/v1/rum
|
|
|
35
35
|
"resource": {
|
|
36
36
|
"attributes": [
|
|
37
37
|
{ "key": "deployment.environment.name", "value": { "stringValue": "production" } },
|
|
38
|
-
{ "key": "rum.schema.version", "value": { "stringValue": "3" } },
|
|
39
38
|
{ "key": "service.name", "value": { "stringValue": "order-center" } },
|
|
40
39
|
{ "key": "session.sample_rate", "value": { "intValue": 1 } },
|
|
41
40
|
{ "key": "telemetry.sdk.language", "value": { "stringValue": "webjs" } },
|
|
@@ -65,8 +64,6 @@ https://rum.example.com/collector/v1/rum
|
|
|
65
64
|
{ "key": "view.url", "value": { "stringValue": "https://app.example.com/orders/123" } },
|
|
66
65
|
{ "key": "view.url_path_group", "value": { "stringValue": "/orders/:id" } },
|
|
67
66
|
{ "key": "view.loading_type", "value": { "stringValue": "initial_load" } },
|
|
68
|
-
{ "key": "rum.page.host", "value": { "stringValue": "app.example.com" } },
|
|
69
|
-
{ "key": "rum.page.path", "value": { "stringValue": "/orders/123" } },
|
|
70
67
|
{ "key": "span_type", "value": { "stringValue": "resource" } },
|
|
71
68
|
{ "key": "outcome.type", "value": { "stringValue": "success" } },
|
|
72
69
|
{ "key": "resource.type", "value": { "stringValue": "fetch" } },
|