@blueking/open-telemetry 0.0.14 → 0.0.16

package/dist/plugins/action.d.ts

@@ -1,6 +1,10 @@
 import type { BkOTPlugin } from '../core/plugin';
-export type BkOTActionEventName = 'click' | 'input' | 'keydown' | 'pointerdown' | 'scroll' | 'submit';
 export interface BkOTActionPluginOptions {
-    eventNames?: BkOTActionEventName[];
+    actionNameAttribute?: string;
+    maxDuration?: number;
+    /** 默认仅采集显式 data 属性；设为 text 才会读取可访问名称和 DOM 文本。 */
+    nameCollection?: 'explicit' | 'text';
 }
+export declare const getActionNameFromElement: (target: Element, actionNameAttribute?: string, includeText?: boolean) => string;
+export declare const isDeadClickExcluded: (target: Element) => boolean;
 export declare const createActionPlugin: (options?: BkOTActionPluginOptions) => BkOTPlugin;

package/dist/plugins/activity.d.ts

@@ -0,0 +1,6 @@
+import type { BkOTPlugin } from '../core/plugin';
+export declare const EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE = "data-bk-excluded-activity-mutations";
+/**
+ * 页面级 DOM 活动只观察一次，再通过运行时活动总线分发给 View、Action 和白屏检测。
+ */
+export declare const createActivityPlugin: () => BkOTPlugin;

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

@@ -1,8 +1,25 @@
 import type { BkOTPlugin } from '../core/plugin';
 export interface BkOTBlankScreenPluginOptions {
+    /** 页面活动稳定后首次检查的延迟，默认 1000ms。 */
     checkDelay?: number;
+    /** 两次空白结果之间的确认间隔，默认 200ms。 */
+    confirmationDelay?: number;
+    /** loading、骨架屏等不参与空白比例计算的元素。 */
     ignoreSelectors?: string[];
+    /** 应用挂载根节点，默认 body。根节点不存在本身会被判为候选白屏。 */
     rootSelector?: string;
+    /** 空白采样点比例阈值，默认 0.8。 */
     threshold?: number;
 }
+interface DetectionResult {
+    centerElement: string;
+    emptyCount: number;
+    ignoredCount: number;
+    reason: 'empty_viewport' | 'missing_root';
+    rootFound: boolean;
+    score: number;
+    validCount: number;
+}
+export declare const detectBlankScreen: (rootSelector: string, ignoredSelectors: string[]) => DetectionResult;
 export declare const createBlankScreenPlugin: (options?: BkOTBlankScreenPluginOptions) => BkOTPlugin;
+export {};

package/dist/plugins/common.d.ts

@@ -1,3 +1,11 @@
-import type { BkOTInstrumentationsConfig } from '../core/config';
-import type { BkOTPlugin } from '../core/plugin';
-export declare const createCommonInstrumentationsPlugin: (option?: BkOTInstrumentationsConfig) => BkOTPlugin;
+import { REQUEST_DISCARD_ATTRIBUTE } from '../core/processor';
+import type { BkOTRequestConfig, BkOTRequestContext } from '../core/config';
+import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
+import type { Span } from '@opentelemetry/api';
+interface RequestDetails {
+    method?: string;
+    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 createCommonInstrumentationsPlugin: (option: BkOTRequestConfig | boolean | undefined) => BkOTPlugin;

package/dist/plugins/device.d.ts

@@ -1,5 +1,7 @@
 import type { BkOTPlugin } from '../core/plugin';
 export interface BkOTDevicePluginOptions {
+    /** 是否跨页面持久化匿名设备 ID，默认 false。 */
+    persistentId?: boolean;
     storageKey?: string;
 }
 /**

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

@@ -1,17 +1,8 @@
 import type { BkOTPlugin } from '../core/plugin';
 export interface BkOTLongTaskPluginOptions {
+    /** 采集阈值，默认 50ms。Performance API 本身通常只产生大于 50ms 的条目。 */
     threshold?: number;
+    /** 标记 warning 的阈值，默认 100ms。 */
+    warningThreshold?: number;
 }
