@blueking/open-telemetry 0.0.22-beta.1 → 0.0.23

package/dist/plugins/blank-screen.d.ts

@@ -10,7 +10,7 @@ export interface BkOTBlankScreenPluginOptions {
     confirmationDelay?: number;
     /** loading、骨架屏等不参与空白比例计算的元素。 */
     ignoreSelectors?: string[];
-    /** 应用挂载根节点，默认 body。根节点不存在本身会被判为候选白屏。 */
+    /** 应用挂载根节点，默认 body。根节点不存在时回退到 body 检测。 */
     rootSelector?: string;
     /** 空白采样点比例阈值，默认 0.8。 */
     threshold?: number;

package/dist/plugins/common.d.ts

@@ -1,5 +1,5 @@
 import { REQUEST_DISCARD_ATTRIBUTE } from '../core/processor';
-import type { BkOTRequestConfig, BkOTRequestContext } from '../core/config';
+import type { BkOTRequestConfig, BkOTRequestContext, BkOTRequestOutcome } from '../core/config';
 import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
 import type { Span } from '@opentelemetry/api';
 interface RequestDetails {
@@ -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) => void;
+export declare const decorateRequestSpan: (context: BkOTRuntimeContext, span: Span, subtype: "fetch" | "xhr", domainContext: BkOTRequestContext, outcome: BkOTRequestOutcome, details?: RequestDetails) => void;
 export declare const createCommonInstrumentationsPlugin: (option: BkOTRequestConfig | boolean | undefined) => BkOTPlugin;

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

@@ -8,9 +8,7 @@
  *   （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

@@ -18,11 +18,6 @@ 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 longTaskBlockingDuration: "long_task.blocking_duration";
     readonly longTaskDuration: "long_task.duration";
     readonly longTaskEntryType: "long_task.entry_type";
@@ -30,7 +25,8 @@ export declare const RUM_ATTRIBUTES: {
     readonly longTaskStartTime: "long_task.start_time";
     readonly networkEffectiveType: "network.effective_type";
     readonly nextHopProtocol: "resource.protocol";
-    readonly result: "result";
+    readonly outcomeReason: "outcome.reason";
+    readonly outcomeType: "outcome.type";
     readonly rumSchemaVersion: "rum.schema.version";
     readonly serviceName: "service.name";
     readonly serviceVersion: "service.version";
@@ -38,9 +34,9 @@ export declare const RUM_ATTRIBUTES: {
     readonly sessionHasReplay: "session.has_replay";
     readonly sessionId: "session.id";
     readonly sessionSampleRate: "session.sample_rate";
+    readonly sessionPhase: "session.phase";
     readonly sessionStartTime: "session.start_time";
     readonly sessionType: "session.type";
-    readonly spanSubtype: "span_subtype";
     readonly spanType: "span_type";
     readonly userId: "user.id";
     readonly vitalMetric: "vital.metric";
@@ -55,9 +51,12 @@ export declare const RUM_ATTRIBUTES: {
     readonly viewLoadingTime: "view.loading_time";
     readonly viewLoadingType: "view.loading_type";
     readonly viewName: "view.name";
+    readonly viewPhase: "view.phase";
+    readonly viewSource: "view.source";
     readonly viewStartedAt: "view.started_at";
     readonly viewUrl: "view.url";
     readonly viewUrlPathGroup: "view.url_path_group";
     readonly viewVersion: "view.version";
+    readonly websocketPhase: "websocket.phase";
 };
 export type RumAttributeKey = (typeof RUM_ATTRIBUTES)[keyof typeof RUM_ATTRIBUTES];

package/dist/schema/span.d.ts

@@ -1,5 +1,5 @@
 import type { Attributes } from '@opentelemetry/api';
-export declare const RUM_SPAN_RESULT: {
+export declare const RUM_SPAN_OUTCOME: {
     readonly abort: "abort";
     readonly error: "error";
     readonly success: "success";
@@ -9,38 +9,47 @@ export declare const RUM_SPAN_RESULT: {
 export declare const RUM_SPAN_TYPE: {
     readonly action: "action";
     readonly custom: "custom";
-    readonly document: "document";
     readonly error: "error";
-    readonly longtask: "longtask";
+    readonly longTask: "long_task";
     readonly resource: "resource";
-    readonly route: "route";
     readonly session: "session";
     readonly vital: "vital";
+    readonly view: "view";
     readonly websocket: "websocket";
 };
+export type RumRequestOutcome = {
+    error?: unknown;
+    type: 'network_error';
+} | {
+    error?: unknown;
+    type: 'timeout';
+} | {
+    statusCode?: number;
+    type: 'response';
+} | {
+    type: 'abort';
+};
 export interface RumResourceSpanInput {
     initiatorType?: string;
     method?: string;
-    networkError?: boolean;
-    responseStatus?: number;
+    outcome?: RumRequestOutcome;
     transferSize?: number;
     url: string;
 }
 export interface RumSpanClassification {
-    errorType?: string;
-    result?: RumSpanResult;
-    spanSubtype: string;
+    outcome?: RumSpanOutcome;
+    outcomeReason?: string;
     spanType: RumSpanType;
 }
-export type RumSpanResult = (typeof RUM_SPAN_RESULT)[keyof typeof RUM_SPAN_RESULT];
+export type RumSpanOutcome = (typeof RUM_SPAN_OUTCOME)[keyof typeof RUM_SPAN_OUTCOME];
 export type RumSpanType = (typeof RUM_SPAN_TYPE)[keyof typeof RUM_SPAN_TYPE];
 export interface RumUrlTarget {
     serverAddress?: string;
     serverPort?: number;
 }
-export declare const getHttpResult: (statusCode: number | undefined) => RumSpanResult;
-export declare const getHttpErrorType: (statusCode: number | undefined) => "none" | "network_timeout" | "http_5xx" | "http_4xx";
-export declare const getVitalResult: (rating: string | undefined) => RumSpanResult;
+export declare const getHttpOutcome: (statusCode: number | undefined) => RumSpanOutcome;
+export declare const getHttpOutcomeReason: (statusCode: number | undefined) => "network_timeout" | "http_5xx" | "http_4xx" | undefined;
+export declare const getVitalOutcome: (rating: string | undefined) => RumSpanOutcome;
 export declare const getUrlTarget: (url: string | undefined) => RumUrlTarget;
-export declare const buildRumSpanAttributes: ({ errorType, result, spanSubtype, spanType, }: RumSpanClassification) => Attributes;
-export declare const buildRumResourceSpanAttributes: ({ initiatorType, method, networkError, responseStatus, transferSize, url, }: RumResourceSpanInput) => Attributes;
+export declare const buildRumSpanAttributes: ({ outcome, outcomeReason, spanType, }: RumSpanClassification) => Attributes;
+export declare const buildRumResourceSpanAttributes: ({ initiatorType, method, outcome, transferSize, url, }: RumResourceSpanInput) => Attributes;

package/package.json

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

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 源码本身的开发维护。
 
@@ -21,34 +21,34 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 
 | 用户想做的事                                                                                | 读取                                  |
 | ------------------------------------------------------------------------------------------- | ------------------------------------- |
-| 第一次接入、安装、最小示例、CDN、生产推荐配置                                               | `references/getting-started.md`       |
-| 评估 SDK 能力边界、默认开关、浏览器 API、信号产出和降级行为                               | `references/capabilities.md`          |
-| 理解源码模块、初始化顺序、运行时上下文、过滤链路和 Hook 时机                              | `references/architecture.md`          |
-| 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文                       | `references/concepts.md`              |
-| 查配置项、默认值、Endpoint、插件参数和 Hook                                                | `references/configuration.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`       |
-| 写自定义插件、接入第三方 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/troubleshooting.md`       |
+| 第一次接入、安装、最小示例、CDN、第一次数据验证                                             | `references/getting-started.md`       |
+| 生产上线、采样容量、Collector/CORS、灰度与验收                                              | `references/production.md`            |
+| 评估 SDK 能力边界、默认开关、浏览器 API、信号产出和降级行为                                 | `references/capabilities.md`          |
+| 理解源码模块、初始化顺序、运行时上下文、过滤链路和 Hook 时机                                | `references/architecture.md`          |
+| 理解 OTLP 层级、Session/View/Action 关联、字段归属和服务端派生                              | `references/data-model.md`            |
+| 配置 Session、用户、Device、持久化和跨 Tab                                                  | `references/session-context.md`       |
+| 配置自动/手动 View、Router、BFCache 和 View Loading Time                                    | `references/views-routing.md`         |
+| 配置 Fetch/XHR、Resource Timing、Trace Header 和 WebSocket                                  | `references/network.md`               |
+| 配置自动 Action、手动 Action、命名和 Rage/Dead/Error Click                                  | `references/actions.md`               |
+| 配置 Web Vitals、Long Task 及其浏览器降级                                                   | `references/performance.md`           |
+| 配置 JS/Promise/资源错误、exception 和 CSP Violation                                        | `references/errors-security.md`       |
+| 配置白屏根节点、阈值、忽略元素和处理误报                                                    | `references/blank-screen.md`          |
+| 写自定义 BkOTPlugin、接入第三方 OpenTelemetry Instrumentation                               | `references/extensions.md`            |
+| 查全部配置项、默认值、Endpoint、插件参数和 Hook                                              | `references/configuration.md`         |
+| 查公开 API（start/flush/shutdown/setUser/startView/reportAction/reportCustomEvent 等）      | `references/api.md`                   |
+| Vue / React / Router / SSR / 微前端集成                                                     | `references/framework-integration.md` |
+| URL/属性脱敏、Consent、低基数路由、user.id 和服务端隐私责任                                  | `references/privacy.md`               |
+| 查 Transport、OTLP JSON、批量队列、重试、keepalive、Session 采样和 CORS                    | `references/transport-sampling.md`    |
+| 查具体 Span 名、OTLP Envelope、Resource/Span/Event 完整字段字典                             | `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,15 +59,15 @@ 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()` 改名。
 
 ### 数据归一
 
-SDK 为 span 补充归一字段便于统一检索：`span_type`（document/resource/vital/error/longtask/action/route/custom）、`span_subtype`、`result`（success/warning/error/timeout/abort）、`error_type`。Fetch/XHR 与静态资源统一为 resource，通过 `resource.type` 区分。
+SDK 为 Span 补充归一字段便于统一检索：`span_type`（session/view/resource/vital/error/long_task/action/websocket/custom）、`outcome.type`（success/warning/error/timeout/abort）和可选 `outcome.reason`。具体子类由 `resource.type`、`vital.metric`、`error.source` 等领域字段表达；Fetch/XHR 与静态资源统一为 resource，通过 `resource.type` 区分。
 
 ## 最小接入速查
 
@@ -95,7 +95,7 @@ CDN：
 </script>
 ```
 
-`transport.endpoint` 是必填上报根地址（不含路径前缀），SDK 自动拼 `/v1/rum`。SDK 不创建 Metric/Log Provider，所有原始 RUM 事件统一走 Trace Span。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
+`transport.endpoint` 是必填上报根地址，可以包含网关前缀，但不要包含最终 `/v1/rum`；SDK 去除末尾斜杠后自动追加 `/v1/rum`。SDK 不创建 Metric/Log Provider，所有原始 RUM 事件统一走 Trace Span。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 异步启动；如果要确保首个手动事件不丢，应改用 `autoStart: false` 并显式 `await start()`。
 
 ## 默认采集能力清单
 
@@ -103,15 +103,16 @@ CDN：
 
 - 基础能力：Session、View；内置采集：`request`、`action`、`resource`、`error`、`webVitals`、`blankScreen`、`device`
 
-View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数按「任务路由」读取对应 `plugins-*.md`。
+View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各能力参数按「任务路由」读取对应主题 reference。
 
 ## 关键易错点
 
 - **单实例**：`fetch`/`xhr`/`action`/`websocket` 会 patch 或监听全局 API，同页面只应初始化一个 SDK 实例，微前端只在主应用初始化一次。
 - **`use()` / `useInstrumentation()` 必须在 `start()` 之前**：要注册自定义插件或 instrumentation，请设 `autoStart: false` 再手动 `start()`。
 - **采样影响手动上报**：未命中采样时 `reportAction()` / `reportCustomEvent()` 静默丢弃，排查时先确认采样。
-- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；SDK 不采集 HTTP Body；`user.id` 需 hash 的话要在传入前处理。
-- **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。
+- **手动事件不排队**：异步 autoStart 尚未建立 View 时立即调用的手动事件可能被过滤；确定性时序使用 `autoStart: false`、`await start()`，manual View 再先调用 `startView()`。
+- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；SDK 不采集 HTTP Body；`user.id` 需 hash 的话要在传入前处理。`tracking.beforeSend` 新写入的字段不会再次自动经过 `redactAttributes`。
+- **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。该配置不会阻止构造阶段读取 Device Resource 快照；要求授权前零读取时必须延迟构造 SDK。
 - **单一信号**：只有 `/v1/rum` Trace 通道；计数、直方图、分位数、错误指纹和跨事件聚合由服务端完成。
 - **低基数路由**：用 `tracking.view.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。
 - **手动 View 的时机**：使用 `autoStart: false`，先 `await start()` 建立 Session，再调用 `startView()`；启动前调用会因没有有效采样 Session 而被忽略。

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

@@ -0,0 +1,166 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 用户 Action 与挫败信号
+
+Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认自动监听 click，也提供 `reportAction()` 上报业务命名动作。自动 Action 才计算 Loading Time、页面活动和挫败信号。
+
+## 自动 Action 生命周期
+
+一次 click 的处理过程：
+
+1. 从 Event 取得真实发生时间和 composed target。
+2. 生成 `action.id`，保存当时的 Session/View 上下文。
+3. 把活动中的 Action ID 写入运行时上下文，后续请求、资源、错误和 Long Task 自动关联。
+4. 观察请求、DOM Mutation、Resource、Long Task、Error 和部分用户行为。
+5. 发生过页面活动后，等待所有请求完成并连续 100ms 无活动。
+6. 最长等待 `maxDuration`，默认 10 秒。
+7. 从运行时上下文移除 Action ID。
+8. 最多再等待到 click 后 1 秒完成 Rage Click 判断。
+9. 创建并结束 `action.click` Span。
+
+上报等待期不会延长 Action 关联窗口；后续无关事件不会因为等待 Rage Click 判断而关联旧 Action。
+
+## Action 活动
+
+会影响 Loading Time 的活动：
+
+- Fetch/XHR 开始和结束；
+- 静态资源完成；
+- DOM Mutation；
+- Long Task；
+- Error；
+- `window.open`。
+
+Error 会把 Action 标记为发生过活动、更新结束时间并标记 `error_click`；Long Task 也只影响 Action Activity。View Loading Time 的稳定判断会忽略 Error 和 Long Task。`view.excludedActivityUrls` 命中的请求/资源不参与 Action 活动。
+
+点击后 100ms 内没有任何页面活动时，Action 以零持续时间结束且没有 `action.loading_time`；它仍可能被识别为 Dead Click。
+
+## 自动命名
+
+默认配置：
+
+```ts
+tracking: {
+  action: {
+    actionNameAttribute: 'data-bk-action-name',
+    maxDuration: 10_000,
+    nameCollection: 'explicit',
+  },
+}
+```
+
+`explicit` 模式从目标元素向上查找指定属性；找不到时只使用目标标签名。推荐：
+
+```html
+<button data-bk-action-name="提交订单">提交</button>
+```
+
+遥测中的名称为 `Click on 提交订单`，同时写入：
+
+- `action.target.name=提交订单`
+- `action.target.tag=button`
+
+名称会合并连续空白、截断到 100 字符。
+
+## 文本命名模式
+
+`nameCollection='text'` 才会继续读取：
+
+1. 关联 label；
+2. button/reset/submit input value；
+3. button、label、`role=button` 文本；
+4. `aria-label`、`alt`、`name`、`title`、`placeholder`；
+5. DOM textContent；
+6. 从目标开始，最多继续检查 10 层父级；遇到 form/body/html/head 停止。
+
+该模式可能采集用户输入、订单内容或个人信息。生产环境优先使用 `explicit`，只有完成隐私评估后才启用文本模式。
+
+## Rage Click
+
+满足以下条件时标记 `rage_click`：
+
+- 1 秒内至少三次 click；
+- 点击目标是同一个 DOM Element；
+- 相邻点击坐标距离不超过 100px；
+- 期间没有 scroll 或 selectionchange 中断点击链。
+
+前三次点击仍各自保留独立 Action Span，并带 Rage Click 语义，不合并成一条事件。
+
+## Dead Click
+
+点击后没有页面活动，且没有 input、scroll 或文本选择时，候选为 `dead_click`。以下目标因行为难以可靠判断而排除：
+
+- 带 href 的链接；
+- `select`、`textarea`、`canvas`；
+- `contenteditable`；
+- 文本类 input；
+- 指向以上控件的 label。
+
+button、checkbox、radio、range、reset、submit input 仍可判断。
+
+## Error Click
+
+Action 活动窗口内发生由 Activity Bus 通知的前端错误时，标记 `error_click`。Error 不要求是 Action Span 的子 Span，只要事件时间落在活动窗口并带同一 `action.id` 即可在服务端关联。
+
+## Outcome 与字段
+
+自动 Action Span：
+
+| 条件 | `outcome.type` | 具体语义 |
+| --- | --- | --- |
+| 无错误、无挫败 | `success` | 无 |
+| 有前端错误 | `warning` | `action.frustration.type=error_click` |
+| 只有 Rage/Dead Click | `warning` | `action.frustration.type` 对应值 |
+
+关键字段：
+
+- `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` 固定顺序的数组
+
+SDK 不在 Action Span 中写请求数、资源数、错误数或 Long Task 数；服务端通过 `action.id` 关联原始事件后派生。
+
+## 手动 Action
+
+```ts
+bkOT.reportAction({
+  name: '立即支付',
+  attributes: {
+    'biz.order_type': 'normal',
+  },
+});
+```
+
+它立即创建并结束 `action.custom`：
+
+- 新生成独立 `action.id`；
+- `action.type=custom`；
+- `action.name` 使用传入名称；
+- `span_type=action`、`outcome.type=success`；
+- 不建立活动窗口；
+- 不计算 Loading Time 或挫败信号；
+- 不把该 ID挂到后续请求/错误。
+
+未采样、未授权或没有有效 View 时不会导出。`reportAction()` 未采样时静默返回。
+
+## Flush 与页面退出
+
+页面隐藏、pagehide、Session 过期、插件 flush 或 shutdown 时，SDK会结束仍活动的 Action，并立即落数等待中的 Rage Click Action，避免正常生命周期中积压。
+
+## 常见问题
+
+### Action 名称只有标签名
+
+这是默认隐私行为。为元素或祖先添加 `data-bk-action-name`，或显式配置其他 `actionNameAttribute`。
+
+### 点击有请求但没有 Loading Time
+
+检查请求是否命中 `view.excludedActivityUrls`，click 是否在请求开始前被其他监听逻辑延迟，以及 Action 是否在未采样/无 View 状态发生。
+
+### Dead Click 过多
+
+确认自定义控件是否由普通 `div` 实现但实际承担输入/跳转行为；可让点击产生可观察活动、改用语义化元素，或关闭自动 Action 并使用手动上报。当前配置没有单独关闭某一种挫败信号的选项。