@blueking/open-telemetry 0.0.31 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",

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

@@ -6,9 +6,11 @@ Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认
 
 ## 自动 Action 生命周期
 
+插件在 `window` 上以 capture + passive 监听 `click`，**只处理主键点击**（`event.button === 0`）。右键、中键和辅助键点击不创建 Action。
+
 一次 click 的处理过程：
 
-1. 从 Event 取得真实发生时间和 composed target。
+1. 从 Event 取得真实发生时间和 composed target（`composedPath()[0]`，因此能穿透 Shadow DOM 拿到真实内部元素）。
 2. 生成 `action.id`，保存当时的 Session/View 上下文。
 3. 把当前活动的 `action.id` 字符串写入运行时上下文，后续请求、资源、错误和 Long Task 自动关联。多个点击窗口重叠时取最近一次。
 4. 观察请求、DOM Mutation、Resource、Long Task、Error 和部分用户行为。
@@ -33,7 +35,7 @@ Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认
 
 Error 会把 Action 标记为发生过活动、更新结束时间并标记 `error_click`；Long Task 也只影响 Action Activity。View Loading Time 的稳定判断会忽略 Error 和 Long Task。`view.excludedActivityUrls` 命中的请求/资源不参与 Action 活动。
 
-点击后 100ms 内没有任何页面活动时，Action 以零持续时间结束且没有 `action.loading_time`；它仍可能被识别为 Dead Click。
+点击后 100ms 内没有任何页面活动时，Action 以零持续时间结束（Span 起止时间相同）；它仍可能被识别为 Dead Click。持续时间用 OTLP 起止时间表达，不写 `action.loading_time` Attribute。
 
 ## 自动命名
 
@@ -116,12 +118,12 @@ Action 活动窗口内发生由 Activity Bus 通知的前端错误时，标记 `
 
 - `action.id`
 - `action.type=click`
-- `action.name`
 - `action.target.name`
 - `action.target.tag`
-- `action.loading_time`，只有观察到页面活动时存在，单位 ms
 - `action.frustration.type`，按 `rage_click`、`dead_click`、`error_click` 固定顺序的数组
 
+有页面活动时，持续时间体现在 Span 起止时间上，不写 `action.name` 或 `action.loading_time` Attribute。完整字段见[遥测字段字典](./telemetry-reference.md#action-字段)。
+
 SDK 不在 Action Span 中写请求数、资源数、错误数或 Long Task 数；服务端通过 `action.id` 关联原始事件后派生。
 
 ## 手动 Action
@@ -135,11 +137,11 @@ bkOT.reportAction({
 });
 ```
 
-它立即创建并结束 `action.custom`：
+它立即创建并结束 Span `action.立即支付`（即 `action.<name>`）：
 
 - 新生成独立 `action.id`；
 - `action.type=custom`；
-- `action.name` 使用传入名称；
+- Span 名为 `action.<传入 name>`；
 - `span_type=action`、`outcome.type=success`；
 - 不建立活动窗口；
 - 不计算 Loading Time 或挫败信号；