-/**
- * Long Task 监控插件，通过 PerformanceObserver 捕获主线程上 >= threshold（默认 50ms）的长任务，
- * 上报为 metric（counter + duration histogram），用于评估页面卡顿趋势。
- *
- * 使用建议：
- * - 默认关闭，建议在性能敏感模块按需开启。
- * - PerformanceObserver 使用 `buffered: true`，能拿到 observer 创建之前已发生的 longtask，避免漏掉早期阶段。
- *
- * 兼容性：
- * - 仅在 PerformanceObserver 与 `supportedEntryTypes` 包含 `longtask` 的浏览器上启用，否则 init 直接 return；
- *   Firefox 当前不支持 longtask，会自动跳过。
- */
 export declare const createLongTaskPlugin: (options?: BkOTLongTaskPluginOptions) => BkOTPlugin;

package/dist/plugins/page-view.d.ts

@@ -1,2 +1,3 @@
 import type { BkOTPlugin } from '../core/plugin';
+export declare const isViewLocationChange: (fromUrl: string, toUrl: string) => boolean;
 export declare const createPageViewPlugin: () => BkOTPlugin;

package/dist/plugins/request-body.d.ts

@@ -0,0 +1,14 @@
+import type { BkOTRequestBodyConfig, BkOTRequestContext, BkOTRequestEvent } from '../core/config';
+import type { BkOTRuntimeContext } from '../core/plugin';
+import type { Span } from '@opentelemetry/api';
+interface CaptureRequestBodyLogOptions {
+    bodyConfig: BkOTRequestBodyConfig;
+    domainContext: BkOTRequestContext;
+    event: BkOTRequestEvent;
+    fetchRequest?: Request | RequestInit;
+    runtimeContext: Pick<BkOTRuntimeContext, 'emitLog'>;
+    span: Span;
+}
+export declare const prepareFetchRequestBodySource: (request: Request | RequestInit) => Request | RequestInit | undefined;
+export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
+export {};

package/dist/plugins/resource.d.ts

@@ -1,2 +1,18 @@
 import type { BkOTPlugin } from '../core/plugin';
-export declare const createResourcePlugin: () => BkOTPlugin;
+type ResourceTimingWithStatus = PerformanceResourceTiming & {
+    deliveryType?: string;
+    renderBlockingStatus?: string;
+    responseStatus?: number;
+};
+export declare const getResourceTimingAttributes: (entry: ResourceTimingWithStatus) => Record<string, number>;
+export declare const getResourcePerformanceAttributes: (entry: ResourceTimingWithStatus) => {
+    'resource.encoded_body_size': number;
+    'resource.decoded_body_size': number;
+    'resource.render_blocking_status'?: string | undefined;
+    'resource.delivery_type'?: string | undefined;
+    transfer_size: number;
+    "resource.cache.hit": boolean | undefined;
+    "resource.protocol": string;
+};
+export declare const createResourcePlugin: (emitResourceSpans?: boolean) => BkOTPlugin;
+export {};

package/dist/plugins/session-state.d.ts

@@ -0,0 +1,18 @@
+export interface ActiveSessionRecord {
+    expiresAt: number;
+    id: string;
+    startedAt: number;
+    status: 'active';
+}
+export interface ExpiredSessionRecord {
+    expiredAt: number;
+    previousId: string;
+    reason: SessionExpireReason;
+    status: 'expired';
+}
+export type SessionExpireReason = 'inactivity' | 'maxLifetime';
+export type SessionRecord = ActiveSessionRecord | ExpiredSessionRecord;
+export declare const createActiveSessionRecord: (id: string, now: number, idleTimeoutMs: number, maxDurationMs: number) => ActiveSessionRecord;
+export declare const getSessionExpireReason: (record: ActiveSessionRecord, now: number, maxDurationMs: number) => SessionExpireReason | undefined;
+export declare const expandActiveSession: (record: ActiveSessionRecord, now: number, idleTimeoutMs: number, maxDurationMs: number) => ActiveSessionRecord;
+export declare const parseSessionRecord: (raw: null | string, now: number, maxDurationMs: number) => null | SessionRecord;

package/dist/plugins/session.d.ts

