@blueking/open-telemetry 0.0.31 → 0.0.33

package/skills/bk-rum-otele/references/network.md

@@ -21,7 +21,7 @@ SDK 不采集任何请求 Body、响应 Body、WebSocket 消息内容、消息
 1. 把 URL 转成绝对 URL。
 2. 排除 SDK 自身上报和 `excludedUrls`。
 3. 按白名单探测既有 Trace Header，规划本次请求的 trace context。
-4. 创建 `browser.resource` CLIENT Span，并把关联后端 Trace 的 Span Link 一并写入。
+4. 创建 `span_type=resource` 的 CLIENT Span，并把关联后端 Trace 的 Span Link 一并写入。
 5. 需要时注入 `traceparent`。
 6. 把请求开始/结束通知给 View/Action 页面活动。
 7. 根据 Response 或终止原因生成结构化 outcome，并补充结果、异常和 Resource Timing。
@@ -32,7 +32,7 @@ Patch 在插件 shutdown 时仅在全局方法仍是 SDK 安装版本的情况
 
 ## 请求 Span
 
-Fetch 和 XHR 都生成 `browser.resource`：
+Fetch 和 XHR 都生成名称为 `<http.request.method> <url.template>` 的 Resource Span：
 
 | 字段                        | Fetch                                          | XHR                         |
 | --------------------------- | ---------------------------------------------- | --------------------------- |
@@ -53,18 +53,17 @@ Span 开始时间使用请求开始时间，结束时间优先使用匹配到的
 
 ## Outcome 与 Status
 
-| 条件                               | `outcome.type` | `outcome.reason`  | OTel Status                 |
-| ---------------------------------- | -------------- | ----------------- | --------------------------- |
-| `408` / `504`                      | `timeout`      | `network_timeout` | ERROR                       |
-| 其他 `4xx`                         | `error`        | `http_4xx`        | ERROR                       |
-| `5xx`                              | `error`        | `http_5xx`        | ERROR                       |
-| Fetch AbortError / XHR `abort`     | `abort`        | 不写              | UNSET，不记录 exception     |
-| Fetch TimeoutError / XHR `timeout` | `timeout`      | `network_timeout` | ERROR，Fetch 记录 exception |
-| Fetch 其他 reject / XHR `error`    | `error`        | `network`         | ERROR，Fetch 记录 exception |
-| XHR `load` 但无法取得有效状态      | `error`        | `network`         | ERROR                       |
-| 其余                               | `success`      | 不写              | UNSET                       |
+| 条件                               | `outcome.type` | OTel Status                 |
+| ---------------------------------- | -------------- | --------------------------- |
+| `408` / `504`                      | `timeout`      | ERROR                       |
+| 其他 `4xx` / `5xx`                 | `error`        | ERROR                       |
+| Fetch AbortError / XHR `abort`     | `abort`        | UNSET，不记录 exception     |
+| Fetch TimeoutError / XHR `timeout` | `timeout`      | ERROR，Fetch 记录 exception |
+| Fetch 其他 reject / XHR `error`    | `error`        | ERROR，Fetch 记录 exception |
+| XHR `load` 但无法取得有效状态      | `error`        | ERROR                       |
+| 其余                               | `success`      | UNSET                       |
 
-SDK 不根据业务响应 JSON 中的 code 判断成功或失败；需要业务口径时使用 `request.beforeSend` 增加属性，或上报自定义事件。
+当前 SDK **不写** `outcome.reason`。HTTP 失败请用 `http.response.status_code` 细分。SDK 不根据业务响应 JSON 中的 code 判断成功或失败；需要业务口径时使用 `request.beforeSend` 增加属性，或上报自定义事件。
 
 ## URL 排除
 
