@blueking/open-telemetry 0.0.31 → 0.0.33

package/dist/plugins/web-vitals.d.ts

@@ -4,7 +4,7 @@
  * 基于 google/web-vitals 库（attribution 版本）采集 Core Web Vitals：
  *   CLS / FCP / INP / LCP / TTFB
  *
- * browser.web_vital span 带 vital.id（唯一）、vital.value 与 attribution 详情
+ * Span 使用大写 vital.metric 命名，并带 vital.id（唯一）、vital.value 与 attribution 详情
  *   （LCP 元素 url / CLS shift target / INP interaction target 等高基数字段），
  *   方便按个例排查"哪个元素拖累了 LCP"
  *

package/dist/schema/attributes.d.ts

@@ -6,6 +6,7 @@
 export declare const RUM_ATTRIBUTES: {
     readonly actionFrustrationType: "action.frustration.type";
     readonly actionId: "action.id";
+    readonly actionName: "action.name";
     readonly actionTargetName: "action.target.name";
     readonly actionTargetTag: "action.target.tag";
     readonly actionType: "action.type";

package/dist/schema/span.d.ts

@@ -39,8 +39,17 @@ export interface RumSpanClassification {
     outcome?: RumSpanOutcome;
     spanType: RumSpanType;
 }
+interface RumSpanNameInput {
+    attributes: Attributes;
+    nameHint?: string;
+    spanType: RumSpanType;
+}
 export type RumSpanOutcome = (typeof RUM_SPAN_OUTCOME)[keyof typeof RUM_SPAN_OUTCOME];
 export type RumSpanType = (typeof RUM_SPAN_TYPE)[keyof typeof RUM_SPAN_TYPE];
+/**
+ * 使用稳定的领域字段生成可读 Span 名称。唯一 ID、完整 URL、错误消息和数值不参与命名，避免抬高基数。
+ */
+export declare const buildRumSpanName: ({ attributes, nameHint, spanType }: RumSpanNameInput) => string;
 export interface RumUrlTarget {
     serverAddress?: string;
     serverPort?: number;
@@ -50,3 +59,4 @@ export declare const getVitalOutcome: (rating: string | undefined) => RumSpanOut
 export declare const getUrlTarget: (url: string | undefined) => RumUrlTarget;
 export declare const buildRumSpanAttributes: ({ outcome, spanType, }: RumSpanClassification) => Attributes;
 export declare const buildRumResourceSpanAttributes: ({ initiatorType, method, outcome, url, }: RumResourceSpanInput) => Attributes;
+export {};

package/package.json

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

package/skills/bk-rum-otele/SKILL.md

@@ -55,7 +55,7 @@ SDK 只创建 Trace Provider。页面、请求、资源、错误、Vital、白
 
 SDK 把能力拆成两类：
 
-- **内置采集**：统一放在 `tracking`，包括 View、请求、资源、错误、Web Vitals、Action 等；其中 Fetch/XHR 由 SDK 自有的单一请求生命周期直接 patch，统一创建 `browser.resource` CLIENT Span。
+- **内置采集**：统一放在 `tracking`，包括 View、请求、资源、错误、Web Vitals、Action 等；其中 Fetch/XHR 由 SDK 自有的单一请求生命周期直接 patch，创建 `<METHOD> <url.template>` CLIENT Span。
 - **扩展**：接入方的 RUM 插件放在 `extensions.plugins`，标准 OpenTelemetry instrumentation 放在 `extensions.instrumentations`。它们都使用 SDK 私有 provider，并遵循 Consent 生命周期。
 
 ### 会话级确定性采样

package/skills/bk-rum-otele/evals/evals.json

@@ -21,7 +21,7 @@
       "id": 2,
       "name": "instrumentation-vs-plugin-httpbody",
       "prompt": "配置里有 instrumentations 和 plugins 两块，fetch、error 这些好像两边都能配？它们到底有什么区别？另外我想采集接口报错时的请求/响应 body 来排查问题，该怎么配、要注意什么？",
-      "expected_output": "正确区分内置 tracking、RUM Plugin 与额外 OTel Instrumentation；指出当前 request 是 SDK 自有 Fetch/XHR patch，生成 browser.resource CLIENT Span，不使用官方 Fetch/XHR instrumentation；说明 excludedUrls、allowedTracingUrls、request.beforeSend；SDK 不读取或上报 HTTP Body。",
+      "expected_output": "正确区分内置 tracking、RUM Plugin 与额外 OTel Instrumentation；指出当前 request 是 SDK 自有 Fetch/XHR patch，生成 <METHOD> <url.template> CLIENT Span，不使用官方 Fetch/XHR instrumentation；说明 excludedUrls、allowedTracingUrls、request.beforeSend；SDK 不读取或上报 HTTP Body。",
       "files": [],
       "assertions": []
     }

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 和部分用户行为。
@@ -16,7 +18,7 @@ Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认
 6. 最长等待 `maxDuration`，默认 10 秒。
 7. 从运行时上下文移除 Action ID。
 8. 最多再等待到 click 后 1 秒完成 Rage Click 判断。
-9. 创建并结束 `action.click` Span。
+9. 使用 `action.name` 创建并结束 Action Span。
 
 上报等待期不会延长 Action 关联窗口；后续无关事件不会因为等待 Rage Click 判断而关联旧 Action。
 
@@ -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.loading_time` Attribute。完整字段见[遥测字段字典](./telemetry-reference.md#action-字段)。
+
 SDK 不在 Action Span 中写请求数、资源数、错误数或 Long Task 数；服务端通过 `action.id` 关联原始事件后派生。
 
 ## 手动 Action
@@ -135,11 +137,11 @@ bkOT.reportAction({
 });
 ```
 
-它立即创建并结束 `action.custom`：
+它立即创建并结束名称为 `立即支付` 的 Action Span：
 
 - 新生成独立 `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>`
@@ -142,7 +144,7 @@ rum.startView({ name: '订单详情' });
 rum.setViewName('订单详情');
 ```
 
-没有采样 Session 时调用被忽略。`view.name` 只在显式命名后才上报，未调用时该字段不存在，聚合请按 `view.url_template`。
+没有采样 Session 时调用被忽略。`view.name` 默认取 `view.url_template`；`startView({ name })` 或 `setViewName()` 提供的名称优先。
 
 ### `setViewLoadingTime(): 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 窗口，不会等待或关联调用之后的请求。
+立即创建并结束以 `action.name` 命名的 Span，写入 `action.name` 和新的 `action.id`、`action.type=custom`、`span_type=action` 和 `outcome.type=success`。事件标识和时间直接使用 OTLP Span ID 与开始时间。它不是一个持续的自动 Action 窗口，不会等待或关联调用之后的请求。
 
 未命中 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 关联回 Resource Span |
 
 运行时属性先合并，显式 `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,8 +107,8 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 `RumRuntimeContext` 保存后续 Span 自动继承的属性：
 
 - `user.id`
-- `session.id`、`session.start_time`、`session.type`、`session.has_replay`
-- `view.id`、`view.url`、`view.url_template`、`view.loading_type`，以及显式命名后才出现的 `view.name`
+- `session.id`、`session.type`、`session.has_replay`
+- `view.id`、`view.url`、`view.url_template`、`view.loading_type` 和 `view.name`；`view.name` 优先使用显式名称，否则取 URL 模板
 - 活动窗口内的 `action.id`
 - Device 插件产生的视口、屏幕、网络和设备 ID
 - View 自定义属性
@@ -129,7 +129,7 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 - 未被请求级 `beforeSend` 标记丢弃；
 - 未被全局 `tracking.beforeSend` 丢弃。
 
-`browser.session` 生命周期 Span 是例外：它允许只有采样有效的 `session.id`，因为 Session start 可能早于 View 创建，Session end 可能发生在 View 已清理之后。
+`span_type=session` 的生命周期 Span 是例外：它允许只有采样有效的 `session.id`，因为 Session start 可能早于 View 创建，Session end 可能发生在 View 已清理之后。
 
 ## OpenTelemetry 全局对象
 

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

@@ -2,7 +2,7 @@
 
 # 白屏检测
 
-Blank Screen 插件用固定成本的视口九点采样判断页面是否缺少可见业务内容。它默认开启，但只在候选结果连续两次超过阈值时上报；每个 View 最多一条 `browser.blank_screen`。
+Blank Screen 插件用固定成本的视口九点采样判断页面是否缺少可见业务内容。它默认开启，但只在候选结果连续两次超过阈值时上报；每个 View 最多一条 `span_type=error` 的白屏 Span。
 
 ## 适用边界
 
@@ -118,35 +118,27 @@ 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`）。
 
 ## 上报字段
 
-判定成功后创建瞬时 INTERNAL Span `browser.blank_screen`：
+判定成功后创建瞬时 INTERNAL Span。名称为 `blank_screen.<blank_screen.reason>`：
 
 | 字段 | 说明 |
 | --- | --- |
 | `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

@@ -20,24 +20,24 @@ SDK 只产生原始 RUM Span：
 
 | 能力 | 配置/API | 默认 | 浏览器来源 | 主要 Span | 详情 |
 | --- | --- | --- | --- | --- | --- |
-| Session | `session` | 基础能力 | localStorage、活动、visibility、storage | `browser.session` | [Session 上下文](./session-context.md) |
-| View / Router | `tracking.view` | auto | Navigation Timing、History、hash、BFCache | `browser.view` | [View 与路由](./views-routing.md) |
-| View Loading Time | `tracking.view.loadingTime` | 开 | 请求/资源/DOM/`window.open` 活动 | `browser.view` update | [View 与路由](./views-routing.md) |
-| Fetch/XHR | `tracking.request` | 开 | fetch、XMLHttpRequest、Resource Timing | `browser.resource` CLIENT | [网络](./network.md) |
-| Trace Header | `allowedTracingUrls` | 无白名单 | W3C Trace Context | 被观测请求的 `traceparent` + `browser.resource` Span Link | [网络](./network.md) |
-| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` CLIENT | [网络](./network.md) |
-| JS Error | `tracking.error` | 开 | window error | `browser.error` | [错误与安全](./errors-security.md) |
-| Promise rejection | `tracking.error` | 开 | unhandledrejection | `browser.unhandledrejection` | [错误与安全](./errors-security.md) |
-| 资源加载错误 | `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) |
+| Session | `session` | 基础能力 | localStorage、活动、visibility、storage | `session.<phase>` | [Session 上下文](./session-context.md) |
+| View / Router | `tracking.view` | auto | Navigation Timing、History、hash、BFCache | `<view.name>` | [View 与路由](./views-routing.md) |
+| View Loading Time | `tracking.view.loadingTime` | 开 | 请求/资源/DOM/`window.open` 活动 | `<view.name>` update | [View 与路由](./views-routing.md) |
+| Fetch/XHR | `tracking.request` | 开 | fetch、XMLHttpRequest、Resource Timing | `<method> <url.template>` CLIENT | [网络](./network.md) |
+| Trace Header | `allowedTracingUrls` | 无白名单 | W3C Trace Context | 被观测请求的 `traceparent` + Resource Span Link | [网络](./network.md) |
+| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `GET <url.template>` CLIENT | [网络](./network.md) |
+| JS Error | `tracking.error` | 开 | window error | `<exception.type>` | [错误与安全](./errors-security.md) |
+| Promise rejection | `tracking.error` | 开 | unhandledrejection | `<exception.type>` | [错误与安全](./errors-security.md) |
+| 资源加载错误 | `tracking.error` | 开 | capture error | `ResourceError` | [错误与安全](./errors-security.md) |
+| Web Vitals | `tracking.webVitals` | 开 | web-vitals、PerformanceObserver | `<VITAL>` | [性能体验](./performance.md) |
+| 自动 Action | `tracking.action` | 开 | click、Activity 总线 | `click <target>` | [用户操作](./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) |
+| Blank Screen | `tracking.blankScreen` | 开 | DOM 九点采样、页面活动 | `blank_screen.<reason>` | [白屏](./blank-screen.md) |
 | Device | `tracking.device` | 开 | UA/UA-CH、Screen、Network Information | Resource/运行时属性 | [Session 上下文](./session-context.md) |
-| Long Task | `tracking.longTask` | 关 | LoAF 或 Long Tasks | `browser.long_task` | [性能体验](./performance.md) |
-| CSP | `tracking.cspViolation` | 关 | securitypolicyviolation | `csp.violation` | [错误与安全](./errors-security.md) |
-| WebSocket | `tracking.websocket` | 关 | WebSocket constructor/events | `browser.websocket` CLIENT | [网络](./network.md) |
+| Long Task | `tracking.longTask` | 关 | LoAF 或 Long Tasks | `<long_task.entry_type>` | [性能体验](./performance.md) |
+| CSP | `tracking.cspViolation` | 关 | securitypolicyviolation | `csp.<effective_directive>` | [错误与安全](./errors-security.md) |
+| WebSocket | `tracking.websocket` | 关 | WebSocket constructor/events | `websocket.<phase>` CLIENT | [网络](./network.md) |
 | RUM Plugin | `extensions.plugins` / `use()` | 无 | 插件决定 | `context.startSpan()` | [扩展](./extensions.md) |
 | OTel Instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | instrumentation 决定 | instrumentation Span | [扩展](./extensions.md) |
 
@@ -99,7 +99,7 @@ View 类型：
 
 Fetch/XHR 插件统一负责：
 
-- 建 `browser.resource` CLIENT Span；
+- 建 `span_type=resource` 的 CLIENT Span；
 - 请求结果和 HTTP status；
 - 可选 W3C `traceparent`：为每个白名单请求生成独立 trace context，并用 Span Link 关联，Link Attributes 记录命中格式与原始 Header；业务已有 trace Header 时不注入；
 - 与 Resource Timing 在最多 200ms 内匹配；
@@ -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
 
@@ -229,7 +229,7 @@ SPA 应将 `rootSelector` 指向真实挂载节点。详见[白屏检测](./blan
 ```ts
 tracking: {
   beforeSend(event) {
-    if (event.name === 'browser.resource' && event.attributes['url.full']?.includes('/noise')) {
+    if (event.attributes.span_type === 'resource' && event.attributes['url.full']?.includes('/noise')) {
       return false;
     }
     event.attributes['biz.reviewed'] = true;

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`，之后不会随运行时状态更新。
 
 ## 关联模型
 
@@ -90,9 +90,9 @@ PerformanceObserver 的回调时间可能晚于事件发生时间，因此 Resou
 
 Session、View 和 WebSocket 使用瞬时生命周期 Span：
 
-- `browser.session`：`session.phase=start|rotate|end`
-- `browser.view`：`view.phase=start|update|end`
-- `browser.websocket`：`websocket.phase=connect|open|error|close`
+- `span_type=session`：`session.phase=start|rotate|end`
+- `span_type=view`：`view.phase=start|update|end`
+- `span_type=websocket`：`websocket.phase=connect|open|error|close`
 
 这些 Span 的开始时间与结束时间相同；持续时间由相邻生命周期事件的时间戳在服务端推导，不通过一个数小时不结束的长 Span 表达。
 
@@ -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

@@ -15,7 +15,7 @@
 
 ## JavaScript 运行时错误
 
-监听冒泡阶段的 `window.error`，创建 `browser.error`：
+监听冒泡阶段的 `window.error`，创建以异常类型命名的 Error Span：
 
 - `span_type=error`
 - `outcome.type=error`
@@ -26,11 +26,11 @@
 - `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
 
-监听 `unhandledrejection`，创建 `browser.unhandledrejection`：
+监听 `unhandledrejection`，创建以异常类型命名的 Error Span：
 
 - `outcome.type=error`
 - `error.source=unhandledrejection`
@@ -40,12 +40,14 @@ Reason 是 Error 时保留其名称；其他对象尝试 JSON stringify，失败
 
 ## 资源加载错误
 
-在捕获阶段监听非 ErrorEvent 的 `error`，只处理 Event target 是 Element 的情况，创建 `browser.resource_error`：
+在捕获阶段监听非 ErrorEvent 的 `error`，只处理 Event target 是 Element 的情况，创建名为 `ResourceError` 的 Error Span：
 
 - `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 时 |
 
@@ -116,10 +118,9 @@ tracking: {
 }
 ```
 
-插件监听 `document.securitypolicyviolation`，每个浏览器事件创建 `csp.violation` Error Span：
+插件监听 `document.securitypolicyviolation`。每个浏览器事件创建 `csp.<csp.effective_directive>` 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

@@ -2,7 +2,7 @@
 
 # 快速上手
 
-本页用最少步骤完成安装、上报验证和第一个生产前配置。开始前需要一个接受 OTLP/HTTP JSON Trace 的 Collector 根地址；SDK 会固定请求 `<endpoint>/v1/rum`。
+本页用最少步骤完成安装、上报验证和第一个生产前配置。开始前需要一个接受 OTLP/HTTP JSON Trace 的 Collector 根地址；SDK 会固定请求 `<endpoint>/v1/rum`。也可以先安装自带 Skill，让 Cursor、Claude Code 或 Codex 按项目生成配置，见[用 AI 接入](/ai-setup)。
 
 ## 1. 安装
 
@@ -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.32/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 构建。
+
 ## 默认会采集什么
 
 最小配置默认开启：
@@ -243,6 +261,7 @@ rum.startView({
 
 ## 接入后下一步
 
+- 想让 AI 生成配置：[用 AI 接入](/ai-setup)
 - 上线前逐项评审：[生产接入指南](./production.md)
 - Vue、React、微前端：[框架与路由集成](./framework-integration.md)
 - 查所有开关：[配置参考](./configuration.md)