@@ -1,7 +1,7 @@
 import type { BkOTPlugin } from '../core/plugin';
-export interface BkOTSessionPluginOptions {
-    inactivityMs?: number;
-    maxLifetimeMs?: number;
+export interface BkOTSessionConfig {
+    /** 以 0~1 表示的 Session 采样率，默认 1。 */
+    sampleRate?: number;
     storageKey?: string;
 }
-export declare const createSessionPlugin: (options?: BkOTSessionPluginOptions) => BkOTPlugin;
+export declare const createSessionPlugin: (options?: BkOTSessionConfig) => BkOTPlugin;

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

@@ -1,2 +1,76 @@
+/**
+ * Web Vitals 插件
+ *
+ * 基于 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 详情
+ *   （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 维度区分
+ *
+ * Navigation Type：
+ *   优先使用 metric.navigationType（web-vitals 内部计算，含 'back-forward-cache' 等准确值），
+ *   fallback 到 PerformanceNavigationTiming.type（注意 web-vitals 用连字符 'back-forward'，
+ *   PerformanceNavigationTiming 用下划线 'back_forward'，统一成连字符）。
+ *
+ * View 边界：FCP/LCP/TTFB 使用 web-vitals 的条目时间回查历史 View；CLS/INP 按 SDK View 重置，
+ * CLS 使用 session window，INP 使用当前 View 的 p98 交互候选。
+ *
+ * 生命周期保护：
+ * - disposed 标志位：shutdown 后所有回调入口 early return，避免向已销毁的 provider 上报
+ * - dynamic import 完成后再次检查 disposed：处理"start() 完成前 shutdown()"的 race
+ * - dynamic import 自身 try/catch：与 PluginManager 的 per-plugin 隔离形成纵深防御，
+ *   即使加载失败也不影响整体启动
+ */
+import { type Attributes } from '@opentelemetry/api';
 import type { BkOTPlugin } from '../core/plugin';
+interface EventTimingEntry extends PerformanceEntry {
+    interactionId?: number;
+    processingEnd?: number;
+    processingStart?: number;
+    target?: EventTarget | null;
+}
+interface LayoutShiftEntry extends PerformanceEntry {
+    hadRecentInput?: boolean;
+    sources?: Array<{
+        node?: Node | null;
+    }>;
+    value?: number;
+}
+interface ViewVitalState {
+    cls: number;
+    clsWindowEnd?: number;
+    clsWindowLargestShiftTarget?: string;
+    clsWindowLargestShiftValue: number;
+    clsWindowStart?: number;
+    clsWindowValue: number;
+    interactionCountAtStart?: number;
+    interactionIdMax: number;
+    interactionIdMin: number;
+    inpCandidates: InpCandidate[];
+    largestShiftTarget?: string;
+    largestShiftValue: number;
+    runtimeAttributes: Attributes;
+    startedAt: number;
+}
+interface InpCandidate {
+    duration: number;
+    inputDelay: number;
+    interactionId: number;
+    interactionTarget?: string;
+    interactionType: string;
+    presentationDelay: number;
+    processingDuration: number;
+}
+export declare const updateViewCls: (view: ViewVitalState, entry: LayoutShiftEntry) => void;
+export declare const updateViewInp: (view: ViewVitalState, entry: EventTimingEntry) => void;
+export declare const getViewInp: (view: ViewVitalState) => InpCandidate | undefined;
 export declare const createWebVitalsPlugin: () => BkOTPlugin;
+export {};

package/dist/schema/attributes.d.ts

@@ -4,26 +4,42 @@
  * 插件里不要散落硬编码字符串，后续字段命名调整只改这里，避免采集端与字段文档逐步漂移。
  */
 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";
     readonly deploymentEnvironmentName: "deployment.environment.name";
-    readonly browserName: "browser_name";
-    readonly browserVersion: "browser_version";
-    readonly cacheHit: "cache_hit";
-    readonly deviceType: "device_type";
+    readonly browserName: "browser.name";
+    readonly browserVersion: "browser.version";
+    readonly cacheHit: "resource.cache.hit";
+    readonly deviceType: "device.type";
     readonly durationBucket: "duration_bucket";
     readonly errorType: "error_type";
     readonly eventLabel: "event_label";
     readonly exceptionFingerprint: "exception.fingerprint";
     readonly exceptionMessageShort: "exception.message_short";
     readonly exceptionStackTopFrame: "exception.stack_top_frame";
-    readonly longtaskAttributionScript: "longtask.attribution_script";
-    readonly longtaskBlockingDuration: "longtask.blocking_duration";
+    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: "next_hop_protocol";
+    readonly nextHopProtocol: "resource.protocol";
     readonly result: "result";
     readonly serviceName: "service.name";
     readonly serviceVersion: "service.version";
-    readonly osName: "os_name";
+    readonly osName: "os.name";
     readonly sessionHasReplay: "session.has_replay";
     readonly sessionId: "session.id";
     readonly sessionStartTime: "session.start_time";
@@ -33,8 +49,6 @@ export declare const RUM_ATTRIBUTES: {
     readonly targetDomain: "target_domain";
     readonly targetLabel: "target_label";
     readonly targetPathTemplate: "target_path_template";
-    readonly targetTag: "target.tag";
-    readonly targetTextShort: "target.text_short";
     readonly targetValue: "target_value";
     readonly traceScene: "trace_scene";
     readonly transferSize: "transfer_size";
@@ -42,8 +56,15 @@ export declare const RUM_ATTRIBUTES: {
     readonly vitalMetric: "vital.metric";
     readonly vitalRating: "vital.rating";
     readonly vitalValue: "vital.value";
+    readonly viewDomComplete: "view.dom_complete";
+    readonly viewDomContentLoaded: "view.dom_content_loaded";
+    readonly viewDomInteractive: "view.dom_interactive";
+    readonly viewFirstByte: "view.first_byte";
     readonly viewId: "view.id";
+    readonly viewLoadEvent: "view.load_event";
+    readonly viewLoadingTime: "view.loading_time";
     readonly viewLoadingType: "view.loading_type";
+    readonly viewName: "view.name";
     readonly viewUrl: "view.url";
     readonly viewUrlPathGroup: "view.url_path_group";
 };

package/dist/schema/span.d.ts

@@ -11,23 +11,16 @@ export declare const RUM_SPAN_TYPE: {
     readonly custom: "custom";
     readonly document: "document";
     readonly error: "error";
-    readonly http: "http";
     readonly longtask: "longtask";
     readonly resource: "resource";
     readonly route: "route";
     readonly vital: "vital";
 };
-export interface RumHttpSpanInput {
-    duration?: number;
-    method?: string;
-    statusCode?: number;
-    subtype: 'fetch' | 'xhr';
-    url?: string;
-    urlPathTemplate?: string;
-}
 export interface RumResourceSpanInput {
-    duration: number;
+    duration?: number;
     initiatorType?: string;
+    method?: string;
+    networkError?: boolean;
     responseStatus?: number;
     transferSize?: number;
     url: string;
@@ -58,5 +51,4 @@ export declare const getHttpErrorType: (statusCode: number | undefined) => "none
 export declare const getVitalResult: (rating: string | undefined) => RumSpanResult;
 export declare const getUrlTarget: (url: string | undefined, pathTemplate?: string) => RumUrlTarget;
 export declare const buildRumSpanAttributes: ({ duration, errorType, eventLabel, result, spanSubtype, spanType, targetLabel, targetValue, traceScene, }: RumSpanClassification) => Attributes;
-export declare const buildRumHttpSpanAttributes: ({ duration, method, statusCode, subtype, url, urlPathTemplate, }: RumHttpSpanInput) => Attributes;
-export declare const buildRumResourceSpanAttributes: ({ duration, initiatorType, responseStatus, transferSize, url, urlPathTemplate, }: RumResourceSpanInput) => Attributes;
+export declare const buildRumResourceSpanAttributes: ({ duration, initiatorType, method, networkError, responseStatus, transferSize, url, urlPathTemplate, }: RumResourceSpanInput) => Attributes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",
@@ -21,22 +21,18 @@
     "docs:dev": "vitepress dev wikis",
     "docs:preview": "vitepress preview wikis",
     "dev": "vite dev",
-    "dts": "vue-tsc --project tsconfig.dts.json"
+    "dts": "vue-tsc --project tsconfig.dts.json",
+    "test:rum-context": "node --experimental-default-type=module --experimental-strip-types --test tests/action-plugin.test.mjs tests/consent.test.mjs tests/experience-plugins.test.mjs tests/request-model.test.mjs tests/runtime-context.test.mjs tests/sampling.test.mjs tests/session-state.test.ts tests/session-plugin.test.mjs tests/session-page-view.test.mjs tests/session-processors.test.mjs tests/web-vitals.test.mjs"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.217.0",
-    "@opentelemetry/auto-instrumentations-web": "^0.62.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/instrumentation-document-load": "^0.62.0",
-    "@opentelemetry/instrumentation-fetch": "^0.217.0",
-    "@opentelemetry/instrumentation-user-interaction": "^0.61.0",
-    "@opentelemetry/instrumentation-xml-http-request": "^0.217.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-logs": "^0.217.0",
     "@opentelemetry/sdk-metrics": "^2.7.1",

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

@@ -11,7 +11,7 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 
 ## 怎么用本 skill
 
-1. 先读下面的「核心心智模型」，它是理解一切配置的前提，尤其是 Instrumentation 与 Plugin 在采样上的差异——这是最容易踩坑的地方。
+1. 先读下面的「核心心智模型」，它是理解入口分组、采样和信号关联的前提。
 2. 再按「任务路由」跳到对应的 `references/*.md` 拿完整细节和可复制的代码示例。不要凭记忆写配置，`references` 是权威来源。
 3. 给出配置时，默认从最小接入起步，再按用户实际诉求逐项打开能力，避免一次性堆满所有插件。
 
@@ -19,19 +19,22 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 
 根据用户诉求，读取对应参考文件（都在本 skill 的 `references/` 下）：
 
-| 用户想做的事 | 读取 |
-| --- | --- |
-| 第一次接入、安装、最小示例、CDN、生产推荐配置 | `references/getting-started.md` |
-| 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文 | `references/concepts.md` |
-| 查配置项、默认值、transport/endpoint、采样、批量上报、traceparent 透传 | `references/configuration.md` |
-| 开关某个采集能力、看插件清单和各插件参数（error/blankScreen/httpBody/longTask/websocket 等） | `references/plugins.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/duration_bucket、哪些字段是后端派生 | `references/data-model.md` |
-| 查具体的 span 名 / metric 名 / log 事件名、完整属性字典 | `references/telemetry-reference.md` |
-| 本地看不到数据、手动事件没上报、白屏误报、接口 span 太多等排障 | `references/troubleshooting.md` |
+| 用户想做的事                                                                                | 读取                                  |
+| ------------------------------------------------------------------------------------------- | ------------------------------------- |
+| 第一次接入、安装、最小示例、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`    |
+| 开关某个采集能力、看请求配置和各插件参数（request/error/blankScreen/longTask/websocket 等） | `references/plugins.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/duration_bucket、哪些字段是后端派生                          | `references/data-model.md`            |
+| 查具体的 span 名 / metric 名 / log 事件名、完整属性字典                                     | `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`。
 
@@ -43,24 +46,24 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 - **Metric**：可聚合的数值——Web Vitals、长任务数、WebSocket 消息大小、白屏结果。
 - **Log**：离散事件——错误、CSP 违规、会话生命周期、HTTP body 错误路径。
 
-### Instrumentation 与 Plugin（最关键区别）
+### 内置采集与扩展
 
-SDK 把采集能力拆成两类，配置分别挂在顶层 `instrumentations` 和 `plugins` 下：
+SDK 把能力拆成两类：
 
-- **Instrumentation**：OpenTelemetry 官方探针（`documentLoad`、`fetch`、`xhr`、`userInteraction`），负责 patch 浏览器原生 API。**只要 `enabled !== false` 就装载，不受采样影响。**
-- **Plugin**：bk-ot 自研的 RUM 能力单元（`pageView`、`resource`、`error`、`webVitals` 等），基于运行时上下文主动产生 RUM 归一数据。**产生 RUM 数据的插件只在会话命中采样时才启动。**
+- **内置采集**：统一放在 `tracking`，包括 View、请求、资源、错误、Web Vitals、Action 等；其中 Fetch/XHR 由 SDK 自有的单一请求生命周期直接 patch，统一创建 `browser.resource` CLIENT Span。
+- **扩展**：接入方的 RUM 插件放在 `extensions.plugins`，标准 OpenTelemetry instrumentation 放在 `extensions.instrumentations`。它们都使用 SDK 私有 provider，并遵循 Consent 生命周期。
 
-### 会话级 sticky 采样
+### 会话级确定性采样
 
-`sampling.rate`（0–1，默认 1）是**会话级** sticky 采样，不是 trace 级。一次会话命中后 RUM 插件和手动事件都会上报；未命中时主动产生数据的插件不启动，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `rate: 1` 和 `debug: true`。
+`session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是 trace 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的 span/log/metric 决定一致。插件仍维护必要的浏览器生命周期，但未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
 
 ### 运行时上下文
 
-SDK 维护公共上下文并自动挂到后续 span/log/metric 上：`user.id`（业务方提供，SDK 原样透传、不 hash 不脱敏）、`session.id`（session 插件生成/轮换）、`view.*`（pageView 插件维护）。运行中可用 `setUser()` / `setView()` 更新。
+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 补充归一字段便于统一检索：`span_type`（document/http/resource/vital/error/longtask/action/route/custom）、`result`（success/warning/error/timeout/abort）、`duration_bucket`、`target_label` 等。
+SDK 为 span 补充归一字段便于统一检索：`span_type`（document/resource/vital/error/longtask/action/route/custom）、`result`（success/warning/error/timeout/abort）、`duration_bucket`、`target_label` 等。Fetch/XHR 与静态资源统一为 resource，通过 `resource.type` 区分。
 
 ## 最小接入速查
 
@@ -70,9 +73,9 @@ npm：
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  app: { name: 'demo-app', environment: 'production', version: '1.0.0' },
+  application: { name: 'demo-app', environment: 'production', version: '1.0.0' },
   transport: { endpoint: 'https://your-otlp-collector', token: 'your-report-token' },
-  user: { id: window.USER_ID },
+  context: { user: { id: window.USER_ID } },
 });
 ```
 
@@ -82,27 +85,30 @@ CDN：
 <script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
 <script>
   new window.BkOpenTelemetry({
-    app: { name: 'demo-app', environment: 'production' },
+    application: { name: 'demo-app', environment: 'production' },
     transport: { endpoint: 'https://your-otlp-collector', token: 'your-report-token' },
   });
 </script>
 ```
 
-`transport.endpoint` 填上报根地址（不含路径前缀），SDK 自动拼 `/v1/rum`、`/v1/metrics`、`/v1/logs`；若通过 `transport.signals.endpoints` 或单信号 `endpoint` 自定义了某一类地址，则该信号使用自定义 URL，不再拼接。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
+`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()`。
 
 ## 默认采集能力清单
 
-只配 `app` + `transport` 即默认开启：
+只配 `application` + `transport` 即默认开启：
 
-- Instrumentation：`documentLoad`、`fetch`、`xhr`、`userInteraction`
-- Plugin：`pageView`、`resource`、`error`、`webVitals`、`blankScreen`、`device`、`session`
+- 基础能力：Session、View；内置采集：`request`、`action`、`resource`、`error`、`webVitals`、`blankScreen`、`device`
 
-默认关闭、按需打开：`action`、`httpBody`、`longTask`、`routeTiming`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数见 `references/plugins.md`。
+View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数见 `references/plugins.md`。
 
 ## 关键易错点
 
-- **单实例**：`fetch`/`xhr`/`userInteraction`/`websocket` 会 patch 全局 API，同页面只应初始化一个 SDK 实例，微前端只在主应用初始化一次。
+- **单实例**：`fetch`/`xhr`/`action`/`websocket` 会 patch 或监听全局 API，同页面只应初始化一个 SDK 实例，微前端只在主应用初始化一次。
 - **`use()` / `useInstrumentation()` 必须在 `start()` 之前**：要注册自定义插件或 instrumentation，请设 `autoStart: false` 再手动 `start()`。
 - **采样影响手动上报**：未命中采样时 `reportAction()` / `reportCustomEvent()` 静默丢弃，排查时先确认采样。
-- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性、HTTP body 脱敏都需通过 `privacy` / `httpBody.redact` 显式处理；`user.id` 需 hash 的话要在传入前处理。
-- **低基数路由**：用 `route.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。
+- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；HTTP body 默认关闭，显式配置 `request.body` 时必须提供 `redact`，默认只采集错误请求；`user.id` 需 hash 的话要在传入前处理。
+- **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。
+- **信号开关**：`transport.signals.traces/metrics/logs` 设为 `false` 可关闭对应导出链路；关闭 Trace 后不会注入 `traceparent`。只开 Metric 时没有精确 View 下钻。
+- **低基数路由**：用 `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

@@ -5,7 +5,7 @@
       "id": 0,
       "name": "vue3-integration",
       "prompt": "我们是一个 Vue3 + vue-router 的后台管理系统，想接入蓝鲸 RUM 做前端监控。collector 地址是 https://rum.example.com，token 放在 window.__RUM_TOKEN__。帮我写接入代码：要能追踪 SPA 路由切换、检测白屏（挂载点 #app），生产环境按 20% 采样，并且把 URL 里的 token 参数脱敏。",
-      "expected_output": "给出使用 @blueking/open-telemetry 的 BkOpenTelemetry 接入代码：app/transport(endpoint+token)、sampling.rate=0.2、blankScreen.rootSelector='#app'、privacy.redactUrl 脱敏 token、通过 route.getPathGroup 或 vue-router afterEach + setView 追踪 SPA 路由。API/配置项名称需与 SDK 实际一致。",
+      "expected_output": "给出使用 @blueking/open-telemetry 的 BkOpenTelemetry 接入代码：application/transport(endpoint+token)、session.sampleRate=0.2、tracking.blankScreen.rootSelector='#app'、privacy.redactUrl 脱敏 token、通过 tracking.view.getPathGroup 自动追踪或 manual + await start() + startView() 对接 vue-router。API/配置项名称需与 SDK 实际一致。",
       "files": [],
       "assertions": []
     },
