@blueking/open-telemetry 0.0.21 → 0.0.22

package/dist/plugins/common.d.ts

@@ -8,5 +8,5 @@ interface RequestDetails {
     url?: string;
 }
 export { REQUEST_DISCARD_ATTRIBUTE };
-export declare const decorateRequestSpan: (context: BkOTRuntimeContext, span: Span, subtype: "fetch" | "xhr", domainContext: BkOTRequestContext, details?: RequestDetails, fetchRequest?: Request | RequestInit) => void;
+export declare const decorateRequestSpan: (context: BkOTRuntimeContext, span: Span, subtype: "fetch" | "xhr", domainContext: BkOTRequestContext, details?: RequestDetails) => void;
 export declare const createCommonInstrumentationsPlugin: (option: BkOTRequestConfig | boolean | undefined) => BkOTPlugin;

package/dist/plugins/csp-violation.d.ts

@@ -3,14 +3,6 @@ import type { BkOTPlugin } from '../core/plugin';
  * CSP 违规事件采集插件，通过监听 `securitypolicyviolation` 事件捕获被 CSP 策略拦截的脚本/资源，
  * 以 error span 上报，进入统一错误分析口径。
  *
- * 节流策略：
- * - 同 fingerprint（`violatedDirective + blockedURI + sourceFile + lineNumber`）
- *   在 60s 窗口内最多上报 5 条，避免风暴打爆 collector（如某段被拦截的 inline 脚本被反复渲染）。
- * - `browser.csp_violation.count` counter 在节流前累计所有违规，span 只保留窗口触发序号。
- *
- * 体积优化：
- * - `csp.original_policy`（完整 CSP 策略，可能数 KB）仅在窗口首条上报，后续同 fingerprint 不再重复携带。
- *
  * URL 处理：
  * - `blockedURI` / `sourceFile` 中的 URL 类值会经 `redactUrl` 脱敏。
  * - `blockedURI` 是 'inline' / 'eval' 等 CSP 关键字时直接保留，不调用 redactUrl。

package/dist/plugins/device.d.ts

@@ -20,8 +20,8 @@ export declare const getDeviceResourceAttributes: () => Attributes;
  * - viewport 监听 `resize` / `orientationchange`，并经 250ms debounce 合并，避免拖窗口时高频触发；
  *   静默期结束后用最终值刷新 runtimeAttributes。
  * - network 监听 `connection.change`（本身低频，不需要 throttle）。
- * - 二者只更新 in-memory 的 runtimeAttributes，不会主动产生新的 span/log，cardinality 安全；
- *   但更新后续生成的 log/span 会带最新值。
+ * - 二者只更新 in-memory 的 runtimeAttributes，不会主动产生新的 Span；
+ *   更新后续生成的 Span 会带最新值。
  *
  * 与 session 插件的关系：device 跨会话持久（终身），session 有过期与续期（连续访问语义）。
  */

package/dist/plugins/error.d.ts

@@ -1,6 +1,2 @@
 import type { BkOTPlugin } from '../core/plugin';
-export interface BkOTErrorPluginOptions {
-    maxPerWindow?: number;
-    windowMs?: number;
-}
-export declare const createErrorPlugin: (options?: BkOTErrorPluginOptions) => BkOTPlugin;
+export declare const createErrorPlugin: () => BkOTPlugin;

package/dist/plugins/long-task.d.ts

@@ -1,12 +1,10 @@
 import type { BkOTPlugin } from '../core/plugin';
 /**
  * 主线程阻塞优先使用 Long Animation Frame API 获取脚本归因，不支持时回退到 Long Tasks API；
- * span 保留单次诊断详情，metric 只保留低基数维度用于聚合分布。
+ * span 保留单次诊断详情，分布与计数由服务端从原始事件计算。
  */
 export interface BkOTLongTaskPluginOptions {
     /** 采集阈值，默认 50ms。Performance API 本身通常只产生大于 50ms 的条目。 */
     threshold?: number;
-    /** 标记 warning 的阈值，默认 100ms。 */
-    warningThreshold?: number;
 }
 export declare const createLongTaskPlugin: (options?: BkOTLongTaskPluginOptions) => BkOTPlugin;

package/dist/plugins/resource.d.ts

@@ -9,6 +9,7 @@ type ResourceTimingWithStatus = PerformanceResourceTiming & {
     responseStatus?: number;
 };
 export declare const getResourceTimingAttributes: (entry: ResourceTimingWithStatus) => Record<string, number>;
