@blueking/open-telemetry 0.0.32 → 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.32",
+  "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

@@ -18,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。
 
@@ -122,7 +122,7 @@ Action 活动窗口内发生由 Activity Bus 通知的前端错误时，标记 `
 - `action.target.tag`
 - `action.frustration.type`，按 `rage_click`、`dead_click`、`error_click` 固定顺序的数组
 
-有页面活动时，持续时间体现在 Span 起止时间上，不写 `action.name` 或 `action.loading_time` Attribute。完整字段见[遥测字段字典](./telemetry-reference.md#action-字段)。
+有页面活动时，持续时间体现在 Span 起止时间上，不写 `action.loading_time` Attribute。完整字段见[遥测字段字典](./telemetry-reference.md#action-字段)。
 
 SDK 不在 Action Span 中写请求数、资源数、错误数或 Long Task 数；服务端通过 `action.id` 关联原始事件后派生。
 
@@ -137,7 +137,7 @@ bkOT.reportAction({
 });
 ```
 
-它立即创建并结束 Span `action.立即支付`（即 `action.<name>`）：
+它立即创建并结束名称为 `立即支付` 的 Action Span：
 
 - 新生成独立 `action.id`；
 - `action.type=custom`；

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

@@ -144,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`
 
@@ -180,7 +180,7 @@ interface BkOTActionEventPayload {
 }
 ```
 
-立即创建并结束 Span，名为 `action.<name>`（例如 `reportAction({ name: '立即购买' })` 得到 `action.立即购买`），写入新的 `action.id`、`action.type=custom`、`span_type=action` 和 `outcome.type=success`。它不是持续的自动 Action 窗口，不会等待或关联调用之后的请求。不要把它理解成固定 Span 名 `action.custom`。
+立即创建并结束以 `action.name` 命名的 Span，写入 `action.name` 和新的 `action.id`、`action.type=custom`、`span_type=action` 和 `outcome.type=success`。事件标识和时间直接使用 OTLP Span ID 与开始时间。它不是一个持续的自动 Action 窗口，不会等待或关联调用之后的请求。
 
 未命中 Session 采样时静默丢弃。
 
@@ -284,7 +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` |
+| `links` | `Link[]`，关联其他 Trace。OpenTelemetry 只允许在创建时传入，Span 结束前无法追加；内置请求插件用它把后端 Trace 关联回 Resource Span |
 
 运行时属性先合并，显式 `attributes` 后合并，因此显式同名字段优先；整体再经过 `redactAttributes`。未采样时返回 OTel non-recording Span，调用方仍可安全 `end()`。
 

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

@@ -108,7 +108,7 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 
 - `user.id`
 - `session.id`、`session.type`、`session.has_replay`
-- `view.id`、`view.url`、`view.url_template`、`view.loading_type`，以及显式命名后才出现的 `view.name`
+- `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。
 
 ## 适用边界
 
@@ -125,7 +125,7 @@ tracking: {
 
 ## 上报字段
 
-判定成功后创建瞬时 INTERNAL Span `browser.blank_screen`：
+判定成功后创建瞬时 INTERNAL Span。名称为 `blank_screen.<blank_screen.reason>`：
 
 | 字段 | 说明 |
 | --- | --- |

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.<name>`（`action.type=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 内匹配；

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

@@ -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

@@ -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 表达。
 

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`
@@ -30,7 +30,7 @@
 
 ## 未处理 Promise Rejection
 
-监听 `unhandledrejection`，创建 `browser.unhandledrejection`：
+监听 `unhandledrejection`，创建以异常类型命名的 Error Span：
 
 - `outcome.type=error`
 - `error.source=unhandledrejection`
@@ -40,7 +40,7 @@ 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`
@@ -118,7 +118,7 @@ tracking: {
 }
 ```
 
-插件监听 `document.securitypolicyviolation`，每个浏览器事件创建 `csp.violation` Error Span：
+插件监听 `document.securitypolicyviolation`。每个浏览器事件创建 `csp.<csp.effective_directive>` Error Span：
 
 - `outcome.type=error`
 - `error.source=csp`

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. 安装
 
@@ -203,7 +203,7 @@ rum.reportCustomEvent({
 ## 9. CDN 接入
 
 ```html
-<script src="https://unpkg.com/@blueking/open-telemetry@0.0.29/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: {
@@ -261,6 +261,7 @@ rum.startView({
 
 ## 接入后下一步
 
+- 想让 AI 生成配置：[用 AI 接入](/ai-setup)
 - 上线前逐项评审：[生产接入指南](./production.md)
 - Vue、React、微前端：[框架与路由集成](./framework-integration.md)
 - 查所有开关：[配置参考](./configuration.md)

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                         |
 | --------------------------- | ---------------------------------------------- | --------------------------- |
@@ -113,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`：
 
@@ -221,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`。
 
@@ -281,7 +281,7 @@ Timing-Allow-Origin: https://your-web.example.com
 | `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` | 单位 | 当前采集方式 |
 | --- | --- | --- | --- |
@@ -124,7 +124,7 @@ 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`

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。
@@ -79,7 +79,7 @@ new BkOpenTelemetry({
 
 ## Session 遥测
 
-Span 名固定为 `browser.session`：
+Span 名按 `session.<session.phase>` 生成：
 
 | `session.phase` | 使用时机 | 内部 lifecycle reason（不上报为 Attribute） |
 | --- | --- | --- |