@@ -13,7 +13,7 @@
       "id": 1,
       "name": "local-no-data-troubleshoot",
       "prompt": "我按文档接了 bk-rum，本地起了 collector 在 4318，但 Network 里没看到 /rum 请求，reportCustomEvent 也没上报，debug 我也开了。可能是什么问题？怎么排查？",
-      "expected_output": "排障应覆盖：sampling.rate 是会话级 sticky 采样、未命中时插件不启动且手动事件静默丢弃(建议调试设 rate:1)；enabled 是否为 false；建议 spanProcessor:'simple' 便于本地看数据；检查 collector 是否监听 4318、endpoint 是否正确。",
+      "expected_output": "排障应覆盖：session.sampleRate 是会话级确定性采样，未命中时手动事件静默丢弃（建议调试设 sampleRate:1）；enabled/Consent/有效 View 是否正常；建议 transport.signals.traces.processor:'simple'；检查 collector、endpoint 与 Network 中 /v1/rum、/v1/metrics、/v1/logs。",
       "files": [],
       "assertions": []
     },
@@ -21,7 +21,7 @@
       "id": 2,
       "name": "instrumentation-vs-plugin-httpbody",
       "prompt": "配置里有 instrumentations 和 plugins 两块，fetch、error 这些好像两边都能配？它们到底有什么区别？另外我想采集接口报错时的请求/响应 body 来排查问题，该怎么配、要注意什么？",
-      "expected_output": "正确区分 Instrumentation(官方探针，patch 原生 API，不受采样影响)与 Plugin(自研 RUM 数据，受会话级采样影响)；指出 fetch/xhr 属 instrumentations、error 属 plugins；httpBody 默认关闭、只在错误路径(>=400/抛错)采集 body，需配 maxBodySize 与 redact 脱敏，提醒敏感信息处理。",
+      "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 和大小。",
       "files": [],
       "assertions": []
     }