+export declare const getResourceDuration: (entry: ResourceTimingWithStatus) => number;
 export declare const getResourcePerformanceAttributes: (entry: ResourceTimingWithStatus) => {
     'resource.encoded_body_size': number;
     'resource.decoded_body_size': number;

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

@@ -4,16 +4,11 @@
  * 基于 google/web-vitals 库（attribution 版本）采集 Core Web Vitals：
  *   CLS / FCP / INP / LCP / TTFB
  *
- * 维度分层（关键设计）：
- * - metric (histogram)：仅带低基数维度（`view.url_path_group` / navigation.type / vital.name / vital.rating），
- *   适合做 P50 / P75 / P99 聚合统计，避免维度爆炸
- * - span (browser.web_vital)：带 vital.id（唯一）、vital.value 与 attribution 详情
+ * browser.web_vital span 带 vital.id（唯一）、vital.value 与 attribution 详情
  *   （LCP 元素 url / CLS shift target / INP interaction target 等高基数字段），
  *   方便按个例排查"哪个元素拖累了 LCP"
  *
- * Histogram 设计：
- * - browser.web_vital.cls：单位 '1'（无量纲），CLS 是累积分数，不能与 ms 混用
- * - browser.web_vital.duration：单位 'ms'，FCP/INP/LCP/TTFB 共享，靠 vital.metric 维度区分
+ * 数值语义：CLS 是无量纲分数，FCP/INP/LCP/TTFB 的 vital.value 单位为 ms。
  *
  * Navigation Type：
  *   优先使用 metric.navigationType（web-vitals 内部计算，含 'back-forward-cache' 等准确值），

package/dist/schema/attributes.d.ts

@@ -4,14 +4,10 @@
  * 插件里不要散落硬编码字符串，后续字段命名调整只改这里，避免采集端与字段文档逐步漂移。
  */
 export declare const RUM_ATTRIBUTES: {
-    readonly actionErrorCount: "action.error.count";
-    readonly actionFrustrationCount: "action.frustration.count";
     readonly actionFrustrationType: "action.frustration.type";
     readonly actionId: "action.id";
     readonly actionLoadingTime: "action.loading_time";
-    readonly actionLongTaskCount: "action.long_task.count";
     readonly actionName: "action.name";
-    readonly actionResourceCount: "action.resource.count";
     readonly actionTargetName: "action.target.name";
     readonly actionTargetTag: "action.target.tag";
     readonly actionType: "action.type";
@@ -22,17 +18,15 @@ export declare const RUM_ATTRIBUTES: {
     readonly deviceLogicalProcessorCount: "device.logical_processor_count";
     readonly deviceMemoryGib: "device.memory_gib";
     readonly deviceType: "device.type";
+    readonly eventId: "event.id";
+    readonly eventPhase: "event.phase";
+    readonly eventTimestamp: "event.timestamp";
+    readonly eventType: "event.type";
     readonly errorType: "error_type";
-    readonly exceptionFingerprint: "exception.fingerprint";
-    readonly exceptionMessageShort: "exception.message_short";
-    readonly exceptionStackTopFrame: "exception.stack_top_frame";
     readonly longTaskBlockingDuration: "long_task.blocking_duration";
-    readonly longTaskCulprit: "long_task.culprit";
     readonly longTaskDuration: "long_task.duration";
     readonly longTaskEntryType: "long_task.entry_type";
     readonly longTaskId: "long_task.id";
-    readonly longTaskIsFrozenFrame: "long_task.is_frozen_frame";
-    readonly longTaskScriptCount: "long_task.script.count";
     readonly longTaskStartTime: "long_task.start_time";
     readonly networkEffectiveType: "network.effective_type";
     readonly nextHopProtocol: "resource.protocol";
@@ -43,7 +37,9 @@ export declare const RUM_ATTRIBUTES: {
     readonly osName: "os.name";
     readonly sessionHasReplay: "session.has_replay";
     readonly sessionId: "session.id";
+    readonly sessionSampleRate: "session.sample_rate";
     readonly sessionStartTime: "session.start_time";
+    readonly sessionType: "session.type";
     readonly spanSubtype: "span_subtype";
     readonly spanType: "span_type";
     readonly userId: "user.id";
@@ -59,7 +55,9 @@ export declare const RUM_ATTRIBUTES: {
     readonly viewLoadingTime: "view.loading_time";
     readonly viewLoadingType: "view.loading_type";
     readonly viewName: "view.name";
+    readonly viewStartedAt: "view.started_at";
     readonly viewUrl: "view.url";
     readonly viewUrlPathGroup: "view.url_path_group";
+    readonly viewVersion: "view.version";
 };
 export type RumAttributeKey = (typeof RUM_ATTRIBUTES)[keyof typeof RUM_ATTRIBUTES];

package/dist/schema/span.d.ts

@@ -14,7 +14,9 @@ export declare const RUM_SPAN_TYPE: {
     readonly longtask: "longtask";
     readonly resource: "resource";
     readonly route: "route";
+    readonly session: "session";
     readonly vital: "vital";
+    readonly websocket: "websocket";
 };
 export interface RumResourceSpanInput {
     initiatorType?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",
@@ -27,16 +27,11 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.217.0",
     "@opentelemetry/context-zone": "2.7.1",
     "@opentelemetry/core": "^2.7.1",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.217.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.217.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
     "@opentelemetry/instrumentation": "^0.217.0",
     "@opentelemetry/resources": "^2.7.1",
-    "@opentelemetry/sdk-logs": "^0.217.0",
-    "@opentelemetry/sdk-metrics": "^2.7.1",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/sdk-trace-web": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.38.0",

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

@@ -5,7 +5,7 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 
 # 蓝鲸 RUM OpenTelemetry SDK 接入助手
 
-`@blueking/open-telemetry` 是蓝鲸 RUM 的浏览器上报 SDK，基于 OpenTelemetry Web SDK，把页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话、用户动作等浏览器事件统一转成 Trace / Metric / Log 三类信号，通过 OTLP HTTP 上报到 collector。
+`@blueking/open-telemetry` 是蓝鲸 RUM 的浏览器上报 SDK，基于 OpenTelemetry Web SDK，把页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话、用户动作等浏览器事件统一转成 RUM Span，通过唯一的 OTLP HTTP Trace 通道上报到 collector。
 
 本 skill 面向**集成使用方**：帮助把 SDK 接入到自己的前端应用，包括安装、配置、按需开关采集能力、框架集成、隐私脱敏、排障和手动上报。不覆盖 SDK 源码本身的开发维护。
 
@@ -24,31 +24,29 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 | 第一次接入、安装、最小示例、CDN、生产推荐配置                                               | `references/getting-started.md`       |
 | 评估 SDK 能力边界、默认开关、浏览器 API、信号产出和降级行为                               | `references/capabilities.md`          |
 | 理解源码模块、初始化顺序、运行时上下文、过滤链路和 Hook 时机                              | `references/architecture.md`          |
-| 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文                       | `references/concepts.md`              |
+| 搞懂单一 Trace 信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文                | `references/concepts.md`              |
 | 查配置项、默认值、Endpoint、插件参数和 Hook                                                | `references/configuration.md`         |
-| 查 Transport、单信号开关、批量上报、Session 采样和 traceparent 透传                       | `references/transport-sampling.md`    |
+| 查 Transport、批量上报、Session 采样和 traceparent 透传                                   | `references/transport-sampling.md`    |
 | 了解插件默认组合、启用规则和能力分类                                                       | `references/plugins.md`               |
 | 配置 Session、Device、View、Action                                                         | `references/plugins-basic.md`         |
 | 配置 Resource、Web Vitals、Blank Screen、Long Task、View Loading Time                     | `references/plugins-experience.md`    |
 | 配置 Error、CSP Violation 和错误上报                                                       | `references/plugins-error-security.md` |
-| 配置 Fetch/XHR Request、HTTP Body、Trace Header、WebSocket                                 | `references/plugins-network.md`       |
+| 配置 Fetch/XHR Request、Trace Header、WebSocket                                            | `references/plugins-network.md`       |
 | 写自定义插件、接入第三方 OpenTelemetry instrumentation                                      | `references/custom-plugin.md`         |
 | 查公开 API（start/flush/shutdown/setUser/setView/reportAction/reportCustomEvent 等）        | `references/api.md`                   |
 | Vue / React / Vue Router / 微前端 集成                                                      | `references/framework-integration.md` |
 | URL 脱敏、属性脱敏、公共属性、低基数路由、user.id 处理                                      | `references/privacy.md`               |
 | 了解上报字段、span_type/result、哪些字段是后端派生                                          | `references/data-model.md`            |
-| 查具体的 span 名 / metric 名 / log 事件名、完整属性字典                                     | `references/telemetry-reference.md`   |
+| 查具体的 Span 名、事件字段和完整属性字典                                                    | `references/telemetry-reference.md`   |
 | 本地看不到数据、手动事件没上报、白屏误报、接口 span 太多等排障                              | `references/troubleshooting.md`       |
 
 > `references/` 由 `packages/open-telemetry/scripts/gen-skill-references.mjs` 从 SDK 的 `wikis/` 自动生成，请勿手改。如内容过期，让维护者重新执行 `pnpm --filter @blueking/open-telemetry skill:refs`。
 
 ## 核心心智模型
 
-### 三类信号
+### 单一 Trace 信号
 
-- **Trace**：有起止时间的行为——页面访问、接口请求、资源加载、用户点击、长任务。
-- **Metric**：可聚合的数值——Web Vitals、长任务数、WebSocket 消息大小、白屏结果。
-- **Log**：离散事件——错误、CSP 违规、会话生命周期、HTTP body 错误路径。
+SDK 只创建 Trace Provider。页面、请求、资源、错误、Vital、白屏和生命周期事件都编码为 RUM Span；计数、直方图、分位数、错误分组和跨事件聚合由服务端完成。
 
 ### 内置采集与扩展
 
@@ -59,11 +57,11 @@ SDK 把能力拆成两类：
 
 ### 会话级确定性采样
 
-`session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是 trace 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的 span/log/metric 决定一致。插件仍维护必要的浏览器生命周期，但未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
+`session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是单条 Span 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的所有 Span 决定一致。插件仍维护必要的浏览器生命周期，但未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
 
 ### 运行时上下文
 
-SDK 维护公共上下文并自动挂到后续 span/log 上：`user.id`（业务方提供，SDK 原样透传、不 hash 不脱敏）、`session.id`（Session 生成/轮换）、`view.*`（View 管理器维护）。Metric 只保留 `view.url_path_group` 等低基数维度，不携带唯一 `session.id` / `view.id` / `action.id`；精确关联使用对应 span 或 View Snapshot Log。运行中可用 `setUser()` 更新用户；手动 View 使用 `startView()` 划界、`setViewName()` 改名。
+SDK 维护公共上下文并自动挂到后续 Span 上：`user.id`（业务方提供，SDK 原样透传、不 hash 不脱敏）、`session.id`（Session 生成/轮换）、`view.*`（View 管理器维护）和活动窗口内的 `action.id`。运行中可用 `setUser()` 更新用户；手动 View 使用 `startView()` 划界、`setViewName()` 改名。
 
 ### 数据归一
 
@@ -95,7 +93,7 @@ CDN：
 </script>
 ```
 
-`transport.endpoint` 可提供上报根地址（不含路径前缀），SDK 自动拼 `/v1/rum`、`/v1/metrics`、`/v1/logs`；若通过 `transport.signals.{traces|metrics|logs}.endpoint` 自定义某一类地址，则该信号使用完整 URL，不再拼接。当所有已开启信号都有独立地址时，根 endpoint 可省略。三类信号可分别设为 `false` 关闭，但不能全部关闭。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
+`transport.endpoint` 是必填上报根地址（不含路径前缀），SDK 自动拼 `/v1/rum`。SDK 不创建 Metric/Log Provider，所有原始 RUM 事件统一走 Trace Span。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
 
 ## 默认采集能力清单
 
@@ -110,9 +108,9 @@ View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`csp
 - **单实例**：`fetch`/`xhr`/`action`/`websocket` 会 patch 或监听全局 API，同页面只应初始化一个 SDK 实例，微前端只在主应用初始化一次。
 - **`use()` / `useInstrumentation()` 必须在 `start()` 之前**：要注册自定义插件或 instrumentation，请设 `autoStart: false` 再手动 `start()`。
 - **采样影响手动上报**：未命中采样时 `reportAction()` / `reportCustomEvent()` 静默丢弃，排查时先确认采样。
-- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；HTTP body 默认关闭，显式配置 `request.body` 时必须提供 `redact`，默认只采集错误请求；`user.id` 需 hash 的话要在传入前处理。
+- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；SDK 不采集 HTTP Body；`user.id` 需 hash 的话要在传入前处理。
 - **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。
-- **信号开关**：`transport.signals.traces/metrics/logs` 设为 `false` 可关闭对应导出链路；关闭 Trace 后不会注入 `traceparent`。只开 Metric 时没有精确 View 下钻。
+- **单一信号**：只有 `/v1/rum` Trace 通道；计数、直方图、分位数、错误指纹和跨事件聚合由服务端完成。
 - **低基数路由**：用 `tracking.view.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。
 - **手动 View 的时机**：使用 `autoStart: false`，先 `await start()` 建立 Session，再调用 `startView()`；启动前调用会因没有有效采样 Session 而被忽略。
 - **Action 命名隐私**：默认 `nameCollection: 'explicit'` 只读取 `data-bk-action-name`，否则退回标签名；只有显式设为 `text` 才读取可访问名称和 DOM 文本。

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

@@ -13,7 +13,7 @@
       "id": 1,
       "name": "local-no-data-troubleshoot",
       "prompt": "我按文档接了 bk-rum，本地起了 collector 在 4318，但 Network 里没看到 /rum 请求，reportCustomEvent 也没上报，debug 我也开了。可能是什么问题？怎么排查？",
-      "expected_output": "排障应覆盖：session.sampleRate 是会话级确定性采样，未命中时手动事件静默丢弃（建议调试设 sampleRate:1）；enabled/Consent/有效 View 是否正常；建议 transport.signals.traces.processor:'simple'；检查 collector、endpoint 与 Network 中 /v1/rum、/v1/metrics、/v1/logs。",
+      "expected_output": "排障应覆盖：session.sampleRate 是会话级确定性采样，未命中时手动事件静默丢弃（建议调试设 sampleRate:1）；enabled/Consent/有效 View 是否正常；建议 transport.processor:'simple'；检查 collector、endpoint 与 Network 中 /v1/rum。",
       "files": [],
       "assertions": []
     },
@@ -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；HTTP body 默认关闭，显式配置 tracking.request.body 后默认只采集错误请求，必须配置 redact，并限制 Content-Type 和大小。",
+      "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。",
       "files": [],
       "assertions": []
     }

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

@@ -42,7 +42,7 @@ await bkOT.start();
 await bkOT.flush();
 ```
 
-先并行调用已启动插件的 `flush()`，再 force flush Trace、Metric、Log Provider。SDK 已在 `pagehide` 和页面变为 hidden 时触发 flush；业务只需在关键流程完成后按需主动调用。
+先并行调用已启动插件的 `flush()`，再 force flush Trace Provider。SDK 已在 `pagehide` 和页面变为 hidden 时触发 flush；业务只需在关键流程完成后按需主动调用。
 
 ### shutdown()
 
@@ -180,21 +180,9 @@ span.end();
 
 只有已采样且同时带有效 `session.id`、`view.id` 的 Span 会导出。
 
-### emitLog(record)
+### tracer
 
-```ts
-bkOT.emitLog({
-  severityText: 'INFO',
-  body: 'biz.cache_ready',
-  attributes: { 'biz.cache': 'homepage' },
-});
-```
-
-自动合并运行时上下文与脱敏。自定义插件应使用 `emitLog()`，不要直接调用 `logger.emit()`。
-
-### tracer / meter / logger
-
-实例公开 SDK 私有 Provider 对应的原生 OpenTelemetry `Tracer`、`Meter`、`Logger`。优先使用 `startSpan()` 与 `emitLog()`。当前没有公开稳定的自定义 Metric 采样 helper，直接通过 `meter` 创建的数据点默认无法通过过滤器，不应作为接入方稳定能力；详见[架构与数据流](./architecture.md#扩展边界)。
+实例公开 SDK 私有 Provider 对应的 OpenTelemetry `Tracer`。SDK 不创建或公开 `Meter`、`Logger`，自定义 RUM 事件使用 `startSpan()`。
 
 ## 扩展注册
 
@@ -219,7 +207,7 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 
 两者都必须在 `start()` 前调用；使用默认自动启动时没有可靠的动态注册窗口，推荐配置 `autoStart: false`。完整插件契约见[自定义插件](./custom-plugin.md)。
 
-额外 instrumentation 的稳定扩展边界是 Trace。第三方 Metric 不会自动获得 SDK 内部采样标记，默认无法通过 Metric 过滤器。
+额外 instrumentation 的稳定扩展边界是 Trace；SDK 不注册 Metric Provider。
 
 ## 运行时与诊断成员
 
@@ -294,7 +282,7 @@ const config = resolveConfig({
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
-console.log(config.transport.traces && config.transport.traces.endpoint);
+console.log(config.transport.endpoint);
 ```
 
 用于预览核心解析结果和测试配置。插件自己的参数默认值在插件工厂执行时解析，不会全部展开到 `ResolvedBkOTConfig`。
@@ -309,7 +297,7 @@ console.log(config.transport.traces && config.transport.traces.endpoint);
 | `createDevicePlugin` | `BkOTDevicePluginOptions` |
 | `createCommonInstrumentationsPlugin` | `BkOTRequestConfig \| boolean` |
 | `createResourcePlugin` | 直接传 `boolean`，控制是否为静态资源创建 Span；默认 `true` |
-| `createErrorPlugin` | `BkOTErrorPluginOptions` |
+| `createErrorPlugin` | 无 |
 | `createWebVitalsPlugin` | 无 |
 | `createBlankScreenPlugin` | `BkOTBlankScreenPluginOptions` |
 | `createActionPlugin` | `BkOTActionPluginOptions` |
@@ -325,7 +313,7 @@ console.log(config.transport.traces && config.transport.traces.endpoint);
 
 - `RumRuntimeContext` 及 Session/View/User 相关类型。
 - `PluginManager`。
-- `FilteringSpanProcessor`、`FilteringMetricExporter`、`FilteringLogRecordProcessor`。
+- `FilteringSpanProcessor`。
 - `EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE`，用于标记不应延长 View Loading/Action 的 DOM 子树。
 - 配置输入、解析结果、Transport、Hook、请求上下文等 TypeScript 类型。
 
@@ -340,11 +328,11 @@ console.log(config.transport.traces && config.transport.traces.endpoint);
 | 分类 | 类型 |
 | --- | --- |
 | 顶层配置 | `BkOTOptions`、`BkOTApplicationConfig`、`BkOTTransportConfig`、`BkOTTrackingConfig`、`BkOTTrackingConsent`、`BkOTContextConfig`、`BkOTPrivacyConfig`、`BkOTExtensionsConfig` |
-| Transport | `BkOTBatchConfig`、`SignalExporterConfig`、`SignalExporterInputConfig`、`SignalExportersInputConfig`、`TraceExporterInputConfig`、`MetricExporterInputConfig` |
+| Transport | `BkOTBatchConfig`、`ResolvedTransportConfig` |
 | View/Session/User | `BkOTViewConfig`、`BkOTSessionConfig`、`BkOTStartViewOptions`、`BkOTViewContext`、`BkOTSessionLifecycleEvent`、`BkOTUserContext` |
-| Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTRequestBodyConfig`、`BkOTRequestBodyRedactPayload`、`BkOTUrlMatcher` |
+| Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTUrlMatcher` |
 | 事件与 Hook | `BkOTActionEventPayload`、`BkOTCustomEventPayload`、`BkOTBeforeSendEvent`、`BkOTAttributesConfig`、`BkOTAttributeValue` |
-| 插件 | `BkOTPlugin`、`BkOTRuntimeContext`、`BkOTActionPluginOptions`、`BkOTBlankScreenPluginOptions`、`BkOTDevicePluginOptions`、`BkOTErrorPluginOptions`、`BkOTLongTaskPluginOptions` |
+| 插件 | `BkOTPlugin`、`BkOTRuntimeContext`、`BkOTActionPluginOptions`、`BkOTBlankScreenPluginOptions`、`BkOTDevicePluginOptions`、`BkOTLongTaskPluginOptions` |
 | 实例与解析结果 | `BkOTInstance`、`PluginManager`、`ResolvedBkOTConfig`、`ResolvedApplicationConfig`、`ResolvedTransportConfig`、`ResolvedViewConfig`、`ResolvedConfigHooks` |
 | Schema | `RumAttributeKey`、`RumSpanClassification`、`RumSpanType`、`RumSpanResult` |
 

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

@@ -2,140 +2,60 @@
 
 # 架构与数据流
 
-本页描述当前 `src/` 的实现边界，适合 SDK 维护者、扩展插件作者和需要解释“为什么数据没有被导出”的接入方。
+SDK 只负责采集浏览器事实和必须在浏览器本地完成的体验语义计算，所有数据统一编码为 RUM Span，通过 `<transport.endpoint>/v1/rum` 上报。
 
-## 源码模块
+## 模块边界
 
-| 目录/文件 | 职责 | 稳定入口 |
-| --- | --- | --- |
-| `src/index.ts` | ESM 公共导出边界 | npm import 只能依赖这里导出的符号 |
-| `src/browser.ts` | CDN/IIFE 入口 | 暴露 `window.BkOpenTelemetry` |
-| `src/core/config.ts` | 输入类型、校验、默认值、Endpoint 与 Hook 解析 | `BkOTOptions`、`resolveConfig()` |
-| `src/core/sdk.ts` | Provider、Exporter、生命周期、内置插件组合、公开实例 API | `BkOpenTelemetry` |
-| `src/core/runtime-context.ts` | User/Session/View/Action 属性快照与历史归属 | `RumRuntimeContext` |
-| `src/core/processor.ts` | Span/Metric/Log 的采样、上下文、自上报和 beforeSend 过滤 | 三个 Filtering 类 |
-| `src/core/plugin.ts` | 插件契约、启动、并行 flush、反向 shutdown、错误隔离 | `createPlugin()` |
-| `src/plugins/` | 浏览器采集与 RUM 语义 | 各 `create*Plugin()` |
-| `src/schema/` | 归一字段、Span 类型、结果和耗时分桶 | `RUM_ATTRIBUTES`、`buildRumSpanAttributes()` |
+| 模块 | 职责 |
+| --- | --- |
+| `core/config.ts` | 配置校验、Endpoint、Hook、Resource 属性 |
+| `core/sdk.ts` | TracerProvider、Exporter、生命周期和公开 API |
+| `core/runtime-context.ts` | User/Session/View/Action 当前快照与历史归属 |
+| `core/processor.ts` | 采样、上下文、自上报和 beforeSend 过滤 |
+| `plugins/` | 浏览器原始事件采集与本地体验语义 |
+| `schema/` | RUM 字段和 Span 分类 |
 
-文档描述与源码冲突时，以 `src/index.ts` 的公开导出和对应实现为准。`dist/` 是构建产物，不作为文档事实源。
+SDK 不创建 `MeterProvider`、`LoggerProvider`、Metric Reader 或 Log Processor。
 
-## 构造、启动与关闭
+## 生命周期
 
-### 构造阶段
+构造时只创建 Resource、TracerProvider、OTLP Trace Exporter 和运行时上下文。获得 Consent 后，插件依次建立 Session、View、请求、资源、错误、Vitals、Action 等采集。`flush()` 刷新插件和 Trace Provider；`shutdown()` 反向关闭插件并关闭 Trace Provider。
 
-`new BkOpenTelemetry(options)` 同步完成：
+## 原始事件模型
 
-1. `resolveConfig()` 校验 `application.name`、Transport 和已启用信号的 Endpoint。
-2. 创建 Resource、TracerProvider、MeterProvider、LoggerProvider。
-3. 根据三类信号开关决定是否创建 exporter、processor 或 metric reader。
-4. 创建运行时上下文；初始状态尚无 Session/View，也未命中采样。
-5. `autoStart !== false` 时异步调用 `start()`。
+公共流程：
 
-因此，需要在启动前注册扩展或立即创建手动 View 时，应显式设置 `autoStart: false`。
+1. 插件读取浏览器事件的真实时间。
+2. 按事件时间关联 `session.id`、`view.id`、`action.id`。
+3. 写入唯一 `event.id`、`event.type`、`event.timestamp`。
+4. 创建 RUM Span，应用 URL/属性脱敏。
+5. FilteringSpanProcessor 校验采样和有效上下文，执行 `tracking.beforeSend`。
+6. 通过 `/v1/rum` 批量上报。
 
-### 启动阶段
+Session 和 View 使用显式生命周期事件：
 
-`start()` 幂等。获得 Consent 且 `enabled=true` 时，插件按以下顺序初始化：
+- `browser.session`：`event.phase=start|rotate|end`。
+- `browser.view`：`event.phase=start|update|end`，并携带单调递增的 `view.version`。
+- `browser.websocket`：`event.phase=connect|open|error|close`，通过 `websocket.connection.id` 关联。
 
-1. 上下文：Session → Device → Activity → View → Resource Observer。
-2. 请求：统一 Fetch/XHR patch。
-3. RUM：Error → Web Vitals → Blank Screen → Action → 按需 WebSocket / Long Task / CSP。
-4. 接入方 `extensions.plugins`。
-5. 接入方 OpenTelemetry instrumentations。
+Session 生命周期允许只有 `session.id`；其他普通事件必须同时归属有效 Session 和 View。
 
-单个插件 `init()` 抛错不会阻断其他插件；仅在 `debug: true` 时输出 warning。Consent 撤销后再授权会重新执行插件 `init()`，插件必须在 `shutdown()` 中完整释放监听和 patch。
+## SDK 与服务端分工
 
-### flush 与 shutdown
+SDK 保留浏览器端才可靠的计算：CLS、INP、Action Loading Time、View Loading Time、挫败信号和白屏判断。
 
-- `flush()`：并行刷新插件，再 force flush Trace、Metric、Log provider。
-- `shutdown()`：反向关闭插件，结束/刷新最终数据，移除页面生命周期监听，关闭三个 provider。
-- `shutdown()` 后同一实例不能重新启动；需要重新创建实例。
-- SDK 在 `pagehide` 和页面变为 hidden 时主动调用 `flush()`。
+服务端负责：
 
-## 从浏览器事件到 OTLP
+- View/Session 时长、事件计数、错误率、吞吐量；
+- Counter、Histogram、P50/P75/P95/P99；
+- 错误指纹、分组和风暴控制；
+- 采样率修正、乱序/迟到事件合并；
+- 基于 `event.id` 去重，基于 `view.id + view.version` 幂等更新。
 
-一次事件的公共路径是：
+## 请求采集
 
-1. 插件或公开 API 观察浏览器事件。
-2. 从 `RumRuntimeContext` 读取事件发生时对应的 User、Session、View、Action 属性。
-3. 构造原生 OpenTelemetry Span、Metric datapoint 或 LogRecord。
-4. 应用 URL/属性脱敏和事件级 Hook。
-5. Filtering processor/exporter 校验采样与上下文。
-6. 通过对应 OTLP HTTP exporter 上报。
+Fetch/XHR 由 SDK 单层 patch：创建 `browser.resource` CLIENT Span、可选注入 `traceparent`、关联 Resource Timing，并通过活动总线参与 View/Action Loading Time。`excludedUrls` 完全排除请求，`request.beforeSend` 可修改或丢弃请求 Span。SDK 不读取请求或响应 Body。
 
-不同信号的最终过滤规则不同：
+## 隐私与扩展
 
-| 信号 | 接受条件 | 最终 Hook |
-| --- | --- | --- |
-| Span | 已采样，且同时有有效 `session.id`、`view.id`；排除 SDK 上报请求和请求级丢弃标记 | `tracking.beforeSend` |
-| Log | 同 Span；`session.start/rotate` 允许只有有效 Session | `tracking.beforeSend` |
-| Metric | datapoint 带内部已采样标记；导出前移除该标记 | 无全局 beforeSend |
-
-这意味着手动模式首次 `startView()` 之前，普通 Span/Log 不会导出；只创建原生 meter 数据但没有使用 SDK 采样属性的自定义 Metric 也不会导出。
-
-## 运行时上下文与历史归属
-
-运行时上下文维护当前属性，也保留有限的变更时间线。PerformanceObserver 经常在事件结束后才回调，因此 `startSpan(..., { startTime, contextTime })` 可以按事件真实发生时间解析其所属 Session/View/Action，避免把旧页面资源归到新 View。
-
-### Span 与 Log
-
-Span/Log 可携带唯一关联字段：
-
-- `user.id`
-- `session.id`
-- `view.id`、`view.name`、`view.url`、`view.url_path_group`
-- 活动期间的 `action.id`
-
-### Metric
-
-Metric 只保留 `view.url_path_group` 等低基数属性，不携带 `session.id`、`view.id`、`action.id`。需要从聚合指标下钻到具体访问时，查询同名语义 Span 或 View Snapshot Log，或由后端使用 exemplar/派生数据建立关联。
-
-## Session、采样与 Consent
-
-三者是不同控制层：
-
-| 控制层 | 决定什么 | 运行期变化 |
-| --- | --- | --- |
-| `enabled` | 实例是否启动采集 | 构造后不提供 Setter |
-| Consent | 是否安装采集副作用、创建 Session/View | `setTrackingConsent()` 可授权/撤销 |
-| `session.sampleRate` | 有效 Session 的数据是否进入导出链路 | Session 轮换后用新 ID 重新计算 |
-| Signal 开关 | 是否存在对应 exporter/processor/reader | 构造时固定 |
-
-Session 采样由 `application.name + session.id` 稳定 hash 决定，同一 Session 的三类信号保持一致。插件仍可维护页面生命周期，但未采样数据会在创建或导出路径被丢弃。
-
-## 请求采集设计
-
-Fetch/XHR 由 `createCommonInstrumentationsPlugin()` 的单一生命周期直接 patch，不叠加官方 Fetch/XHR instrumentation：
-
-- `excludedUrls` 在最前面完全排除请求。
-- 开始请求时创建 `browser.resource` CLIENT Span，并登记 View/Action 活动。
-- 只有 `allowedTracingUrls` 命中且 Trace 开启时才调用全局 propagator 注入。SDK 成功注册默认 W3C propagator 时注入 `traceparent`/已有 `tracestate`；宿主已有全局 propagator 时，实际 Header 由宿主决定。
-- Resource Observer 把同一 URL/时间窗的 PerformanceResourceTiming 匹配回请求 Span。
-- `request.beforeSend` 可修改请求事件属性或标记丢弃该 Span。
-- 配置 Body 且 Log 开启时，异步生成关联 `trace.id` / `span.id` 的 `browser.request.body` Log。
-- SDK 自身所有已启用 OTLP Endpoint 始终排除，防止递归上报。
-
-静态资源复用同一个 Resource Observer，但 Fetch/XHR entry 只用于 timing 匹配，不再创建第二条资源 Span。
-
-## 脱敏与 Hook 顺序
-
-| 入口 | 作用范围 | 适合用途 |
-| --- | --- | --- |
-| `privacy.redactUrl` | SDK 写入的 URL 类属性 | 删除 query/hash、模板化路径 |
-| `privacy.redactAttributes` | Resource、通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
-| `tracking.request.beforeSend` | 单个 Fetch/XHR，带原始 Request/Response/XHR 上下文 | 请求专属补充或丢弃 |
-| Request Body `redact` | 单个请求/响应 Body，必填 | 内容级脱敏；返回 `undefined` 跳过该 Body |
-| `tracking.beforeSend` | Span/Log 进入底层 processor 前 | 最终兜底修改或丢弃；不作用于 Metric |
-
-第三方 instrumentation 自己生成的属性不经过 SDK 的 `redactAttributes` 构造路径。若要统一约束第三方 Span，应在 `tracking.beforeSend` 中做最终清理。
-
-## 扩展边界
-
-- RUM 语义、Session/View 关联、Log 或活动总线：使用 `createPlugin()`。
-- 已有标准 OpenTelemetry instrumentation：通过 `extensions.instrumentations` 或 `useInstrumentation()` 注册。
-- 自定义 Log 使用 `context.emitLog()`，不要直接 `context.logger.emit()`，否则不会自动合并运行时上下文。
-- 自定义 Span 优先使用 `context.startSpan()`，它会应用运行时属性与脱敏。
-- 当前包没有导出稳定的自定义 Metric 采样属性/helper。直接使用 `context.meter` 创建的数据点默认无法通过 `FilteringMetricExporter`；不要依赖内部 `bk.rum.sampled` 字段，也不要把 `getRuntimeAttributes()` 中的唯一 Session/View/Action ID 整体复制到 labels。需要稳定扩展时优先使用 Span/Log，或先在 SDK 内补充公共 Metric API。
-
-完整契约与示例见[自定义插件](./custom-plugin.md)。
+`privacy.redactUrl` 处理 URL，`privacy.redactAttributes` 处理 Resource 和 SDK Span，`tracking.beforeSend` 是导出前最终兜底。自定义 RUM 插件使用 `context.startSpan()`；SDK 不提供 `meter`、`logger` 或 `emitLog()`。