@@ -114,7 +113,7 @@ traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
              └ version=00                       parent-id：16 位 ─────┘  sampled=01
 ```
 
-这样后端按 trace-id 检索时，一条 Trace 只对应一个 API 请求，也不会把前端的 `browser.resource` Span 混进后端链路。前后端的关联改由 **Span Link** 承担，后端可按 `link.trace_id` 反查对应的 RUM Span。
+这样后端按 trace-id 检索时，一条 Trace 只对应一个 API 请求，也不会把前端 Resource Span 混进后端链路。前后端的关联由 **Span Link** 承担，后端可按 `link.trace_id` 反查对应的 RUM Span。
 
 每个命中白名单的请求恒定产出**一条** Link，结构固定为 trace context 加上记录来源的 `attributes`：
 
@@ -222,7 +221,7 @@ Fetch resolve/reject 和 XHR 终止事件往往早于 Resource Timing Observer
 
 ## 静态资源
 
-`tracking.resource=true` 时，Resource PerformanceObserver 为非 Fetch/XHR Entry 创建独立 `browser.resource` CLIENT Span。Fetch 和 `xmlhttprequest` Entry 只回填已有请求 Span，不重复上报。
+`tracking.resource=true` 时，Resource PerformanceObserver 为非 Fetch/XHR Entry 创建独立 Resource CLIENT Span。Span 名使用 `GET <url.template>`。Fetch 和 `xmlhttprequest` Entry 只回填已有请求 Span，不重复上报。
 
 常见资源类型来自 `initiatorType`，例如 `script`、`link`、`img`、`css`、`beacon`、`other`。
 
@@ -275,14 +274,14 @@ Timing-Allow-Origin: https://your-web.example.com
 
 `tracking.websocket=true` 时，SDK 使用 Proxy 包装全局 `WebSocket` 构造器，并保持静态常量、`instanceof` 和子类构造行为。每条连接生成 `websocket.connection.id`，随后发送四类瞬时 CLIENT Span：
 
-| phase     | 时机                  | 额外字段                       |
-| --------- | --------------------- | ------------------------------ | -------- |
-| `connect` | 构造 WebSocket 后立即 | 基础目标字段                   |
-| `open`    | `open` Event          | 无                             |
-| `error`   | `error` Event         | `websocket.error.phase=connect | runtime` |
-| `close`   | `close` Event         | code、reason、was_clean        |
+| phase     | 时机                  | 额外字段                                      |
+| --------- | --------------------- | --------------------------------------------- |
+| `connect` | 构造 WebSocket 后立即 | 基础目标字段                                  |
+| `open`    | `open` Event          | 无                                            |
+| `error`   | `error` Event         | `websocket.error.phase`：`connect` 或 `runtime` |
+| `close`   | `close` Event         | code、reason、was_clean                       |
 
-Span 名统一为 `browser.websocket`，通过 `websocket.phase` 区分，不使用长连接 Span。基础字段包括：
+Span 名按 `websocket.<websocket.phase>` 生成，不使用长连接 Span。基础字段包括：
 
 - `network.protocol.name=websocket`
 - `url.full`，经脱敏

package/skills/bk-rum-otele/references/performance.md

@@ -6,7 +6,7 @@
 
 ## Web Vitals 总览
 
-`browser.web_vital` 覆盖：
+`span_type=vital` 覆盖以下指标，Span 名使用大写指标名：
 
 | 指标 | `vital.metric` | 单位 | 当前采集方式 |
 | --- | --- | --- | --- |
@@ -24,25 +24,16 @@
 
 - `vital.metric`
 - `vital.value`
-- `vital.rating=good|needs-improvement|poor`
 - `vital.id`
 - `span_type=vital`
-- `outcome.type=success`，仅 rating=good
+- `outcome.type=success`，仅内部 rating=good
 - `outcome.type=warning`，其他 rating
 
-Vital Span 是瞬时 INTERNAL Span。非法 `NaN`、`Infinity` 不上报。
+Vital Span 是瞬时 INTERNAL Span。非法 `NaN`、`Infinity` 不上报。当前 **不写** `vital.rating` 或 `navigationType` Attribute；good/poor 只通过 `outcome.type` 体现。
 
 ## Navigation Type
 
-优先使用 web-vitals metric 的 `navigationType`；否则读取首个 `PerformanceNavigationTiming.type`，并把 `back_forward` 规范为 `back-forward`。可能值包括：
-
-- `navigate`
-- `reload`
-- `back-forward`
-- `back-forward-cache`
-- `prerender`
-- `restore`
-- `unknown`
+web-vitals 指标对象可能带 `navigationType`，但当前插件 **不会** 把它写入 Span。不要按该字段查询 Collector 数据。
 
 ## FCP、LCP 与 TTFB 的 View 归属
 
@@ -52,8 +43,8 @@ Attribution 字段：
 
 | 指标 | 字段 |
 | --- | --- |
-| LCP | `vital.lcp.url`、`target`、`element_render_delay`、`resource_load_duration`、`time_to_first_byte` |
-| FCP | `vital.fcp.time_to_first_byte`、`load_state` |
+| LCP | `vital.lcp.url`、`target`、`element_render_delay`、`resource_load_duration` |
+| FCP | 当前无独立归因字段 |
 | TTFB | `vital.ttfb.waiting_duration`、`dns_duration`、`connection_duration`、`request_duration` |
 
 LCP URL 经过 `redactUrl`；DOM target 等字段可能包含高基数或业务语义，应纳入隐私审查。
@@ -66,16 +57,16 @@ SDK 不直接使用整页生命周期累计的 web-vitals CLS，而是按 SDK Vi
 - 相邻 Shift 间隔小于 1 秒且窗口总长小于 5 秒时进入同一 session window；
 - 取所有 session window 中累计值最大的一个；
 - 数值保留四位小数；
-- 记录该窗口中最大的单次 Shift 及目标元素；
+- 记录该窗口中最大的单次 Shift 及目标元素（仅用于内部累计 `vital.value`，**不上报** `vital.cls.largest_shift_*`）；
 - View 结束时发送一条 CLS Span，即使值为 0。
 
-Rating 阈值：
+Rating 阈值（只影响 `outcome.type`，不写 `vital.rating`）：
 
-- `<= 0.1`：good
-- `<= 0.25`：needs-improvement
-- `> 0.25`：poor
+- `<= 0.1`：good → `success`
+- `<= 0.25`：needs-improvement → `warning`
+- `> 0.25`：poor → `warning`
 
-Attribution：`vital.cls.largest_shift_target`、`vital.cls.largest_shift_value`。通过 web-vitals 原生指标产生时还可能带 `vital.cls.load_state`。
+当前 **不上报** `vital.cls.load_state`。按 View 汇总的 CLS 传入空 attribution。
 
 ## 每个 View 的 INP
 
@@ -133,19 +124,17 @@ tracking: {
 
 ## Long Task Span
 
-每条合格 Entry 生成 `browser.long_task` INTERNAL Span，Span 持续时间等于浏览器 Entry duration：
+每条合格 Entry 生成 `span_type=long_task` 的 INTERNAL Span。Span 名使用 `long_task.entry_type`，持续时间等于浏览器 Entry duration：
 
 - `long_task.id`
 - `long_task.entry_type=long-animation-frame|long-task`
-- `long_task.duration`
 - `long_task.name`
-- LoAF 的 `long_task.start_time`
 - LoAF 原生 `long_task.blocking_duration`
 - LoAF 的 `long_task.first_ui_event_timestamp`
 - LoAF 的 `long_task.render_start`
 - LoAF 的 `long_task.style_and_layout_start`
 
-Span 开始时间是 `performance.timeOrigin + entry.startTime`。该 Span 也会通知 Action Activity，使活动中的 Action 能关联此 Long Task。
+Span 开始时间是 `performance.timeOrigin + entry.startTime`，结束时间加上 `entry.duration`；持续时间只体现在 Span 起止时间上，没有独立的 `long_task.duration` 或 `long_task.start_time` Attribute。该 Span 也会通知 Action Activity，使活动中的 Action 能关联此 Long Task。
 
 ## LoAF 脚本 Event
 

package/skills/bk-rum-otele/references/privacy.md

@@ -52,7 +52,7 @@ await rum.setTrackingConsent('not-granted');
 - SDK 不提供 Consent UI、Cookie 分类或法律依据记录；
 - 页面中有多个 SDK 实例时，全局 OTel 对象按引用计数释放，但全局监听仍可能重复，因此仍应使用单实例。
 
-构造阶段有一个重要边界：`new BkOpenTelemetry()` 会先解析配置并创建 OpenTelemetry Resource。只要 `tracking.device !== false`，这个过程会同步读取 UA/UA-CH、内存、逻辑处理器等 Device Resource 快照，即使初始 Consent 是 `not-granted` 或 `enabled: false`；这些值此时不会发送，Device 插件的 ID/视口/网络监听也不会启动。如果你的合规定义连“读取到内存”都必须晚于授权，应在获得授权后再构造 SDK，而不是只依赖 `trackingConsent`。
+构造阶段有一个重要边界：`new BkOpenTelemetry()` 会先解析配置并创建 OpenTelemetry Resource。只要 `tracking.device !== false`，这个过程会同步读取 `navigator.userAgent` 与 UA-CH（`userAgentData.platform` / `mobile`），生成 `user_agent.*` 和 `device.type` 四个 Resource 字段，即使初始 Consent 是 `not-granted` 或 `enabled: false`；这些值此时不会发送，Device 插件的 ID/视口/网络监听也不会启动。如果你的合规定义连“读取 User-Agent”都必须晚于授权，应在获得授权后再构造 SDK，而不是只依赖 `trackingConsent`。
 
 ## URL 脱敏
 

package/skills/bk-rum-otele/references/session-context.md

@@ -20,7 +20,7 @@ SDK 使用以下固定规则：
 初始化时，SDK 尝试从 localStorage 读取同一应用和 Collector 隔离的 Session Record：
 
 - Record 有效：复用 ID，并延长无活动过期时间。
-- Record 不存在：创建新 Session，发送 `browser.session` start。
+- Record 不存在：创建新 Session，发送 `session.start` Span。
 - Record 已过期：创建新 ID，发送 rotate；旧 Session 的 end 由持有旧上下文的 Tab 发送。
 - localStorage 不可访问：退回当前 JavaScript 进程内存，不影响页面采集，但不能跨页面或跨 Tab 共享。
 
@@ -29,7 +29,7 @@ SDK 使用以下固定规则：
 用户活动会延长有效 Session。达到 15 分钟无活动或 4 小时最长生命周期时，SDK：
 
 1. 通知 View、Action 等插件 Session 已过期。
-2. 发送 `browser.session` end。
+2. 发送 `session.end` Span。
 3. 清除运行时 `session.*`。
 4. 结束当前 View。
 5. 触发一次 flush。
@@ -39,7 +39,13 @@ SDK 使用以下固定规则：
 
 ## 跨 Tab 行为
 
-默认 storage key 根据 `application.name` 与解析后 Endpoint host 计算，多个同源 Tab 因而共享 Session Record。
+默认 storage key 按 `application.name` 与 **解析后 Endpoint 的 host** 计算：
+
+```text
+bk_ot_session__${hash36(application.name + "\0" + endpointHost)}
+```
+
+`hash36` 是 djb2 风格非密码学 hash，转成 36 进制。同一浏览器 origin 下，不同 `application.name` 或不同 Collector host 不会共用 Session。多个同源 Tab 默认共享同一 key 下的 Session Record。
 
 - 其他 Tab 只延长当前相同 Session 时，本 Tab 会更新自己的过期 Timer。
 - 其他 Tab 使 Session 过期或替换 ID 时，本 Tab 会停用自己的 Session。
@@ -73,24 +79,23 @@ new BkOpenTelemetry({
 
 ## Session 遥测
 
-Span 名固定为 `browser.session`：
+Span 名按 `session.<session.phase>` 生成：
 
-| `session.phase` | 使用时机 | 常见 reason |
+| `session.phase` | 使用时机 | 内部 lifecycle reason（不上报为 Attribute） |
 | --- | --- | --- |
 | `start` | 首次创建 | `init` |
 | `rotate` | 旧 Session 过期后新建 | `inactivity`、`maxLifetime` |
 | `end` | 当前 Session 失效 | `inactivity`、`maxLifetime`、`external` |
 
-关键字段：
+实际上报字段只有：
 
 - `session.id`
-- `session.start_time`
 - `session.type=user`
 - `session.has_replay=false`
-- `session.lifecycle.reason`
-- `session.previous_id`，仅存在前一个 ID 时出现
 - `session.phase`
 
+过期原因通过 `onSessionLifecycle` 通知插件，**不会**写成 `session.lifecycle.reason` 或 `session.start_time`。完整字段见[遥测字段字典](./telemetry-reference.md#session-字段)。
+
 生命周期 Span 是瞬时事件，持续时间由服务端根据时间戳推导。
 
 ## User 上下文
@@ -121,10 +126,9 @@ SDK 只维护 `user.id`，并原样透传：不 hash、不截断、不验证、
 | `user_agent.name` | UA 简单识别：Edge/Chrome/Firefox/Safari/Other | 否 |
 | `user_agent.version` | UA 主版本 | 未识别版本时 |
 | `user_agent.os.name` | UA / UA-CH platform | 否，无法识别为 `Other` |
-| `device.type` | UA-CH mobile 或移动 UA | 否 |
-| `device.memory_gib` | `navigator.deviceMemory` | 浏览器未实现时 |
+| `device.type` | UA-CH mobile 或移动 UA 特征 | 否，仅为 `mobile` 或 `desktop` |
 
-关闭 `tracking.device` 时，这些 Device Resource 字段不写入。
+关闭 `tracking.device` 时，这些 Device Resource 字段不写入。当前不读取 `navigator.deviceMemory`，因此没有 `device.memory_gib`。
 
 ## Device 运行时属性