@blueking/open-telemetry 0.0.19 → 0.0.21

package/skills/bk-rum-otele/references/telemetry-reference.md

@@ -9,51 +9,54 @@
 ## 命名规则
 
 - **信号名**：`browser.*` 表示内置浏览器事件（如 `browser.web_vital`）；`action.<type>`、`custom.<name>` 是运行期动态拼接；`csp.violation`、`websocket.*` 使用领域前缀。
-- **属性 key**：沿用 OpenTelemetry 语义约定的字段用点号（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。字段常量集中定义在 `src/schema/attributes.ts`。
+- **属性 key**：标准字段与 RUM 领域字段均使用点号命名空间（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。公共与跨插件字段常量集中定义在 `src/schema/attributes.ts`，插件私有字段在对应插件内定义。
 
-## 公共上下文属性
+## 公共 Resource 与运行时上下文属性
 
-以下属性由运行时上下文自动挂到**几乎所有** span / log 上（metric 视插件而定），后续各清单不再重复列出：
+Resource 属性由三类信号共享；运行时上下文属性自动挂到**几乎所有** span / log 上（metric 视插件而定）。后续各清单不再重复列出：
 
-| key | 类型 | 说明 | 低基数 |
-| --- | --- | --- | --- |
-| `service.name` | string | 应用名（`application.name`） | 是 |
-| `service.version` | string | 应用版本（`application.version`，可选） | 是 |
-| `deployment.environment.name` | string | 环境（`application.environment`） | 是 |
-| `rum.provider` | string | 固定 `blueking` | 是 |
-| `telemetry.sdk.language` | string | 固定 `webjs` | 是 |
-| `user.id` | string | 接入方提供，原样透传 | 否 |
-| `session.id` | string | session 插件生成/轮换 | 否 |
-| `session.has_replay` | boolean | 当前固定 `false` | 是 |
-| `view.id` | string | View 管理器生成的实例 ID | 否 |
-| `view.name` | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
-| `view.url` | string | 当前 view URL（已脱敏） | 否 |
-| `view.url_path_group` | string | 低基数路由模板 | 是 |
-| `view.loading_type` | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
-| `device.type` | string | `mobile` / `desktop` | 是 |
-| `browser.name` / `browser.version` | string | 浏览器信息 | 是 |
-| `os.name` | string | 操作系统 | 是 |
-| `network.effective_type` | string | 网络质量（`4g` 等） | 是 |
+| key | 归属 | 类型 | 说明 | 低基数 |
+| --- | --- | --- | --- | --- |
+| `service.name` | Resource | string | 应用名（`application.name`） | 是 |
+| `service.version` | Resource | string | 应用版本（`application.version`，可选） | 是 |
+| `deployment.environment.name` | Resource | string | 环境（`application.environment`） | 是 |
+| `rum.schema.version` | Resource | string | 当前固定 `2` | 是 |
+| `telemetry.sdk.name` / `telemetry.sdk.language` / `telemetry.sdk.version` | Resource | string | SDK 名、语言和包版本 | 是 |
+| `device.type` | Resource | string | `mobile` / `desktop` | 是 |
+| `browser.name` / `browser.version` | Resource | string | 归一化浏览器信息 | 是 |
+| `os.name` | Resource | string | 操作系统 | 是 |
+| `device.memory_gib` | Resource | number | 浏览器暴露的近似设备内存（GiB） | 是 |
+| `device.logical_processor_count` | Resource | number | 浏览器暴露的逻辑处理器数量 | 是 |
+| `user.id` | Runtime | string | 接入方提供，原样透传 | 否 |
+| `session.id` | Runtime | string | session 插件生成/轮换 | 否 |
+| `session.has_replay` | Runtime | boolean | 当前固定 `false` | 是 |
+| `view.id` | Runtime | string | View 管理器生成的实例 ID | 否 |
+| `view.name` | Runtime | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
+| `view.url` | Runtime | string | 当前 view URL（已脱敏） | 否 |
+| `view.url_path_group` | Runtime | string | 低基数路由模板 | 是 |
+| `view.loading_type` | Runtime | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
+| `device.id` | Runtime | string | 当前实例或持久化匿名设备 ID | 否 |
+| `network.effective_type` | Runtime | string | 网络质量（`4g` 等） | 是 |
 
 > span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` 等归一字段（见下方[归一字段](#归一字段)）。接入方可通过 `context.attributes.page` 注入额外的页面属性。
 
 ## Span 清单
 
-| span 名 | span_type | 来源 | 关键属性 | 备注 |
-| --- | --- | --- | --- | --- |
-| `browser.view` | `document` / `route` | View 管理器 | `view.name`、`view.loading_time`、`view.loading_time.source`、`url.previous`、`event.source`、`view.end_reason` | 有持续时间，下一次 View 或 pagehide 时结束 |
-| `browser.resource` | `resource` | Fetch/XHR request 采集 | `resource.type=fetch\|xhr`、`url.full`、`http.request.method`、`http.response.status_code`、网络阶段属性 | span kind 为 CLIENT；Fetch/XHR 共用同一实现 |
-| `browser.resource` | `resource` | resource 插件 | `resource.type`、`url.full`、`resource.size`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
-| `browser.web_vital` | `vital` | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
-| `browser.blank_screen` | `error` | blankScreen 插件（二次确认白屏时） | `blank_screen.empty_ratio`、`blank_screen.reason`、`blank_screen.root_selector`、`blank_screen.root_found`、`blank_screen.*_sample_count`、`blank_screen.center_element` | 每个 View 最多一条 |
-| `browser.error` | `error` | error 插件（`window.error`） | `exception.fingerprint`、`exception.message_short`、`exception.stack_top_frame`、`error.source=window.error`、`error.window_occurrence_index`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | 完整异常写入标准 `exception` Span Event |
-| `browser.unhandledrejection` | `error` | error 插件（Promise 异常） | `exception.fingerprint`、`error.source=unhandledrejection` | 完整异常写入标准 `exception` Span Event |
-| `browser.resource_error` | `error` | error 插件（资源加载失败） | `exception.fingerprint`、`error.source=resource`、`url.full`、`html.tag` | 完整异常写入标准 `exception` Span Event |
-| `browser.long_task` | `longtask` | longTask 插件 | `long_task.id`、`long_task.entry_type`、`long_task.start_time`、`long_task.duration`、`long_task.blocking_duration`、`long_task.culprit`、`long_task.script.count` | LoAF 脚本详情写入 `long_task.script` Span Event |
-| `csp.violation` | `error` | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_occurrence_index`、`csp.original_policy`（窗口首条） | |
-| `websocket.connect` | `custom` | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`network.protocol.name=websocket` | 长连接生命周期不绑定 span |
-| `action.click` / `action.custom` | `action` | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
-| `custom.<name>` | `custom` | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时记录 exception、设置错误 Status/Result，`span_type` 仍为 `custom` |
+| span 名 | span_type | kind | 来源 | 关键属性 | 备注 |
+| --- | --- | --- | --- | --- | --- |
+| `browser.view` | `document` / `route` | INTERNAL | View 管理器 | `view.name`、`view.loading_time`、`view.loading_time.source`、`url.previous`、`event.source`、`view.end_reason` | 有持续时间，由下一次 View、pagehide、Session 过期或 SDK shutdown 结束 |
+| `browser.resource` | `resource` | CLIENT | Fetch/XHR request 采集 | `resource.type=fetch\|xhr`、`url.full`、`http.request.method`、`http.response.status_code`、网络阶段属性 | Fetch/XHR 共用同一实现 |
+| `browser.resource` | `resource` | CLIENT | resource 插件 | `resource.type`、`url.full`、`resource.size`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
+| `browser.web_vital` | `vital` | INTERNAL | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
+| `browser.blank_screen` | `error` | INTERNAL | blankScreen 插件（二次确认白屏时） | `blank_screen.empty_ratio`、`blank_screen.reason`、`blank_screen.root_selector`、`blank_screen.root_found`、`blank_screen.*_sample_count`、`blank_screen.center_element` | 每个 View 最多一条 |
+| `browser.error` | `error` | INTERNAL | error 插件（`window.error`） | `exception.fingerprint`、`exception.message_short`、`exception.stack_top_frame`、`error.source=window.error`、`error.window_occurrence_index`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | 完整异常写入标准 `exception` Span Event |
+| `browser.unhandledrejection` | `error` | INTERNAL | error 插件（Promise 异常） | `exception.fingerprint`、`error.source=unhandledrejection` | 完整异常写入标准 `exception` Span Event |
+| `browser.resource_error` | `error` | INTERNAL | error 插件（资源加载失败） | `exception.fingerprint`、`error.source=resource`、`url.full`、`html.tag` | 完整异常写入标准 `exception` Span Event |
+| `browser.long_task` | `longtask` | INTERNAL | longTask 插件 | `long_task.id`、`long_task.entry_type`、`long_task.start_time`、`long_task.duration`、`long_task.blocking_duration`、`long_task.culprit`、`long_task.script.count` | LoAF 脚本详情写入 `long_task.script` Span Event |
+| `csp.violation` | `error` | INTERNAL | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_occurrence_index`、`csp.original_policy`（窗口首条） | |
+| `websocket.connect` | `custom` | CLIENT | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`server.port`、`network.protocol.name=websocket` | 长连接生命周期不绑定 span |
+| `action.click` / `action.custom` | `action` | INTERNAL | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
+| `custom.<name>` | `custom` | INTERNAL | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时记录 exception、设置错误 Status/Result，`span_type` 仍为 `custom` |
 
 ## Metric 清单
 
@@ -68,16 +71,16 @@
 | `browser.long_task.count` | Counter | - | `view.url_path_group`、`long_task.entry_type` | longTask |
 | `browser.long_task.duration` | Histogram | `ms` | 同上 | longTask |
 | `browser.long_task.blocking_duration` | Histogram | `ms` | 同上 | longTask，仅 LoAF |
-| `browser.websocket.message.count` | Counter | - | `server.address`、`url.scheme`、`websocket.direction`（in/out） | websocket |
+| `browser.websocket.message.count` | Counter | - | `server.address`、`server.port`、`url.scheme`、`websocket.direction`（in/out） | websocket |
 | `browser.websocket.message.bytes` | Counter | `By` | 同上 | websocket |
-| `browser.websocket.error.count` | Counter | - | `server.address`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
-| `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`url.scheme` | websocket，仅成功建连 |
+| `browser.websocket.error.count` | Counter | - | `server.address`、`server.port`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
+| `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`server.port`、`url.scheme` | websocket，仅成功建连 |
 
 > 各 metric 只会合并 `context.attributes.metric` hook 返回的自定义低基数维度，不会合并 `context.attributes.page`，也不会携带 `session.id`、`view.id` 或 `action.id`。`view.url_path_group` 中明显的数字 ID、UUID、长十六进制段会归一为 `:id`。精确 View 关联请查询对应 span 或 View Snapshot Log。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
 
 ## Log 事件清单
 
-| body | severity | 来源 | 关键属性 |
+| eventName / body | severity | 来源 | 关键属性 |
 | --- | --- | --- | --- |
 | `session.start` | INFO | session 插件（首次新建） | `session.id`、`session.start_time`、`session.rotate.reason=init` |
 | `session.rotate` | INFO | session 插件（轮换） | + `session.previous_id`、`session.rotate.reason`（`inactivity` / `maxLifetime`） |
@@ -86,6 +89,8 @@
 | `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_occurrence_index` |
 | `websocket.close` | INFO | websocket 插件 | `websocket.close.code`、`websocket.close.reason`、`websocket.close.was_clean` |
 
+> 内置 Log 的 `eventName` 与 `body` 当前使用同一个事件名；查询与 `tracking.beforeSend` 应优先使用 `eventName`。
+
 > 错误主数据统一走 `error` span（见 Span 清单），SDK **不再**为同一个错误额外 emit error log，避免重复计数。
 
 ## 属性字典
@@ -101,6 +106,27 @@
 | `result` | string | `success`/`warning`/`error`/`timeout`/`abort` | 是 |
 | `error_type` | string | 错误细分，如 `http_5xx`/`network_timeout`/`slow`/`none` | 是 |
 
+### View / Navigation
+
+| key | 类型 | 出现位置 | 说明 |
+| --- | --- | --- | --- |
+| `view.id` / `view.name` / `view.url` / `view.url_path_group` | string | Span / Log | View 标识、名称、脱敏 URL 与低基数路由模板 |
+| `view.loading_type` | string | Span / Log / Metric | `initial_load` / `route_change` / `session_renewal` / `bf_cache` |
+| `view.loading_time` | number | Span / Log；同时作为 Metric 值 | View 从开始到页面活动稳定的耗时（ms） |
+| `view.loading_time.source` | string | Span / Log | `auto` / `manual` |
+| `view.first_byte` | number | 初始 View Span / Log | Navigation Timing 的 `responseStart`（相对 `performance.timeOrigin`，ms） |
+| `view.dom_interactive` / `view.dom_content_loaded` | number | 初始 View Span / Log | DOM interactive / DOMContentLoaded 时间（相对 `performance.timeOrigin`，ms） |
+| `view.dom_complete` / `view.load_event` | number | 初始 View Span / Log | DOM complete / load event 时间（相对 `performance.timeOrigin`，ms） |
+| `url.previous` | string | Span / Log | 前一个 View URL（已脱敏） |
+| `document.referrer` | string | 初始 View Span / Log | 页面 referrer（已脱敏） |
+| `event.source` | string | Span / Log | View 创建触发源，如 `load`、`pushState`、`popstate`、`manual`、`bfCache`、`sessionRenewal` |
+| `view.end_reason` | string | Span / final Log | 下一 View 的触发源，或 `pagehide` / `session_expired` / `shutdown` |
+| `event.type` | string | Log | 固定 `view` |
+| `view.snapshot.type` | string | Log | `create` / `update` / `final` |
+| `view.document_version` | number | Log | 当前 View Snapshot 的递增版本号 |
+| `view.duration` | number | Log | 从 View 开始到 Snapshot 的耗时（ms） |
+| `view.is_active` | boolean | Log | 非 final Snapshot 为 `true` |
+
 ### HTTP / Resource
 
 | key | 类型 | 说明 |
@@ -142,12 +168,11 @@
 
 ### 错误 / 异常
 
+以下字段位于 Error Span 顶层属性：
+
 | key | 类型 | 说明 |
 | --- | --- | --- |
-| `exception.type` | string | 异常类型/名称 |
-| `exception.message` | string | 异常消息 |
 | `exception.message_short` | string | 消息前 80 字符 |
-| `exception.stacktrace` | string | 堆栈 |
 | `exception.stack_top_frame` | string | 栈顶帧 |
 | `exception.fingerprint` | string | 节流分组指纹（djb2 hash） |
 | `error.source` | string | `window.error`/`unhandledrejection`/`resource`/`csp` |
@@ -157,18 +182,29 @@
 | `code.filepath` / `code.lineno` / `code.column` | string/number | JS 错误位置 |
 | `html.tag` | string | 资源错误的元素标签 |
 
+`error.subtype` 仅作为 `browser.error.count` Metric 维度，取值为 `js` / `promise` / `resource_load`，不写入 Error Span 顶层属性。
+
+完整异常由 `recordException()` 写入名为 `exception` 的标准 Span Event，不在 Span 顶层属性中：
+
+| Event 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `exception.type` | string | 异常类型/名称 |
+| `exception.message` | string | 异常消息 |
+| `exception.stacktrace` | string | 堆栈（存在时） |
+
 ### 设备 / 浏览器 / 网络
 
 | key | 类型 | 说明 |
 | --- | --- | --- |
 | `device.id` | string | 匿名设备标识；默认仅当前 SDK 实例稳定，`tracking.device.persistentId=true` 时持久化 |
-| `device.memory` / `device.cpu_cores` | number | 硬件能力 |
-| `device.platform` / `device.mobile` | string/bool | UA-CH 平台信息 |
+| `device.memory_gib` | number | Resource 中的近似设备内存（GiB） |
+| `device.logical_processor_count` | number | Resource 中的逻辑处理器数量 |
 | `browser.viewport.width` / `browser.viewport.height` | number | 视口尺寸 |
 | `browser.screen.width` / `browser.screen.height` | number | 屏幕尺寸 |
+| `network.effective_type` | string | 网络质量，如 `4g` |
 | `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data` | mixed | 网络信息 |
-| `browser.name` / `browser.version` / `os.name` | string | UA 解析结果 |
-| `device.type` | string | `mobile` / `desktop` |
+| `browser.name` / `browser.version` / `os.name` | string | Resource 中的 UA 解析结果 |
+| `device.type` | string | Resource 中的 `mobile` / `desktop` |
 
 ### 用户动作 / 会话
 
@@ -200,7 +236,9 @@
 | `long_task.is_frozen_frame` | boolean | 总耗时是否达到 700ms |
 | `long_task.culprit` | string | 最重脚本 URL、函数或 legacy attribution |
 | `long_task.script.count` | number | LoAF 脚本数 |
+| `long_task.first_ui_event_timestamp` | number | LoAF 首个 UI Event 时间戳 |
 | `long_task.render_start` / `long_task.style_and_layout_start` | number | LoAF 渲染与样式布局阶段起点 |
+| `long_task.culprit.*` | mixed | 最重脚本的耗时、强制布局耗时、函数名与 invoker 类型 |
 | `long_task.script.*` | mixed | `long_task.script` Span Event 上的脚本耗时、URL、函数、invoker 和强制布局归因 |
 
 ### CSP
@@ -221,7 +259,8 @@
 | key | 类型 | 说明 |
 | --- | --- | --- |
 | `url.scheme` | string | `ws` / `wss` |
-| `server.address` | string | 目标 host |
+| `server.address` | string | 目标 hostname，不包含端口 |
+| `server.port` | number | 目标显式端口（存在时） |
 | `network.protocol.name` | string | 固定 `websocket` |
 | `websocket.direction` | string | `in` / `out`（仅 metric） |
 | `websocket.error.phase` | string | `connect` / `runtime` |