@@ -155,11 +157,15 @@ bkOT.reportAction({
 
 ### Action 名称只有标签名
 
-这是默认隐私行为。为元素或祖先添加 `data-bk-action-name`，或显式配置其他 `actionNameAttribute`。
+这是默认隐私行为。为元素或祖先添加 `data-bk-action-name`，或显式配置其他 `actionNameAttribute`。向上查找会跨越 Shadow DOM 边界（`parentElement` 为空时改用 `ShadowRoot.host`），因此 Web Component 内部元素也能继承宿主上的 data 属性。
+
+### 右键或中键点击没有 Action
+
+预期行为，只有 `event.button === 0` 的主键点击会创建 Action。需要记录其他交互时用 `reportAction()`。
 
-### 点击有请求但没有 Loading Time
+### 点击有请求但 Span 持续时间为 0
 
-检查请求是否命中 `view.excludedActivityUrls`，click 是否在请求开始前被其他监听逻辑延迟，以及 Action 是否在未采样/无 View 状态发生。
+检查请求是否命中 `view.excludedActivityUrls`，click 是否在请求开始前被其他监听逻辑延迟，以及 Action 是否在未采样/无 View 状态发生。持续时间看 Span 起止时间，不要查 `action.loading_time` Attribute。
 
 ### Dead Click 过多
 

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

@@ -30,6 +30,8 @@ CDN bundle 的默认导出会挂到：
 window.BkOpenTelemetry
 ```
 
+它只提供这个构造函数，不挂载 ESM 入口里的插件工厂、schema 常量或 TypeScript 类型。
+
 ## 生命周期 API
 
 ### `start(): Promise<void>`
@@ -178,7 +180,7 @@ interface BkOTActionEventPayload {
 }
 ```
 
-立即创建并结束 `action.custom` Span，写入新的 `action.id`、`action.type=custom`、`span_type=action` 和 `outcome.type=success`。事件标识和时间直接使用 OTLP Span ID 与开始时间。它不是一个持续的自动 Action 窗口，不会等待或关联调用之后的请求。
+立即创建并结束 Span，名为 `action.<name>`（例如 `reportAction({ name: '立即购买' })` 得到 `action.立即购买`），写入新的 `action.id`、`action.type=custom`、`span_type=action` 和 `outcome.type=success`。它不是持续的自动 Action 窗口，不会等待或关联调用之后的请求。不要把它理解成固定 Span 名 `action.custom`。
 
 未命中 Session 采样时静默丢弃。
 
@@ -282,6 +284,7 @@ span.end(endedAt);
 | `startTime` | OTel `TimeInput`；浏览器场景常用 epoch milliseconds |
 | `contextTime` | 用哪个 epoch ms 回查 Session/View/Action；缺省时复用数字型 `startTime` |
 | `kind` | SpanKind，默认 `INTERNAL` |
+| `links` | `Link[]`，关联其他 Trace。OpenTelemetry 只允许在创建时传入，Span 结束前无法追加；内置请求插件用它把后端 Trace 关联回 `browser.resource` |
 
 运行时属性先合并，显式 `attributes` 后合并，因此显式同名字段优先；整体再经过 `redactAttributes`。未采样时返回 OTel non-recording Span，调用方仍可安全 `end()`。
 
@@ -325,7 +328,7 @@ import { resolveConfig } from '@blueking/open-telemetry';
 | `RUM_ATTRIBUTES` | SDK 公共字段 key 常量表 |
 | `RUM_SPAN_TYPE` | RUM Span 大类常量表 |
 | `RUM_SPAN_OUTCOME` | success/warning/error/timeout/abort 常量表 |
-| `buildRumSpanAttributes` | 根据 spanType/outcome/outcomeReason 生成分类属性 |
+| `buildRumSpanAttributes` | 根据 spanType/outcome 生成 `span_type` 与 `outcome.type`；当前不写 `outcome.reason` |
 
 内置插件工厂适合 SDK 定制或组合插件。普通接入使用 `tracking` 开关即可；不要把同一个内置工厂再放进 `extensions.plugins`，否则可能重复监听和上报。
 

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

@@ -44,7 +44,7 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 
 1. `resolveConfig()` 校验 `application.name` 和 `transport.endpoint`。
 2. 解析应用、传输、采样、Hook 和默认配置。
-3. 创建 OpenTelemetry Resource；默认 Device 开启时会在此同步读取 UA、OS、内存和逻辑处理器快照，这一步早于 Consent 插件生命周期。
+3. 创建 OpenTelemetry Resource；默认 Device 开启时会在此同步读取 UA / UA-CH（浏览器名与版本、OS、`mobile` 标记）快照，这一步早于 Consent 插件生命周期。
 4. 创建 `OTLPTraceExporter`，目标固定为 `<endpoint>/v1/rum`。
 5. 按 `transport.processor` 创建 `BatchSpanProcessor` 或 `SimpleSpanProcessor`。
 6. 在外层包裹 `FilteringSpanProcessor`。
@@ -107,7 +107,7 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 `RumRuntimeContext` 保存后续 Span 自动继承的属性：
 
 - `user.id`
-- `session.id`、`session.start_time`、`session.type`、`session.has_replay`
+- `session.id`、`session.type`、`session.has_replay`
 - `view.id`、`view.url`、`view.url_template`、`view.loading_type`，以及显式命名后才出现的 `view.name`
 - 活动窗口内的 `action.id`
 - Device 插件产生的视口、屏幕、网络和设备 ID

package/skills/bk-rum-otele/references/blank-screen.md

@@ -118,11 +118,10 @@ tracking: {
 - `body` 中存在足够的可见内容时不报告白屏；
 - 只有回退采样的空白比例仍达到阈值，才进入二次确认；
 - `blank_screen.reason=missing_root`
-- `blank_screen.root_found=false`
-- empty ratio 和采样计数来自 `body` 的实际检测结果；
-- 二次确认仍为空白才上报。
+- empty ratio 和 `empty_sample_count` 来自回退后的实际检测结果，不是固定 `1`
+- 二次确认仍为空白才上报
 
-根节点缺失本身不再作为白屏证据，避免 Vue 等框架替换初始挂载容器后，在 SPA View 切换时持续误报。`missing_root` 表示配置根节点缺失且回退后的视口也符合白屏条件；排障时仍应检查 selector 是否稳定。
+根节点缺失本身不再作为白屏证据，避免 Vue 等框架替换初始挂载容器后，在 SPA View 切换时持续误报。`missing_root` 表示配置根节点缺失且回退后的视口也符合白屏条件；排障时仍应检查 selector 是否稳定。当前 Span **不写** `root_found`、`root_selector`、`center_element` 或各类 sample_count 分项（除 `empty_sample_count`）。
 
 ## 上报字段
 
@@ -131,22 +130,15 @@ tracking: {
 | 字段 | 说明 |
 | --- | --- |
 | `blank_screen.reason` | `missing_root` / `empty_viewport` |
-| `blank_screen.empty_ratio` | 空白有效点比例 |
-| `blank_screen.sample_count` | 固定 9 |
-| `blank_screen.valid_sample_count` | 9 - ignored |
+| `blank_screen.empty_ratio` | 空白有效点比例，即 `emptyCount / validCount` |
 | `blank_screen.empty_sample_count` | 空白点数 |
-| `blank_screen.ignored_sample_count` | Loading/Skeleton 点数 |
-| `blank_screen.root_selector` | 当前配置 |
-| `blank_screen.root_found` | 根节点是否存在 |
-| `blank_screen.center_element` | 中心点最上层元素的 `tag` 或 `tag#id` |
 
 分类固定：
 
 - `span_type=error`
 - `outcome.type=error`
-- `outcome.reason=blank_screen`
 
-Span 自动关联 Session 和 View，但插件本身不写 Error exception Event，也不设置 OpenTelemetry Status ERROR。
+不写 `outcome.reason`，不设置 OpenTelemetry Status ERROR，也不记录 exception Event。完整字段见[遥测字段字典](./telemetry-reference.md#白屏字段)。
 
 ## 每个 View 最多一次
 
@@ -181,10 +173,9 @@ new BkOpenTelemetry({
 
 1. `reason` 是否为 `missing_root`。
 2. `rootSelector` 是否指向真正承载内容的稳定节点。
-3. `valid_sample_count` 是否太少。
+3. `empty_ratio` 是否只是略高于阈值。
 4. 页面是否用 Canvas、iframe 或背景图承载主要内容。
-5. `center_element` 是否显示遮罩或布局容器。
-6. 异步渲染是否晚于 `checkDelay + confirmationDelay`。
-7. View Loading Activity 是否没有覆盖业务的异步过程。
+5. 异步渲染是否晚于 `checkDelay + confirmationDelay`。
+6. View Loading Activity 是否没有覆盖业务的异步过程。
 
 完整字段见[遥测字段字典](./telemetry-reference.md#白屏字段)。

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

@@ -31,7 +31,7 @@ SDK 只产生原始 RUM Span：
 | 资源加载错误 | `tracking.error` | 开 | capture error | `browser.resource_error` | [错误与安全](./errors-security.md) |
 | Web Vitals | `tracking.webVitals` | 开 | web-vitals、PerformanceObserver | `browser.web_vital` | [性能体验](./performance.md) |
 | 自动 Action | `tracking.action` | 开 | click、Activity 总线 | `action.click` | [用户操作](./actions.md) |
-| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` | [用户操作](./actions.md) |
+| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.<name>`（`action.type=custom`） | [用户操作](./actions.md) |
 | Custom event | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | [API](./api.md) |
 | Blank Screen | `tracking.blankScreen` | 开 | DOM 九点采样、页面活动 | `browser.blank_screen` | [白屏](./blank-screen.md) |
 | Device | `tracking.device` | 开 | UA/UA-CH、Screen、Network Information | Resource/运行时属性 | [Session 上下文](./session-context.md) |
@@ -122,7 +122,7 @@ SDK 不做错误节流、fingerprint 和分组。CSP 插件每次 violation 建
 
 ## Web Vitals 与 Long Task
 
-Vitals：CLS、FCP、INP、LCP、TTFB。每个指标保留 value、rating 和浏览器可提供的 attribution。CLS 和 INP 按当前 View 聚合边界定稿，不是全站一个永久累计值。
+Vitals：CLS、FCP、INP、LCP、TTFB。每条 Span 带 `vital.metric`、`vital.value`、`vital.id`；内部 rating 只映射为 `outcome.type`。CLS/INP 按当前 View 聚合定稿。LCP/TTFB 带部分 attribution，FCP/CLS 当前没有独立归因字段。详见[性能体验](./performance.md)。
 
 Long Task 优先 Long Animation Frame 获取脚本归因，不支持时回退 Long Tasks。默认关闭，threshold 默认 50ms。
 

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

@@ -65,10 +65,10 @@ new BkOpenTelemetry({
 | `headers` | `Record<string, string>` | 无 | 自定义头；同名时覆盖 token 生成的头 |
 | `processor` | `'batch' \| 'simple'` | `'batch'` | 批量或逐 Span 导出 |
 | `batch` | `BkOTBatchConfig` | OTel 默认值 | 仅 batch 模式生效 |
-| `timeoutMillis` | `number` | `10000` | exporter 请求及重试的总期限，必须大于 0 |
-| `concurrencyLimit` | `number` | `30` | exporter 并发 Promise 上限 |
+| `timeoutMillis` | `number` | 未配置时沿用 OTel exporter | exporter 请求及重试的总期限，必须大于 0。当前锁定的 `@opentelemetry/exporter-trace-otlp-http` 默认约为 `10000` |
+| `concurrencyLimit` | `number` | 未配置时沿用 OTel exporter | exporter 并发 Promise 上限。当前锁定依赖默认约为 `30` |
 
-`batch` 子项：
+`batch` 子项由 SDK 原样传给 `BatchSpanProcessor`，本包不硬编码。未配置时沿用锁定的 `@opentelemetry/sdk-trace-base` 默认值（当前常见为）：
 
 | 配置 | 默认 | 说明 |
 | --- | ---: | --- |
@@ -214,7 +214,7 @@ SPA 应将 `rootSelector` 指向真实挂载节点。详见[白屏检测](./blan
 | `persistentId` | `boolean` | `false` | 是否把匿名设备 ID 持久化到 localStorage |
 | `storageKey` | `string` | `BK_RUM_DEVICE_ID_<应用 hash>` | 持久设备 ID 的 key |
 
-`persistentId: false` 时，每次 Device 插件初始化都会创建新的设备 ID，只在当前采集周期内稳定；撤销再授予 Consent 会重新初始化插件并换 ID。`tracking.device: false` 还会阻止浏览器/OS/硬件 Resource 属性生成。详见[Session、用户与设备上下文](./session-context.md)。
+`persistentId: false` 时，每次 Device 插件初始化都会创建新的设备 ID，只在当前采集周期内稳定；撤销再授予 Consent 会重新初始化插件并换 ID。`tracking.device: false` 还会阻止 `user_agent.*` 与 `device.type` 这四个 Resource 属性生成。详见[Session、用户与设备上下文](./session-context.md)。
 
 ## longTask
 

package/skills/bk-rum-otele/references/data-model.md

@@ -30,7 +30,7 @@ resourceSpans[]
 | Resource           | `service.name`、`telemetry.sdk.version`、`session.sample_rate` | SDK 实例固定  | 配置解析和 Device Resource |
 | OpenTelemetry Span | `traceId`、`spanId`、`kind`、开始/结束时间、Status          | 单个 Span     | OpenTelemetry Provider     |
 | RUM 运行时上下文   | `session.id`、`view.id`、`action.id`、`user.id`             | 随运行时变化  | `RumRuntimeContext`        |
-| RUM 分类与结果     | `span_type`、`outcome.type`、`outcome.reason`               | 单个原始 Span | 内置插件或手动 API         |
+| RUM 分类与结果     | `span_type`、`outcome.type`                                 | 单个原始 Span | 内置插件或手动 API         |
 | 领域字段           | `resource.*`、`vital.*`、`error.*`、`blank_screen.*`        | 单项能力决定  | 对应插件                   |
 
 服务端派生字段不属于以上五层，不应伪装成浏览器原始字段。
@@ -45,11 +45,11 @@ Resource 在构造时创建，同一 SDK 实例的全部 Span 共用。基础字
 | `service.version`             | `application.version`，未配置时不存在        |
 | `deployment.environment.name` | `application.environment`，默认 `production` |
 | `session.sample_rate`         | 解析后的 `session.sampleRate`                |
-| `telemetry.sdk.name`          | 固定 `@blueking/open-telemetry`              |
+| `telemetry.sdk.name`          | 固定 `blueking`                            |
 | `telemetry.sdk.language`      | 固定 `webjs`                                 |
 | `telemetry.sdk.version`       | 当前 npm 包版本                              |
 
-默认开启 Device 时，还会写入浏览器、操作系统、设备类型、内存和逻辑处理器字段。Resource 会在构造时经过一次 `privacy.redactAttributes`，之后不会随运行时状态更新。
+默认开启 Device 时，还会写入 `user_agent.name`、`user_agent.version`、`user_agent.os.name` 和 `device.type` 四个字段，全部来自 UA / UA-CH 解析。SDK 不读取设备内存或逻辑处理器数。Resource 会在构造时经过一次 `privacy.redactAttributes`，之后不会随运行时状态更新。
 
 ## 关联模型
 
@@ -106,19 +106,17 @@ View 每次发出 start/update/end 都会递增 `view.version`。服务端应以
 | ---------------- | --------------------------------------------------------------------------------------------------- |
 | `span_type`      | 大类：`session`、`view`、`resource`、`vital`、`error`、`long_task`、`action`、`websocket`、`custom` |
 | `outcome.type`   | `success`、`warning`、`error`、`timeout`、`abort`                                                   |
-| `outcome.reason` | 可选结果原因，例如 `network`、`network_timeout`、`http_4xx`、`http_5xx`                             |
 
-`span_type` 表示 Span 类别，`outcome.type` 表示结果，两者不要混用。例如带异常的 `custom.checkout` 仍是 `span_type=custom`，但 `outcome.type=error` 且 Span Status 为 ERROR。具体子类由 `resource.type`、`vital.metric`、`error.source` 等领域字段表达。
+`span_type` 表示 Span 类别，`outcome.type` 表示结果，两者不要混用。例如带异常的 `custom.checkout` 仍是 `span_type=custom`，但 `outcome.type=error` 且 Span Status 为 ERROR。具体子类由 `resource.type`、`vital.metric`、`error.source`、`blank_screen.reason` 等领域字段表达。当前 SDK **不写** `outcome.reason`。
 
-HTTP Result 规则：
+HTTP 结果只映射 `outcome.type`：
 
-- `408`、`504` → `outcome.type=timeout`、`outcome.reason=network_timeout`
-- 其他 `4xx` → `outcome.type=error`、`outcome.reason=http_4xx`
-- `5xx` → `outcome.type=error`、`outcome.reason=http_5xx`
-- Fetch AbortError 或 XHR `abort` → `outcome.type=abort`，不写 reason
-- Fetch TimeoutError 或 XHR `timeout` → `outcome.type=timeout`、`outcome.reason=network_timeout`
-- Fetch 网络异常或 XHR `error` → `outcome.type=error`、`outcome.reason=network`
-- 其他状态 → `outcome.type=success`，不写 reason
+- `408`、`504` 以及 Fetch TimeoutError / XHR `timeout` → `timeout`
+- 其他 `4xx` / `5xx`、Fetch 网络异常、XHR `error` → `error`
+- Fetch AbortError 或 XHR `abort` → `abort`
+- 其他状态 → `success`
+
+状态码和失败细节见 [遥测字段字典 · 请求与静态资源](./telemetry-reference.md#请求与静态资源字段)。
 
 ## Span Kind 与 Status
 

package/skills/bk-rum-otele/references/errors-security.md

@@ -26,7 +26,7 @@
 - `code.lineno`
 - `code.column`
 
-跨域脚本只暴露 `Script error.` 且没有 Error/filename 时，增加 `error.cross_origin=true`。要获得完整错误和 Stack，脚本资源需要正确配置 CORS，并使用合适的 `crossorigin` 属性。
+跨域脚本只暴露 `Script error.`，且 `code.filepath` 为空、没有 exception stack。SDK 不为这种情况写额外标记字段（没有 `error.cross_origin`），排查时按 `error.message === 'Script error.'` 识别。要获得完整错误和 Stack，脚本资源需要正确配置 CORS，并使用合适的 `crossorigin` 属性。
 
 ## 未处理 Promise Rejection
 
@@ -45,7 +45,9 @@ Reason 是 Error 时保留其名称；其他对象尝试 JSON stringify，失败
 - `outcome.type=error`
 - `error.source=resource`
 - `url.full`：从 `src`、`href` 或 `currentSrc` 读取并脱敏
-- `html.tag`：目标标签名
+- `error.message`：固定格式 `Resource load failed: <小写标签名> <原始 URL>`
+
+失败元素的标签名只出现在 `error.message` 中，没有独立的 `html.tag` 字段。注意该 message 里的 URL 是**未脱敏**的原始值，只有 `url.full` 经过 `redactUrl`；URL 可能含敏感信息时应用 `redactAttributes` 重写 `error.message`。
 
 该事件与 Performance Resource Span 不同：它表示浏览器资源元素加载失败，可能没有 HTTP Status 或 Resource Timing。
 
@@ -55,7 +57,7 @@ Reason 是 Error 时保留其名称；其他对象尝试 JSON stringify，失败
 
 | Event 字段 | 说明 |
 | --- | --- |
-| `exception.type` | Error name 或归一名称 |
+| `exception.type` | Error 的 `name`；非 Error 值时为 `window.error`、`UnhandledRejection` 或 `ResourceError` |
 | `exception.message` | 完整消息 |
 | `exception.stacktrace` | Error 存在 Stack 时 |
 
@@ -119,7 +121,6 @@ tracking: {
 插件监听 `document.securitypolicyviolation`，每个浏览器事件创建 `csp.violation` Error Span：
 
 - `outcome.type=error`
-- `outcome.reason=csp`
 - `error.source=csp`
 - `csp.blocked_uri`
 - `csp.violated_directive`

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

@@ -87,6 +87,10 @@ await bkOT.start();
 | `applyRedact()` | 执行属性脱敏 |
 | `flush()` | 请求 SDK 刷新 |
 | `registerInstrumentations()` | 插件内注册额外 Instrumentation |
+| `setUser()` | 更新 `user.id` |
+| `setView()` / `onViewCommand()` | 直接操作 View 上下文与命令流，仅供替换内置 View 插件的场景 |
+
+`setView()`、`onViewCommand()`、`onViewChange()`、`notifyActivity()` 和 `onActivity()` 只存在于 Plugin Context，**不在** `BkOTInstance` 公开接口上；业务代码应使用 `startView()` / `setViewName()`。
 
 ## 创建正确的自定义 Span
 
@@ -210,6 +214,10 @@ SDK 对每个 Instrumentation：
 
 Instrumentation 创建的 Span 由 `FilteringSpanProcessor.onStart()` 补充缺失的 RUM 上下文。它显式设置的同名属性优先，不会被 Processor 覆盖。
 
+Instrumentation 不需要自己判断采样：Provider 上的 `RumSessionSampler` 在 Session 未采样时让所有 Span 变成 non-recording。但导出条件仍然适用——Instrumentation Span 必须在创建时就处于有效 Session + View 上下文中，否则会在 `onEnd` 被过滤掉。因此在 `start()` 之前或 manual View 尚未建立时产生的第三方 Span 会静默丢弃。
+
+过滤层识别自上报请求时会同时检查 `url.full` 和 `http.url`。标准 OTel HTTP Instrumentation 写的是 `http.url`，所以它对 Collector 自身的请求也能被正确排除，不会形成上报回环。
+
 限制：
 
 - 当前稳定边界只有 Trace；

package/skills/bk-rum-otele/references/framework-integration.md

@@ -340,7 +340,7 @@ consentManager.onChange(async allowed => {
 
 如果使用 manual View，授权后需要确认新的 Session 已创建，再按当前 Router 状态调用 `startView()`。自动模式会由 View 插件建立当前 View。
 
-这个示例适用于“授权前可以构造、但不能采集和发送”的策略。若合规要求授权前连 UA/UA-CH、内存等 Device Resource 快照都不能读取，应把 `new BkOpenTelemetry()` 本身也延迟到首次授权后；只设置 `trackingConsent: 'not-granted'` 不会推迟构造阶段的 Device Resource 读取。
+这个示例适用于“授权前可以构造、但不能采集和发送”的策略。若合规要求授权前连 UA / UA-CH 这类 Device Resource 快照都不能读取，应把 `new BkOpenTelemetry()` 本身也延迟到首次授权后；只设置 `trackingConsent: 'not-granted'` 不会推迟构造阶段的 Device Resource 读取。
 
 ## 微前端
 

package/skills/bk-rum-otele/references/getting-started.md

@@ -147,6 +147,22 @@ context: {
 
 SDK 原样透传 `user.id`，不会 hash。不要直接发送手机号、邮箱或可枚举的敏感账号标识。
 
+需要先弹同意再采集时，不要依赖默认 `trackingConsent: 'granted'`：
+
+```ts
+const rum = new BkOpenTelemetry({
+  application: { name: 'order-center' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  privacy: { trackingConsent: 'not-granted' },
+});
+
+async function onConsentGranted() {
+  await rum.setTrackingConsent('granted');
+}
+```
+
+默认 Consent 仍会在构造期读取 Device Resource（UA、设备类型）。若授权前不能读取设备信息，应推迟整个 `new BkOpenTelemetry()`。完整边界见[隐私、Consent 与字段治理](./privacy.md)。
+
 ## 8. 手动上报业务事件
 
 手动 Action：
@@ -187,7 +203,7 @@ rum.reportCustomEvent({
 ## 9. CDN 接入
 
 ```html
-<script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
+<script src="https://unpkg.com/@blueking/open-telemetry@0.0.29/dist/bk-rum.global.js"></script>
 <script>
   window.rum = new window.BkOpenTelemetry({
     application: {
@@ -204,6 +220,8 @@ rum.reportCustomEvent({
 
 生产 CDN 地址应固定 npm package 版本并使用你们认可的 CDN/SRI 策略，不要长期跟随 latest。全局 bundle 包含所需依赖，公开类名是 `window.BkOpenTelemetry`。
 
+CDN 入口**只暴露**这个类（以及 `export default`），不能像 ESM 那样从包里具名导入 `createXxxPlugin`、`RUM_ATTRIBUTES` 或 TypeScript 类型。需要插件工厂或 schema 常量时请走 npm ESM 构建。
+
 ## 默认会采集什么
 
 最小配置默认开启：

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

@@ -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                       |
-
-SDK 不根据业务响应 JSON 中的 code 判断成功或失败；需要业务口径时使用 `request.beforeSend` 增加属性，或上报自定义事件。
+| 条件                               | `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 **不写** `outcome.reason`。HTTP 失败请用 `http.response.status_code` 细分。SDK 不根据业务响应 JSON 中的 code 判断成功或失败；需要业务口径时使用 `request.beforeSend` 增加属性，或上报自定义事件。
 
 ## URL 排除
 
@@ -275,12 +274,12 @@ 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。基础字段包括：
 

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

@@ -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
 
@@ -137,15 +128,13 @@ tracking: {
 
 - `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

@@ -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。
@@ -75,22 +81,21 @@ new BkOpenTelemetry({
 
 Span 名固定为 `browser.session`：
 
-| `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 运行时属性