@blueking/open-telemetry 0.0.33 → 0.0.35-beta.1

package/dist/core/action-activity.d.ts

@@ -18,8 +18,12 @@ export type BkOTActivityEvent = {
     type: 'request_start';
     url?: string;
 } | {
+    actionIds: string[];
     time: number;
-    type: 'dom_mutation' | 'error' | 'window_open';
+    type: 'error';
+} | {
+    time: number;
+    type: 'dom_mutation' | 'window_open';
 };
 export declare class RumActivityObserver {
     private readonly listeners;

package/dist/core/action-target.d.ts

@@ -0,0 +1,19 @@
+export interface ActionTargetOptions {
+    actionNameAttribute?: string;
+    nameCollection?: 'explicit' | 'text';
+}
+export interface ActionTargetSnapshot {
+    name: string;
+    nameSource: 'explicit' | 'accessible_name' | 'text' | 'fallback';
+    tag: string;
+    /** ::shadow 分隔各自根节点内唯一的 selector；它不是标准 CSS 组合符。 */
+    selector?: string;
+    path?: string[];
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+}
+/** 隐藏/隐私目标返回 undefined，调用方应跳过整个自动 Action。 */
+export declare const captureActionTarget: (target: Element, event: Event, options?: ActionTargetOptions) => ActionTargetSnapshot | undefined;
+export declare const getActionNameFromElement: (target: Element, actionNameAttribute?: string, includeText?: boolean) => string;

package/dist/core/config.d.ts

@@ -6,8 +6,10 @@ import type { BkOTSessionConfig } from '../plugins/session';
 import type { RumRequestOutcome } from '../schema/span';
 import type { BkOTPlugin } from './plugin';
 import type { BkOTUserContext } from './runtime-context';
-import type { Attributes } from '@opentelemetry/api';
+import type { BkOTViewRouteMode } from './view-location';
+import type { Attributes, Link } from '@opentelemetry/api';
 import type { Instrumentation } from '@opentelemetry/instrumentation';
+import type { TimedEvent } from '@opentelemetry/sdk-trace-base';
 export interface BkOTActionEventPayload {
     attributes?: Attributes;
     name: string;
@@ -31,6 +33,9 @@ export interface BkOTBatchConfig {
 }
 export interface BkOTBeforeSendEvent {
     attributes: Record<string, unknown>;
+    /** 脱敏后的导出副本，可原地修改或移除；不改变已结束的原 Span。 */
+    events?: TimedEvent[];
+    links?: Link[];
     name: string;
     signal: 'span';
 }
@@ -62,7 +67,7 @@ export interface BkOTOptions {
 export interface BkOTPrivacyConfig {
     /** 初始化时的采集授权状态；运行期可通过 setTrackingConsent 更新。 */
     trackingConsent?: BkOTTrackingConsent;
-    /** 在所有 RUM 自定义插件 emit 前统一过滤属性。 */
+    /** 过滤 Span、Event、Link 属性；导出前再次执行，应保持幂等。抛错时丢弃该条遥测。 */
     redactAttributes?: (attributes: Attributes) => Attributes;
     /** 所有写入 attribute 的 URL 都会先经过此函数。 */
     redactUrl?: (url: string) => string;
@@ -75,13 +80,15 @@ export interface BkOTRequestConfig {
     getUrlTemplate?: (url: string) => string | undefined;
 }
 export type BkOTRequestContext = {
+    /** 本次 send 的终态快照；xhr 原实例可能已被业务复用，不保存正文。 */
+    responseSnapshot?: Readonly<Pick<XMLHttpRequest, 'responseType' | 'responseURL' | 'status' | 'statusText'>>;
+    type: 'xhr';
+    xhr: XMLHttpRequest;
+} | {
     error?: unknown;
     request: Request | RequestInit;
     response?: Response;
     type: 'fetch';
-} | {
-    type: 'xhr';
-    xhr: XMLHttpRequest;
 };
 export interface BkOTRequestEvent {
     attributes: Attributes;
@@ -125,6 +132,8 @@ export interface BkOTViewConfig {
     excludedActivityUrls?: BkOTUrlMatcher | BkOTUrlMatcher[];
     /** 自动计算初始加载与 SPA 路由的页面稳定耗时，默认开启。 */
     loadingTime?: boolean;
+    /** auto 识别 #/ 与 #!/；history 忽略片段，hash 使用片段内路径，document 不自动划分同文档 View。 */
+    routeMode?: BkOTViewRouteMode;
     tracking?: 'auto' | 'manual';
     /** 返回页面路由的低基数模板，例如 `/trace/:id`；返回空值时回退到默认折叠规则。 */
     getUrlTemplate?: (url: string) => string | undefined;
@@ -173,6 +182,7 @@ export interface ResolvedTransportConfig {
 export interface ResolvedViewConfig {
     excludedActivityUrls?: BkOTUrlMatcher | BkOTUrlMatcher[];
     loadingTime: boolean;
+    routeMode: BkOTViewRouteMode;
     tracking: 'auto' | 'manual';
 }
 export declare const resolveConfig: (config: BkOTOptions) => ResolvedBkOTConfig;

package/dist/core/event-time.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Session、Action 和 View 使用同一事件时刻。休眠时 performance.timeOrigin 与墙上时间可能漂移，
+ * 因此用当前时间减去事件已流逝时间换算；缓存同一个 Event，避免监听器之间毫秒取整的偏差。
+ */
+export declare const getEventEpochTime: (event: Event) => number;
+/** Event.timeStamp 在现代浏览器中直接属于 Performance 时钟，不经墙钟回算。 */
+export declare const getEventRelativeTime: (event: Event) => number;

package/dist/core/performance-timing.d.ts

@@ -0,0 +1,13 @@
+type NavigationTimingPoints = PerformanceNavigationTiming & {
+    activationStart?: number;
+};
+type TimingPoints = PerformanceResourceTiming & {
+    finalResponseHeadersStart?: number;
+    workerCacheLookupStart?: number;
+    workerRouterEvaluationStart?: number;
+};
+/** 采集 Resource 与 Navigation 共用的浏览器原始时间点。 */
+export declare const getTimingPointAttributes: (entry: TimingPoints) => Record<string, number>;
+/** Navigation 专属时间点，原样上报；请求阶段由 getTimingPointAttributes 提供。 */
+export declare const getNavigationTimingPointAttributes: (entry: NavigationTimingPoints) => Record<string, number>;
+export {};

package/dist/core/plugin.d.ts

@@ -7,6 +7,8 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 export interface BkOTPlugin {
     enabled?: ((config: ResolvedBkOTConfig) => boolean) | boolean;
     name: string;
+    /** 同步读取浏览器待交付队列；所有插件 drain 后才允许 checkpoint 或停止请求。 */
+    drain?: () => void;
     flush?: () => Promise<void> | void;
     init: (context: BkOTRuntimeContext) => Promise<void> | void;
     shutdown?: () => Promise<void> | void;
@@ -14,13 +16,27 @@ export interface BkOTPlugin {
 export interface BkOTRuntimeContext {
     config: ResolvedBkOTConfig;
     tracer: Tracer;
+    /** afterAssociation 加入身份关联队列，按注册顺序执行；默认阶段仍用于先初始化 View。 */
+    afterSessionTransition: (callback: () => void, afterAssociation?: boolean) => void;
     /** 对外提供的属性脱敏入口，所有插件在 emit 前都应过一次 */
     applyRedact: (attributes: Attributes) => Attributes;
+    beginSessionTransition: (at: number) => () => void;
+    /** 关闭该动作的半开关联区间；不会影响其他重叠 Action。 */
+    endActionContext: (id: string, endTime: number, relativeEndTime?: number) => void;
     flush: () => Promise<void>;
     getRuntimeAttributes: () => Attributes;
     getRuntimeAttributesAt: (timestamp: number) => Attributes;
+    getRuntimeContextAtRelativeTime?: (relativeTime: number) => undefined | {
+        attributes: Attributes;
+        time: number;
+    };
+    getViewHistory?: () => Array<{
+        runtimeAttributes: Attributes;
+        view: BkOTViewContext;
+    }>;
     isSampled: () => boolean;
     isSessionActive: () => boolean;
+    isSessionTransitionPending: () => boolean;
     isViewActive: () => boolean;
     notifyActivity: (event: BkOTActivityEvent) => void;
     notifySessionLifecycle: (event: BkOTSessionLifecycleEvent) => void;
@@ -28,13 +44,24 @@ export interface BkOTRuntimeContext {
     onSessionLifecycle: (listener: (event: BkOTSessionLifecycleEvent) => void) => () => void;
     onViewChange: (listener: (view: BkOTViewContext) => void) => () => void;
     onViewCommand: (listener: (command: BkOTViewCommand) => void) => () => void;
+    /** attributes 保留捕获引用，以支持待定 Session 提交后回填。 */
+    registerActionContext: (id: string, startTime: number, attributes: Attributes) => void;
     registerInstrumentations: (instrumentations: Instrumentation[]) => void;
+    registerSessionCheck: (check: () => void) => () => void;
     setRuntimeAttributes: (attributes: Attributes, changedAt?: number) => void;
     /** 更新用户上下文；user.id 由接入方传入，SDK 原样透传 */
     setUser: (user: BkOTUserContext) => void;
     /** 更新当前 View 上下文，后续 span 会自动带上 view.* 关联字段 */
     setView: (view: BkOTViewContext, changedAt?: number) => void;
     startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
+    /** 本次授权采集区间；再次授权不能重新生成物理文档加载指标。 */
+    collectionStart?: {
+        /** 仅最初即允许采集的实例可读取安装前资源，不补采未授权区间。 */
+        allowInitialResourceHistory?: boolean;
+        isInitialDocument: boolean;
+        relativeStartedAt: number;
+        startedAt: number;
+    };
 }
 /**
  * startSpan 的扩展选项。
@@ -47,20 +74,28 @@ export interface BkOTRuntimeContext {
  * 配合 span.end(endTime?) 可控制结束时间。
  */
 export interface BkOTStartSpanOptions {
-    /** 内置 Span 根据脱敏后的属性生成名称；自定义 startSpan 默认保留传入名称。 */
-    rumSpanType?: RumSpanType;
+    /** 完整运行时快照；缺失字段表示明确不存在，不再从当前或历史上下文补齐。 */
+    contextAttributes?: Attributes;
     /** 用于从历史中解析 Session/View/Action 归属；默认复用数字类型 startTime。 */
     contextTime?: number;
     kind?: SpanKind;
     /** 关联其他 trace 的 Span Link；OTel 要求在创建时传入。 */
     links?: Link[];
+    /** 内置 Span 根据脱敏后的属性生成名称；自定义 startSpan 默认保留传入名称。 */
+    rumSpanType?: RumSpanType;
     startTime?: TimeInput;
 }
 export declare const isPluginEnabled: (plugin: BkOTPlugin, config: ResolvedBkOTConfig) => boolean;
 export declare const createPlugin: (plugin: BkOTPlugin) => BkOTPlugin;
 export declare class PluginManager {
+    private debug;
     private readonly plugins;
     private startedPlugins;
+    private stopped;
+    private stopping?;
+    private drain;
+    private invoke;
+    private warn;
     constructor(plugins: BkOTPlugin[]);
     flush(): Promise<void>;
     shutdown(): Promise<void>;

package/dist/core/processor.d.ts

@@ -1,7 +1,21 @@
+import type { BkOTActivityEvent } from './action-activity';
 import type { ResolvedBkOTConfig } from './config';
-import type { Attributes, Context, Span as ApiSpan } from '@opentelemetry/api';
+import type { Span as ApiSpan, Attributes, Context } from '@opentelemetry/api';
 import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+export declare const RUM_CONTEXT_TIME: symbol;
+export declare const RUM_CONTEXT_SNAPSHOT: symbol;
+/** 请求先创建 Span、后得到最终字段；setAttributes 的合并语义无法表达 Hook 删除。 */
+export declare const replaceSpanAttributes: (span: ApiSpan, attributes: Attributes, replacedKeys: Iterable<string>) => void;
 export declare const markSpanDiscarded: (span: ApiSpan) => void;
+/** Action 自身用单值身份，只有有明确类型的子事件携带多 Action 关联。 */
+export declare const filterActionAttributes: (attributes: Attributes) => Attributes;
+interface SessionAssociation {
+    checkSession: () => void;
+    getAttributesAt: (at: number) => Attributes;
+    isPending: (at?: number) => boolean;
+    isSampled: (attributes: Attributes) => boolean;
+    whenReady: (callback: () => void) => void;
+}
 /**
  * 给所有 span 固化创建时的运行时上下文，并在 onEnd 阶段过滤自身上报请求和无 RUM 上下文 span。
  */
@@ -9,9 +23,17 @@ export declare class FilteringSpanProcessor implements SpanProcessor {
     private readonly inner;
     private readonly config;
     private readonly getRuntimeAttributes;
-    constructor(inner: SpanProcessor, config: ResolvedBkOTConfig, getRuntimeAttributes: () => Attributes);
+    private readonly association?;
+    private readonly onError?;
+    private readonly actionContexts;
+    private readonly pending;
+    private redactEnvelope;
+    constructor(inner: SpanProcessor, config: ResolvedBkOTConfig, getRuntimeAttributes: () => Attributes, association?: SessionAssociation | undefined, onError?: ((event: Extract<BkOTActivityEvent, {
+        type: "error";
+    }>) => void) | undefined);
     forceFlush(): Promise<void>;
     onEnd(span: ReadableSpan): void;
     onStart(span: Span, parentContext: Context): void;
     shutdown(): Promise<void>;
 }
+export {};

package/dist/core/request-timing.d.ts

@@ -1,5 +1,6 @@
 export declare const notifyRequestTiming: (entry: PerformanceResourceTiming) => void;
-export declare const trackRequestTiming: (url: string, startTime?: number) => {
+export declare const trackRequestTiming: (url: string, startTime?: number, initiatorType?: string) => {
+    sent: () => void;
     cancel: () => void;
-    complete: (callback: (entry?: PerformanceResourceTiming) => void) => void;
+    complete: (callback: (entry?: PerformanceResourceTiming) => void, waitForBody?: boolean) => void;
 };

package/dist/core/runtime-context.d.ts

@@ -1,10 +1,14 @@
 import type { Attributes } from '@opentelemetry/api';
 export type BkOTSessionLifecycleEvent = {
+    /** false 表示仅截断本地关联，expiredAt 不是已确认的全局结束时间，不能据此生成结束遥测。 */
+    endTimeKnown?: boolean;
     expiredAt: number;
     id: string;
     reason: 'external' | 'inactivity' | 'maxLifetime';
     type: 'expired';
 } | {
+    /** 本 Tab 绑定该 Session 的生效时间，不等同于共享 Session 的创建时间。 */
+    activatedAt?: number;
     id: string;
     previousId?: string;
     reason: 'inactivity' | 'init' | 'maxLifetime' | 'shared';
@@ -15,16 +19,32 @@ export interface BkOTStartViewOptions {
     attributes?: Attributes;
     name?: string;
     url?: string;
+    /** 框架路由定义中的低基数路径，例如 /orders/:orderId；优先于 URL 推断。 */
+    urlTemplate?: string;
 }
 export interface BkOTUserContext {
     /** 由接入方传入并由 SDK 原样透传；SDK 不 hash、不脱敏、不改写。 */
     id?: string;
 }
 export type BkOTViewCommand = {
+    attributes: Attributes;
+    type: 'set_context';
+} | {
+    elapsed?: number;
+    name: string;
+    time: number;
+    type: 'add_timing';
+} | {
+    key: string;
+    type: 'set_context_property';
+    value: Attributes[string];
+} | {
     name: string;
     type: 'set_name';
 } | {
     options: BkOTStartViewOptions;
+    relativeStartedAt?: number;
+    startedAt?: number;
     type: 'start';
 } | {
     time: number;
@@ -32,13 +52,23 @@ export type BkOTViewCommand = {
 };
 export interface BkOTViewContext {
     attributes?: Attributes;
+    /** 清空 View 时传递已确认的结束边界，供迟到指标归属；不是接收通知的时间。 */
+    endedAt?: number;
     id?: string;
+    interactionCountAtEnd?: number;
+    /** 原生交互计数在 View 边界的快照，供迟安装的 INP 采集器恢复分位数基线。 */
+    interactionCountAtStart?: number;
     loadingType?: 'bf_cache' | 'initial_load' | 'route_change' | 'session_renewal';
     name?: string;
+    relativeEndedAt?: number;
+    /** 与 PerformanceEntry.startTime 同一时钟；不能由 timeOrigin 与墙钟差值推导。 */
+    relativeStartedAt?: number;
     startedAt?: number;
     url?: string;
     urlTemplate?: string;
 }
+/** OTel 属性只允许标量和标量数组；复制数组即可隔离调用方、当前状态与历史快照。 */
+export declare const copyAttributes: (attributes?: Attributes) => Attributes;
 /**
  * 管理 SDK 运行期公共属性快照。
  *
@@ -47,12 +77,13 @@ export interface BkOTViewContext {
  */
 export declare class RumRuntimeContext {
     private readonly actionHistory;
+    private appendActionIds;
     private readonly attributes;
     private readonly queuedViewCommands;
     private recordAssociation;
-    private readonly sessionHistory;
     private sampled;
     private readonly samplingHistory;
+    private readonly sessionHistory;
     private readonly sessionLifecycleListeners;
     private readonly setOptionalAttribute;
     private user;
@@ -61,12 +92,40 @@ export declare class RumRuntimeContext {
     private readonly viewChangeListeners;
     private readonly viewCommandListeners;
     private readonly viewHistory;
+    private readonly viewLifecycles;
     private readonly viewScopedAttributeKeys;
     dispatchViewCommand: (command: BkOTViewCommand) => void;
+    endActionContext: (id: string, endedAt: number, relativeEndedAt?: number) => void;
     getAttributes: () => Attributes;
     getAttributesAt: (timestamp: number) => Attributes;
+    /** PerformanceEntry 按相对区间选择身份；epoch 只用于最终 Span 时间，不再反查身份。 */
+    getRuntimeContextAtRelativeTime: (relativeTime: number) => undefined | {
+        attributes: Attributes;
+        time: number;
+    };
     getUser: () => BkOTUserContext;
     getView: () => BkOTViewContext;
+    /** 指标插件可能晚于首个路由安装，只保留每个 View 的最后快照与原始边界。 */
+    getViewHistory: () => {
+        view: {
+            attributes: Attributes;
+            /** 清空 View 时传递已确认的结束边界，供迟到指标归属；不是接收通知的时间。 */
+            endedAt?: number;
+            id?: string;
+            interactionCountAtEnd?: number;
+            /** 原生交互计数在 View 边界的快照，供迟安装的 INP 采集器恢复分位数基线。 */
+            interactionCountAtStart?: number;
+            loadingType?: "bf_cache" | "initial_load" | "route_change" | "session_renewal";
+            name?: string;
+            relativeEndedAt?: number;
+            /** 与 PerformanceEntry.startTime 同一时钟；不能由 timeOrigin 与墙钟差值推导。 */
+            relativeStartedAt?: number;
+            startedAt?: number;
+            url?: string;
+            urlTemplate?: string;
+        };
+        runtimeAttributes: Attributes;
+    }[];
     isSessionActive: () => boolean;
     isSessionSampledAt: (timestamp: number) => boolean;
     isViewActive: () => boolean;
@@ -74,9 +133,10 @@ export declare class RumRuntimeContext {
     onSessionLifecycle: (listener: (event: BkOTSessionLifecycleEvent) => void) => () => boolean;
     onViewChange: (listener: (view: BkOTViewContext) => void) => () => boolean;
     onViewCommand: (listener: (command: BkOTViewCommand) => void) => () => boolean;
+    registerActionContext: (id: string, startedAt: number, attributes: Attributes) => void;
     setAttributes: (attributes: Attributes, changedAt?: number) => void;
-    setUser: (user: BkOTUserContext) => void;
     setSessionSampled: (sampled: boolean, changedAt?: number) => void;
+    setUser: (user: BkOTUserContext) => void;
     setView: (view: BkOTViewContext, changedAt?: number) => void;
     constructor(initialAttributes?: Attributes, user?: BkOTUserContext);
 }

package/dist/core/sdk.d.ts

@@ -3,12 +3,16 @@ import { type BkOTActionEventPayload, type BkOTCustomEventPayload, type BkOTOpti
 import { type BkOTPlugin, type BkOTRuntimeContext, type BkOTStartSpanOptions } from './plugin';
 import { type BkOTSessionLifecycleEvent, type BkOTStartViewOptions, type BkOTUserContext } from './runtime-context';
 import type { Instrumentation } from '@opentelemetry/instrumentation';
-export interface BkOTInstance extends Omit<BkOTRuntimeContext, 'notifyActivity' | 'onActivity' | 'onViewChange' | 'onViewCommand' | 'registerInstrumentations' | 'setView'> {
+export interface BkOTInstance extends Omit<BkOTRuntimeContext, 'endActionContext' | 'notifyActivity' | 'onActivity' | 'onViewChange' | 'onViewCommand' | 'registerActionContext' | 'registerInstrumentations' | 'setView'> {
+    addTiming: (name: string, elapsed?: number) => void;
     flush: () => Promise<void>;
+    getViewContext: () => Attributes;
     reportAction: (payload: BkOTActionEventPayload) => void;
     reportCustomEvent: (payload: BkOTCustomEventPayload) => void;
     setTrackingConsent: (consent: BkOTTrackingConsent) => Promise<void>;
     setUser: (user: BkOTUserContext) => void;
+    setViewContext: (attributes: Attributes) => void;
+    setViewContextProperty: (key: string, value: Attributes[string]) => void;
     setViewLoadingTime: () => void;
     setViewName: (name: string) => void;
     shutdown: () => Promise<void>;
@@ -23,36 +27,54 @@ export interface BkOTInstance extends Omit<BkOTRuntimeContext, 'notifyActivity'
  */
 export declare class BkOpenTelemetry implements BkOTInstance {
     private readonly activityObserver;
+    private allowInitialResourceHistory;
+    private readonly collectAttributesAt;
+    private collectionStopping?;
     private readonly flushProviders;
+    private hasStartedCollection;
+    private readonly isStopped;
+    private latestManualViewOptions?;
     private phase;
     private pluginManager?;
     private readonly registeredInstrumentations;
     private releaseOtelGlobals?;
     private readonly runtimeContext;
     private sampled;
+    private readonly sessionTransition;
+    private shutdownTask?;
     private readonly startCollection;
     private readonly stopCollection;
+    private tabId?;
     private readonly teardownCallbacks;
     private readonly tracerProvider;
     private assertBeforeStart;
     private createPluginContext;
     private createPluginManager;
+    /** elapsed 为相对当前 View 起点的毫秒；省略时使用调用时刻，避免混用 epoch 时间。 */
+    readonly addTiming: (name: string, elapsed?: number) => void;
+    readonly afterSessionTransition: (callback: () => void, afterAssociation?: boolean) => void;
     readonly applyRedact: (attributes: Attributes) => Attributes;
+    readonly beginSessionTransition: (at: number) => () => void;
     readonly config: ResolvedBkOTConfig;
     readonly flush: () => Promise<void>;
     readonly getRuntimeAttributes: () => Attributes;
     readonly getRuntimeAttributesAt: (timestamp: number) => Attributes;
+    readonly getViewContext: () => Attributes;
     readonly isSampled: () => boolean;
     readonly isSessionActive: () => boolean;
+    readonly isSessionTransitionPending: () => boolean;
     readonly isViewActive: () => boolean;
     readonly notifySessionLifecycle: (event: BkOTSessionLifecycleEvent) => void;
     readonly onSessionLifecycle: (listener: (event: BkOTSessionLifecycleEvent) => void) => () => boolean;
     readonly registerInstrumentations: (instrumentations: Instrumentation[]) => void;
+    readonly registerSessionCheck: (check: () => void) => () => void;
     readonly reportAction: ({ attributes, name }: BkOTActionEventPayload) => void;
     readonly reportCustomEvent: ({ attributes, error, name }: BkOTCustomEventPayload) => void;
     readonly setRuntimeAttributes: (attributes: Attributes, changedAt?: number) => void;
     readonly setTrackingConsent: (consent: BkOTTrackingConsent) => Promise<void>;
     readonly setUser: (user: BkOTUserContext) => void;
+    readonly setViewContext: (attributes: Attributes) => void;
+    readonly setViewContextProperty: (key: string, value: Attributes[string]) => void;
     readonly setViewLoadingTime: () => void;
     readonly setViewName: (name: string) => void;
     readonly shutdown: () => Promise<void>;

package/dist/core/session-transition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 串行提交 Session 时先采集事件，再关联会话。View 变更先落地，随后解析待定快照，
+ * 防止第一击在 Web Lock 返回前继承旧 ID。停止采集会使所有旧回调失效。
+ */
+export declare class SessionTransition {
+    private readonly capacity;
+    private readonly associations;
+    private readonly callbacks;
+    private check?;
+    private checking;
+    private readonly pending;
+    begin: (at: number) => () => void;
+    checkSession: () => void;
+    isPending: (at?: number) => boolean;
+    registerCheck: (check: () => void) => () => void;
+    reset: () => void;
+    whenReady: (callback: () => void, association?: boolean) => void;
+    constructor(capacity: number);
+}

package/dist/core/trace-context.d.ts

@@ -6,16 +6,17 @@
  * Span Link 把后端 trace 关联回 RUM Span。
  *
  * 如果业务已经自行设置了 trace header（`traceparent`、`sentry-trace`、b3、Datadog、sw8），则完全
- * 不注入，避免破坏业务既有的传播方式，只把已有链路建成 Link。
+ * 不注入，避免破坏业务既有的传播方式；只有可映射的合法链路才建 Link。
  *
- * Link 结构恒定：`context` 承载 trace-id/span-id，`attributes` 记录命中的格式与原始 header。
- * sw8 这类无法映射为合法 OTel id 的格式会补一对占位 id，让 Link 结构保持统一。
+ * `context` 承载 trace-id/span-id，`attributes` 只记录命中的格式和是否由 SDK 注入。
+ * 原始厂商 header 可能包含业务标签、服务地址等内容，不进入遥测事件。
+ * sw8 这类无法映射为合法 OTel id 的格式不建 Link，避免把不存在的链路提供给检索端。
  */
-import type { Attributes, Link } from '@opentelemetry/api';
+import type { Link } from '@opentelemetry/api';
 /** 大小写不敏感地读取一个请求 header */
 export type BkOTHeaderReader = (name: string) => string | undefined;
 export interface BkOTRequestTracePlan {
-    /** 关联后端 trace 的 Span Link，恒为一条 */
+    /** 关联后端 trace 的 Span Link；既有厂商上下文无法映射时为空 */
     links: Link[];
     /** 需要注入的 traceparent；业务已有 trace header 时为 undefined */
     traceparent?: string;
@@ -24,8 +25,6 @@ export type BkOTUpstreamTraceFormat = 'b3' | 'b3-multi' | 'datadog' | 'sentry-tr
 export declare const TRACEPARENT_HEADER = "traceparent";
 interface UpstreamTrace {
     format: BkOTUpstreamTraceFormat;
-    /** 命中格式的原始 header，原样写入 Link Attributes */
-    headers: Attributes;
     sampled?: boolean;
     /** 规范化后的合法 OTel id；无法映射时两者同时缺失 */
     spanId?: string;

package/dist/core/view-location.d.ts

@@ -0,0 +1,10 @@
+export type BkOTViewRouteMode = 'auto' | 'document' | 'hash' | 'history';
+/** 仅用于身份比较与模板生成；routePath 仍可能含业务 ID，不能当作已脱敏 URL 直接上报。 */
+export declare const getViewLocation: (url: string, mode?: BkOTViewRouteMode) => {
+    hash: string;
+    kind: "hash" | "history";
+    pathname: string;
+    routePath: string;
+};
+/** 同文档导航边界；整页导航由新 Document 初始化产生 initial_load，不经过此比较。 */
+export declare const isViewLocationChange: (fromUrl: string, toUrl: string, mode?: BkOTViewRouteMode) => boolean;

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { type BkOTPlugin, type BkOTRuntimeContext, createPlugin, type PluginMana
 export { FilteringSpanProcessor } from './core/processor';
 export { type BkOTSessionLifecycleEvent, type BkOTStartViewOptions, type BkOTUserContext, type BkOTViewContext, RumRuntimeContext, } from './core/runtime-context';
 export { BkOpenTelemetry, type BkOTInstance } from './core/sdk';
+export { type BkOTViewRouteMode } from './core/view-location';
+export { type BkOTVueRoute, type BkOTVueRouter, type BkOTVueViewClient, trackVueRouterViews, } from './integrations/vue-router';
 export { type BkOTActionPluginOptions, createActionPlugin } from './plugins/action';
 export { EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE } from './plugins/activity';
 export { type BkOTBlankScreenPluginOptions, createBlankScreenPlugin } from './plugins/blank-screen';