@blueking/open-telemetry 0.0.24 → 0.0.25
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/dist/bk-rum.global.js +1 -1
- package/dist/bk-rum.global.js.map +1 -1
- package/dist/index.js +128 -133
- package/dist/index.js.map +1 -1
- package/dist/plugins/device.d.ts +4 -4
- package/dist/plugins/resource.d.ts +5 -3
- package/dist/schema/attributes.d.ts +4 -4
- package/dist/schema/span.d.ts +1 -2
- package/package.json +1 -1
- package/skills/bk-rum-otele/references/network.md +4 -1
- package/skills/bk-rum-otele/references/session-context.md +5 -8
- package/skills/bk-rum-otele/references/telemetry-reference.md +55 -57
package/dist/plugins/device.d.ts
CHANGED
|
@@ -11,15 +11,15 @@ export declare const getDeviceResourceAttributes: () => Attributes;
|
|
|
11
11
|
*
|
|
12
12
|
* 上报字段：
|
|
13
13
|
* - `device.id`：设备级永久标识，存于 localStorage（默认 key 复用旧 session 插件以保留现网用户）。
|
|
14
|
-
* - `device.memory_gib
|
|
14
|
+
* - `device.memory_gib`：硬件能力快照，写入 Resource。
|
|
15
|
+
* - `user_agent.name` / `user_agent.version` / `user_agent.os.name`：User Agent 信息，写入 Resource。
|
|
15
16
|
* - `browser.viewport.*` / `browser.screen.*`：视口与屏幕尺寸。
|
|
16
|
-
* - `network.
|
|
17
|
-
* 网络信息。
|
|
17
|
+
* - `network.status` / `network.effective_type` / `network.connection_type`：网络信息。
|
|
18
18
|
*
|
|
19
19
|
* 实时更新：
|
|
20
20
|
* - viewport 监听 `resize` / `orientationchange`，并经 250ms debounce 合并，避免拖窗口时高频触发；
|
|
21
21
|
* 静默期结束后用最终值刷新 runtimeAttributes。
|
|
22
|
-
* - network 监听 `connection.change`（本身低频，不需要 throttle）。
|
|
22
|
+
* - network 监听 `online` / `offline` / `connection.change`（本身低频，不需要 throttle）。
|
|
23
23
|
* - 二者只更新 in-memory 的 runtimeAttributes，不会主动产生新的 Span；
|
|
24
24
|
* 更新后续生成的 Span 会带最新值。
|
|
25
25
|
*
|
|
@@ -11,12 +11,14 @@ type ResourceTimingWithStatus = PerformanceResourceTiming & {
|
|
|
11
11
|
export declare const getResourceTimingAttributes: (entry: ResourceTimingWithStatus) => Record<string, number>;
|
|
12
12
|
export declare const getResourceDuration: (entry: ResourceTimingWithStatus) => number;
|
|
13
13
|
export declare const getResourcePerformanceAttributes: (entry: ResourceTimingWithStatus) => {
|
|
14
|
-
'resource.
|
|
15
|
-
'resource.
|
|
14
|
+
'resource.size'?: number | undefined;
|
|
15
|
+
'resource.encoded_body_size'?: number | undefined;
|
|
16
|
+
'resource.decoded_body_size'?: number | undefined;
|
|
17
|
+
'resource.transfer_size'?: number | undefined;
|
|
16
18
|
'resource.render_blocking_status'?: string | undefined;
|
|
17
19
|
'resource.delivery_type'?: string | undefined;
|
|
20
|
+
"resource.protocol"?: string | undefined;
|
|
18
21
|
"resource.cache.hit": boolean | undefined;
|
|
19
|
-
"resource.protocol": string;
|
|
20
22
|
};
|
|
21
23
|
export declare const createResourcePlugin: (emitResourceSpans?: boolean) => BkOTPlugin;
|
|
22
24
|
export {};
|
|
@@ -12,10 +12,7 @@ export declare const RUM_ATTRIBUTES: {
|
|
|
12
12
|
readonly actionTargetTag: "action.target.tag";
|
|
13
13
|
readonly actionType: "action.type";
|
|
14
14
|
readonly deploymentEnvironmentName: "deployment.environment.name";
|
|
15
|
-
readonly browserName: "browser.name";
|
|
16
|
-
readonly browserVersion: "browser.version";
|
|
17
15
|
readonly cacheHit: "resource.cache.hit";
|
|
18
|
-
readonly deviceLogicalProcessorCount: "device.logical_processor_count";
|
|
19
16
|
readonly deviceMemoryGib: "device.memory_gib";
|
|
20
17
|
readonly deviceType: "device.type";
|
|
21
18
|
readonly longTaskBlockingDuration: "long_task.blocking_duration";
|
|
@@ -24,12 +21,12 @@ export declare const RUM_ATTRIBUTES: {
|
|
|
24
21
|
readonly longTaskId: "long_task.id";
|
|
25
22
|
readonly longTaskStartTime: "long_task.start_time";
|
|
26
23
|
readonly networkEffectiveType: "network.effective_type";
|
|
24
|
+
readonly networkStatus: "network.status";
|
|
27
25
|
readonly nextHopProtocol: "resource.protocol";
|
|
28
26
|
readonly outcomeReason: "outcome.reason";
|
|
29
27
|
readonly outcomeType: "outcome.type";
|
|
30
28
|
readonly serviceName: "service.name";
|
|
31
29
|
readonly serviceVersion: "service.version";
|
|
32
|
-
readonly osName: "os.name";
|
|
33
30
|
readonly sessionHasReplay: "session.has_replay";
|
|
34
31
|
readonly sessionId: "session.id";
|
|
35
32
|
readonly sessionSampleRate: "session.sample_rate";
|
|
@@ -38,6 +35,9 @@ export declare const RUM_ATTRIBUTES: {
|
|
|
38
35
|
readonly sessionType: "session.type";
|
|
39
36
|
readonly spanType: "span_type";
|
|
40
37
|
readonly userId: "user.id";
|
|
38
|
+
readonly userAgentName: "user_agent.name";
|
|
39
|
+
readonly userAgentOsName: "user_agent.os.name";
|
|
40
|
+
readonly userAgentVersion: "user_agent.version";
|
|
41
41
|
readonly vitalMetric: "vital.metric";
|
|
42
42
|
readonly vitalRating: "vital.rating";
|
|
43
43
|
readonly vitalValue: "vital.value";
|
package/dist/schema/span.d.ts
CHANGED
|
@@ -33,7 +33,6 @@ export interface RumResourceSpanInput {
|
|
|
33
33
|
initiatorType?: string;
|
|
34
34
|
method?: string;
|
|
35
35
|
outcome?: RumRequestOutcome;
|
|
36
|
-
transferSize?: number;
|
|
37
36
|
url: string;
|
|
38
37
|
}
|
|
39
38
|
export interface RumSpanClassification {
|
|
@@ -52,4 +51,4 @@ export declare const getHttpOutcomeReason: (statusCode: number | undefined) => "
|
|
|
52
51
|
export declare const getVitalOutcome: (rating: string | undefined) => RumSpanOutcome;
|
|
53
52
|
export declare const getUrlTarget: (url: string | undefined) => RumUrlTarget;
|
|
54
53
|
export declare const buildRumSpanAttributes: ({ outcome, outcomeReason, spanType, }: RumSpanClassification) => Attributes;
|
|
55
|
-
export declare const buildRumResourceSpanAttributes: ({ initiatorType, method, outcome,
|
|
54
|
+
export declare const buildRumResourceSpanAttributes: ({ initiatorType, method, outcome, url, }: RumResourceSpanInput) => Attributes;
|
package/package.json
CHANGED
|
@@ -179,14 +179,17 @@ Fetch resolve/reject 和 XHR 终止事件往往早于 Resource Timing Observer
|
|
|
179
179
|
| 字段 | 说明 |
|
|
180
180
|
| --------------------------------- | ---------------------------------------------------------- |
|
|
181
181
|
| `resource.type` | initiator type |
|
|
182
|
-
| `resource.size` | `
|
|
182
|
+
| `resource.size` | `decodedBodySize`（解压后 Body Size） |
|
|
183
183
|
| `resource.encoded_body_size` | 编码后 Body Size |
|
|
184
184
|
| `resource.decoded_body_size` | 解码后 Body Size |
|
|
185
|
+
| `resource.transfer_size` | `transferSize`（网络传输字节数，缓存命中可能为 `0`） |
|
|
185
186
|
| `resource.protocol` | `nextHopProtocol`，例如 `h2` |
|
|
186
187
|
| `resource.cache.hit` | deliveryType=cache，或 transferSize=0 且 decodedBodySize>0 |
|
|
187
188
|
| `resource.delivery_type` | 浏览器提供的 delivery type |
|
|
188
189
|
| `resource.render_blocking_status` | blocking / non-blocking，浏览器支持时 |
|
|
189
190
|
|
|
191
|
+
当三个 Size 均为 `0`，同时 `requestStart`、`responseStart` 和 `nextHopProtocol` 也缺失时，SDK 将其视为浏览器未暴露 Resource Timing 详情，不上报 Size 和协议字段，避免把“未知”误报为真实的 `0`。
|
|
192
|
+
|
|
190
193
|
## 网络阶段字段
|
|
191
194
|
|
|
192
195
|
每个阶段同时写相对资源开始的 `start` 和阶段 `duration`，单位 ms：
|
|
@@ -118,12 +118,11 @@ SDK 只维护 `user.id`，并原样透传：不 hash、不截断、不验证、
|
|
|
118
118
|
|
|
119
119
|
| 字段 | 来源 | 可能缺失 |
|
|
120
120
|
| --- | --- | --- |
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `os.name` | UA / UA-CH platform | 否，无法识别为 `Other` |
|
|
121
|
+
| `user_agent.name` | UA 简单识别：Edge/Chrome/Firefox/Safari/Other | 否 |
|
|
122
|
+
| `user_agent.version` | UA 主版本 | 未识别版本时 |
|
|
123
|
+
| `user_agent.os.name` | UA / UA-CH platform | 否，无法识别为 `Other` |
|
|
124
124
|
| `device.type` | UA-CH mobile 或移动 UA | 否 |
|
|
125
125
|
| `device.memory_gib` | `navigator.deviceMemory` | 浏览器未实现时 |
|
|
126
|
-
| `device.logical_processor_count` | `navigator.hardwareConcurrency` | 浏览器未实现时 |
|
|
127
126
|
|
|
128
127
|
关闭 `tracking.device` 时，这些 Device Resource 字段不写入。
|
|
129
128
|
|
|
@@ -136,13 +135,11 @@ Device 插件还维护：
|
|
|
136
135
|
| `device.id` | 插件启动时 |
|
|
137
136
|
| `browser.viewport.width/height` | 启动、resize、orientationchange |
|
|
138
137
|
| `browser.screen.width/height` | 启动、resize、orientationchange |
|
|
138
|
+
| `network.status` | 启动、online、offline、connection change |
|
|
139
139
|
| `network.effective_type` | 启动和 connection change |
|
|
140
140
|
| `network.connection_type` | 同上 |
|
|
141
|
-
| `network.downlink` | 同上 |
|
|
142
|
-
| `network.rtt` | 同上 |
|
|
143
|
-
| `network.save_data` | 同上 |
|
|
144
141
|
|
|
145
|
-
视口变化使用 250ms trailing debounce
|
|
142
|
+
视口变化使用 250ms trailing debounce。`network.status` 在浏览器环境中始终存在，其他网络字段只有浏览器实现 Network Information API 时才存在。这些变化不主动生成 Span，只影响后续 Span 的上下文。
|
|
146
143
|
|
|
147
144
|
## Device ID 持久化
|
|
148
145
|
|
|
@@ -8,13 +8,13 @@
|
|
|
8
8
|
|
|
9
9
|
一条 RUM Span 的信息按以下层级组合。建模时应保持层级分工，不要把所有字段压成一套无差别标签：
|
|
10
10
|
|
|
11
|
-
| 层级
|
|
12
|
-
|
|
|
13
|
-
| SDK 与应用 Resource
|
|
14
|
-
| RUM 运行时上下文
|
|
15
|
-
| 公共分类
|
|
16
|
-
| 领域属性
|
|
17
|
-
| OTLP Envelope 与 Event | `traceId`、`spanId`、时间戳、`status`、`events`
|
|
11
|
+
| 层级 | 主要字段 | 适合回答的问题 |
|
|
12
|
+
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
|
|
13
|
+
| SDK 与应用 Resource | `service.*`、`deployment.environment.name`、`telemetry.sdk.*` | 哪个应用、环境、版本和 SDK 产生了数据？ |
|
|
14
|
+
| RUM 运行时上下文 | `session.id`、`view.id`、`action.id`、`user.id`、设备和网络字段 | 事件属于哪个 Session、View、Action 和用户上下文？ |
|
|
15
|
+
| 公共分类 | `span_type`、`outcome.type`、`outcome.reason` | 这是什么信号，结果是否正常，失败属于哪类原因？ |
|
|
16
|
+
| 领域属性 | `resource.*`、`error.*`、`vital.*`、`long_task.*` 等 | 具体发生了什么，耗时、来源和诊断细节是什么？ |
|
|
17
|
+
| OTLP Envelope 与 Event | `traceId`、`spanId`、时间戳、`status`、`events` | 如何定位单条记录、关联调用链和读取异常/脚本归因？ |
|
|
18
18
|
|
|
19
19
|
推荐先用 Resource 字段限定应用和环境，再以 `span_type` 选择信号类型，最后使用领域字段细分。Session/View 聚合优先使用 `session.id`、`view.id`；路由聚合优先使用低基数的 `view.url_path_group`，不要直接按完整 URL 或原始 path 建立高基数索引。
|
|
20
20
|
|
|
@@ -74,12 +74,11 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
|
|
|
74
74
|
| `telemetry.sdk.name` | string | 必有 | 固定为 `@blueking/open-telemetry`，用于识别数据生产 SDK。 |
|
|
75
75
|
| `telemetry.sdk.language` | string | 必有 | 固定为 `webjs`，表示浏览器 JavaScript SDK。 |
|
|
76
76
|
| `telemetry.sdk.version` | string | 必有 | 当前 npm 包版本，用于排查字段能力或采集行为是否受 SDK 版本影响。 |
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `os.name`
|
|
80
|
-
| `device.type` | string | `tracking.device !== false` 且有浏览器环境
|
|
81
|
-
| `device.memory_gib` | number | 浏览器支持 `navigator.deviceMemory` 时
|
|
82
|
-
| `device.logical_processor_count` | number | 浏览器支持 `navigator.hardwareConcurrency` 时 | 浏览器暴露的逻辑处理器数量，可辅助分析低端设备性能；可能因浏览器隐私策略而低于真实数量。 |
|
|
77
|
+
| `user_agent.name` | string | `tracking.device !== false` 且有浏览器环境 | 从 User-Agent 识别，取值 `Edge`、`Chrome`、`Firefox`、`Safari` 或 `Other`。识别不到时为 `Other`。 |
|
|
78
|
+
| `user_agent.version` | string | 能识别浏览器版本时 | 从 User-Agent 提取的浏览器主版本号，不包含次版本和补丁版本；识别不到时缺失。 |
|
|
79
|
+
| `user_agent.os.name` | string | `tracking.device !== false` 且有浏览器环境 | 从 User-Agent / User-Agent Client Hints 推断，取值 `iOS`、`Android`、`macOS`、`Windows`、`Linux` 或 `Other`。 |
|
|
80
|
+
| `device.type` | string | `tracking.device !== false` 且有浏览器环境 | `mobile` 或 `desktop`。根据 `userAgentData.mobile` 或移动端 User-Agent 特征推断，不代表具体硬件型号。 |
|
|
81
|
+
| `device.memory_gib` | number | 浏览器支持 `navigator.deviceMemory` 时 | 浏览器提供的近似设备内存容量，单位 GiB。该值通常已分档并可能受隐私策略限制，不应当作精确物理内存。 |
|
|
83
82
|
|
|
84
83
|
`tracking.device=false` 时 SDK 构造的 Resource 不写入设备 Resource 字段。Resource 在 SDK 初始化时经过一次 `redactAttributes`，运行期间不会随窗口或网络状态变化。
|
|
85
84
|
|
|
@@ -105,11 +104,9 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
|
|
|
105
104
|
| `browser.viewport.height` | number | 浏览器环境 | 当前 CSS viewport 高度，单位 CSS px，来源 `window.innerHeight`。 |
|
|
106
105
|
| `browser.screen.width` | number | 浏览器提供 `window.screen` 时 | 当前屏幕宽度，单位 CSS px；不是物理像素，不能直接推导设备分辨率。 |
|
|
107
106
|
| `browser.screen.height` | number | 浏览器提供 `window.screen` 时 | 当前屏幕高度，单位 CSS px；不是当前网页可用区域高度。 |
|
|
107
|
+
| `network.status` | string | 浏览器环境 | 根据 `navigator.onLine` 取 `connected` 或 `not_connected`；表示浏览器判断的联网状态，不保证目标服务实际可达。 |
|
|
108
108
|
| `network.effective_type` | string | Network Information API 支持 | 浏览器估算的有效网络类型，常见为 `slow-2g`、`2g`、`3g`、`4g`。它反映体验模型，不等同于真实无线制式。 |
|
|
109
109
|
| `network.connection_type` | string | 浏览器提供 `connection.type` 时 | 浏览器返回的原始连接类型，例如 `wifi`、`cellular`、`ethernet`；多数 Safari/Firefox 环境可能缺失。 |
|
|
110
|
-
| `network.downlink` | number | Network Information API 支持 | 浏览器估算的下行带宽，单位 Mbps，通常经过舍入；网络变化后更新到后续 Span。 |
|
|
111
|
-
| `network.rtt` | number | Network Information API 支持 | 浏览器估算的往返时延，单位 ms，通常经过舍入；不是当前某个 Resource 请求的实测 RTT。 |
|
|
112
|
-
| `network.save_data` | boolean | Network Information API 支持 | 用户是否开启节省流量偏好；`true` 可用于解释图片降质或资源加载策略差异。 |
|
|
113
110
|
|
|
114
111
|
默认 `context.attributes.page()` 返回空对象，不附加独立页面属性。页面地址使用 View 创建时冻结并经过 `redactUrl` 的 `view.url`，低基数路由聚合使用 `view.url_path_group`；业务需要额外页面维度时可自定义该 Hook。
|
|
115
112
|
|
|
@@ -125,22 +122,22 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
|
|
|
125
122
|
|
|
126
123
|
## Span 清单
|
|
127
124
|
|
|
128
|
-
| Span 名 | Kind | `span_type` | 领域分类字段 | 默认状态/入口
|
|
129
|
-
| ---------------------------- | -------- | ----------- | --------------------------------- |
|
|
130
|
-
| `browser.session` | INTERNAL | `session` | `session.phase` | 始终随 SDK 启动
|
|
131
|
-
| `browser.view` | INTERNAL | `view` | `view.phase`、`view.source` | 自动；可切为手动 View
|
|
132
|
-
| `browser.resource` | CLIENT | `resource` | `resource.type` | 请求、静态资源默认开启
|
|
133
|
-
| `browser.error` | INTERNAL | `error` | `error.source=window.error` | 错误采集默认开启
|
|
134
|
-
| `browser.unhandledrejection` | INTERNAL | `error` | `error.source=unhandledrejection` | 错误采集默认开启
|
|
135
|
-
| `browser.resource_error` | INTERNAL | `error` | `error.source=resource` | 错误采集默认开启
|
|
136
|
-
| `browser.web_vital` | INTERNAL | `vital` | `vital.metric` | 默认开启
|
|
137
|
-
| `action.click` | INTERNAL | `action` | `action.type=click` | 自动 Action 默认开启
|
|
138
|
-
| `action.custom` | INTERNAL | `action` | `action.type=custom` | `reportAction`
|
|
139
|
-
| `browser.blank_screen` | INTERNAL | `error` | `blank_screen.reason` | 默认开启
|
|
140
|
-
| `browser.long_task` | INTERNAL | `long_task` | `long_task.entry_type` | `tracking.longTask`，默认关闭
|
|
141
|
-
| `csp.violation` | INTERNAL | `error` | `error.source=csp` | `tracking.cspViolation`，默认关闭 | 浏览器 `securitypolicyviolation` 事件。
|
|
142
|
-
| `browser.websocket` | CLIENT | `websocket` | `websocket.phase` | `tracking.websocket`，默认关闭
|
|
143
|
-
| `custom.<name>` | INTERNAL | `custom` | Span 名 | `reportCustomEvent`
|
|
125
|
+
| Span 名 | Kind | `span_type` | 领域分类字段 | 默认状态/入口 | 表达的事件 |
|
|
126
|
+
| ---------------------------- | -------- | ----------- | --------------------------------- | --------------------------------- | -------------------------------------------------- |
|
|
127
|
+
| `browser.session` | INTERNAL | `session` | `session.phase` | 始终随 SDK 启动 | Session 创建、轮换和结束生命周期。 |
|
|
128
|
+
| `browser.view` | INTERNAL | `view` | `view.phase`、`view.source` | 自动；可切为手动 View | 初始页面或 SPA View 的 start/update/end 快照。 |
|
|
129
|
+
| `browser.resource` | CLIENT | `resource` | `resource.type` | 请求、静态资源默认开启 | Fetch、XHR 或静态资源加载。 |
|
|
130
|
+
| `browser.error` | INTERNAL | `error` | `error.source=window.error` | 错误采集默认开启 | `window.error` 捕获的 JavaScript 运行时错误。 |
|
|
131
|
+
| `browser.unhandledrejection` | INTERNAL | `error` | `error.source=unhandledrejection` | 错误采集默认开启 | 未处理的 Promise rejection。 |
|
|
132
|
+
| `browser.resource_error` | INTERNAL | `error` | `error.source=resource` | 错误采集默认开启 | script、img、link、media 等元素资源加载失败。 |
|
|
133
|
+
| `browser.web_vital` | INTERNAL | `vital` | `vital.metric` | 默认开启 | 单项用户体验指标及归因。 |
|
|
134
|
+
| `action.click` | INTERNAL | `action` | `action.type=click` | 自动 Action 默认开启 | 自动点击 Action 及其页面活动、错误和挫败归因。 |
|
|
135
|
+
| `action.custom` | INTERNAL | `action` | `action.type=custom` | `reportAction` | 主动上报的业务 Action。 |
|
|
136
|
+
| `browser.blank_screen` | INTERNAL | `error` | `blank_screen.reason` | 默认开启 | 视口九宫格连续检测确认的白屏。 |
|
|
137
|
+
| `browser.long_task` | INTERNAL | `long_task` | `long_task.entry_type` | `tracking.longTask`，默认关闭 | Long Animation Frame，或不支持时回退的 Long Task。 |
|
|
138
|
+
| `csp.violation` | INTERNAL | `error` | `error.source=csp` | `tracking.cspViolation`，默认关闭 | 浏览器 `securitypolicyviolation` 事件。 |
|
|
139
|
+
| `browser.websocket` | CLIENT | `websocket` | `websocket.phase` | `tracking.websocket`，默认关闭 | 同一 WebSocket 连接的四类生命周期事件。 |
|
|
140
|
+
| `custom.<name>` | INTERNAL | `custom` | Span 名 | `reportCustomEvent` | 主动上报的业务事件。 |
|
|
144
141
|
|
|
145
142
|
## Session 字段
|
|
146
143
|
|
|
@@ -190,21 +187,22 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
|
|
|
190
187
|
|
|
191
188
|
适用于 `browser.resource`。Fetch/XHR 由请求插件建 Span，再合并匹配的 Resource Timing；静态资源由 Resource Observer 直接建 Span。
|
|
192
189
|
|
|
193
|
-
| 字段 | 类型 | 条件/单位
|
|
194
|
-
| --------------------------------- | ------- |
|
|
195
|
-
| `url.full` | string | 有有效请求/资源 URL
|
|
196
|
-
| `server.address` | string | URL 可解析
|
|
197
|
-
| `server.port` | number | URL 显式包含端口
|
|
198
|
-
| `resource.type` | string | 必有
|
|
199
|
-
| `http.request.method` | string | Fetch/XHR
|
|
200
|
-
| `http.response.status_code` | number | 获得真实 HTTP Response
|
|
201
|
-
| `resource.size` | number |
|
|
202
|
-
| `resource.protocol` | string | 浏览器提供 `nextHopProtocol`
|
|
203
|
-
| `resource.cache.hit` | boolean | SDK 能推断命中缓存时
|
|
204
|
-
| `resource.delivery_type` | string | 浏览器支持 `deliveryType`
|
|
205
|
-
| `resource.render_blocking_status` | string | 浏览器支持 `renderBlockingStatus`
|
|
206
|
-
| `resource.encoded_body_size` | number | 有 Resource Timing
|
|
207
|
-
| `resource.decoded_body_size` | number | 有 Resource Timing
|
|
190
|
+
| 字段 | 类型 | 条件/单位 | 来源与详细说明 |
|
|
191
|
+
| --------------------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
192
|
+
| `url.full` | string | 有有效请求/资源 URL | 绝对 URL，经 `redactUrl` 脱敏。用于定位请求目标；不要假设 query 中仍保留原始参数。 |
|
|
193
|
+
| `server.address` | string | URL 可解析 | URL 的 `hostname`，不含端口。相对 URL 会基于当前页面地址解析。 |
|
|
194
|
+
| `server.port` | number | URL 显式包含端口 | URL 的显式端口号。使用协议默认端口且 URL 未写端口时缺失。 |
|
|
195
|
+
| `resource.type` | string | 必有 | Fetch/XHR 为 `fetch`/`xhr`；静态资源使用 `PerformanceResourceTiming.initiatorType`，为空时为 `other`，常见还有 `script`、`link`、`img`、`css`。 |
|
|
196
|
+
| `http.request.method` | string | Fetch/XHR | 归一为大写的 HTTP 方法，例如 `GET`、`POST`。静态资源通常没有可用的请求方法，因此缺失。 |
|
|
197
|
+
| `http.response.status_code` | number | 获得真实 HTTP Response | HTTP 响应状态，只写大于 `0` 的有效状态码。abort、timeout、网络失败和 opaque Response 没有可用状态码时缺失，不使用 `0` 代替。 |
|
|
198
|
+
| `resource.size` | number | 有 Resource Timing 详情 | `decodedBodySize`，解压后响应体大小，单位 bytes，不含响应头；缓存命中也能反映真实体积。Fetch/XHR 合并 Resource Timing 后同样会带上。 |
|
|
199
|
+
| `resource.protocol` | string | 浏览器提供 `nextHopProtocol` | 实际传输协议，例如 `h2`、`h3`、`http/1.1`；浏览器无法判断时可能返回空字符串。 |
|
|
200
|
+
| `resource.cache.hit` | boolean | SDK 能推断命中缓存时 | 只在 `deliveryType=cache`，或 `transferSize=0` 且 `decodedBodySize>0` 时写 `true`。没有该字段表示“无法确认命中”，不是明确的 `false`。 |
|
|
201
|
+
| `resource.delivery_type` | string | 浏览器支持 `deliveryType` | 浏览器报告的资源交付方式；原值为空时归一为 `other`。具体枚举随浏览器 Resource Timing 实现演进。 |
|
|
202
|
+
| `resource.render_blocking_status` | string | 浏览器支持 `renderBlockingStatus` | 资源是否阻塞渲染，常见为 `blocking` 或 `non-blocking`，适合定位影响首屏的 CSS/脚本。 |
|
|
203
|
+
| `resource.encoded_body_size` | number | 有 Resource Timing | 编码/压缩后的响应体大小，单位 bytes，不包含响应头。跨域且没有 Timing-Allow-Origin 时可能为 `0`。 |
|
|
204
|
+
| `resource.decoded_body_size` | number | 有 Resource Timing | 解码/解压后的响应体大小，单位 bytes，可与 encoded size 对比压缩收益。 |
|
|
205
|
+
| `resource.transfer_size` | number | 有 Resource Timing | `transferSize`，本次网络实际传输字节数（含响应头）；受缓存和 Timing-Allow-Origin 影响可能为 `0`，可与 body size 对比判断是否命中缓存。 |
|
|
208
206
|
|
|
209
207
|
网络阶段字段均为 number、单位 ms。每个 `*.start` 相对该 Resource Entry 的 `startTime`，每个 `*.duration` 为对应阶段结束值减开始值：
|
|
210
208
|
|
|
@@ -263,12 +261,12 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
|
|
|
263
261
|
|
|
264
262
|
`browser.web_vital` 上报 CLS、FCP、INP、LCP 和 TTFB。FCP/LCP/TTFB 由 `web-vitals/attribution` 采集导航级指标；CLS/INP 按 SDK View 边界汇总，View 结束时上报。
|
|
265
263
|
|
|
266
|
-
| 字段
|
|
267
|
-
|
|
|
268
|
-
| `vital.metric`
|
|
269
|
-
| `vital.value`
|
|
270
|
-
| `vital.rating`
|
|
271
|
-
| `vital.id`
|
|
264
|
+
| 字段 | 类型 | 条件/单位 | 来源与详细说明 |
|
|
265
|
+
| -------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
266
|
+
| `vital.metric` | string | 必有 | 指标名的小写值：`cls`、`fcp`、`inp`、`lcp`、`ttfb`。用于同一 Span 名下区分指标。 |
|
|
267
|
+
| `vital.value` | number | 必有 | 指标值。CLS 是无量纲分数；FCP、INP、LCP、TTFB 单位均为 ms。非有限值不会上报。 |
|
|
268
|
+
| `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`。 |
|
|
269
|
+
| `vital.id` | string | 必有 | 单条 Vital 的唯一 ID。FCP/LCP/TTFB 沿用 `web-vitals` ID；按 View 汇总的 CLS/INP 由 SDK 生成。 |
|
|
272
270
|
|
|
273
271
|
`vital.rating=good` 映射为 `outcome.type=success`；其他评级映射为 `outcome.type=warning`。具体体验评级由 `vital.rating` 表达，不重复写入 `outcome.reason`。
|
|
274
272
|
|
|
@@ -446,10 +444,10 @@ Legacy Long Task 的每个 attribution 条目生成一个 Event，Event 时间
|
|
|
446
444
|
|
|
447
445
|
`reportCustomEvent({ name, attributes, error })` 创建 `custom.<name>`：
|
|
448
446
|
|
|
449
|
-
| 字段
|
|
450
|
-
|
|
|
451
|
-
| `span_type`
|
|
452
|
-
| `outcome.type`
|
|
447
|
+
| 字段 | 类型 | 条件 | 来源与详细说明 |
|
|
448
|
+
| -------------- | ------ | ------------------- | ------------------------------------------------------ |
|
|
449
|
+
| `span_type` | string | 必有，固定 `custom` | 将主动业务事件归入 Custom 类别。 |
|
|
450
|
+
| `outcome.type` | string | 必有 | 没有 `error` 时为 `success`；传入 Error 时为 `error`。 |
|
|
453
451
|
|
|
454
452
|
调用方传入的 `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.*` 等保留字段。
|
|
455
453
|
|