@blueking/open-telemetry 0.0.6 → 0.0.7

package/dist/core/config.d.ts

@@ -1,6 +1,18 @@
 import type { BkOTPlugin } from './plugin';
+import type { BkOTUserContext } from './runtime-context';
 import type { Attributes } from '@opentelemetry/api';
 import type { Instrumentation } from '@opentelemetry/instrumentation';
+export interface BkOTActionEventPayload {
+    attributes?: Attributes;
+    targetTag?: string;
+    targetText?: string;
+    type: 'click' | 'custom' | 'input' | 'keydown' | 'pointerdown' | 'scroll' | 'submit' | string;
+}
+export interface BkOTAppConfig {
+    environment?: string;
+    name?: string;
+    version?: string;
+}
 export interface BkOTAttributesConfig {
     custom?: () => Attributes;
     error?: () => Attributes;
@@ -14,27 +26,6 @@ export interface BkOTBatchConfig {
     maxQueueSize?: number;
     scheduledDelayMillis?: number;
 }
-export interface BkOTConfig {
-    attributes?: BkOTAttributesConfig;
-    autoStart?: boolean;
-    debug?: boolean;
-    enabled?: boolean;
-    endpoint?: string;
-    environment?: string;
-    headers?: Record<string, string>;
-    instrumentations?: Instrumentation[];
-    logs?: SignalExporterInputConfig;
-    metrics?: SignalExporterInputConfig;
-    plugins?: BkOTPlugin[];
-    redact?: BkOTRedactConfig;
-    rum?: BkOTRumConfig;
-    sampleRate?: number;
-    signalEndpoints?: SignalEndpointsConfig;
-    spanBatch?: BkOTBatchConfig;
-    spanProcessor?: BkOTSpanProcessorMode;
-    token?: string;
-    traces?: SignalExporterInputConfig;
-}
 export interface BkOTCustomEventPayload {
     attributes?: Attributes;
     error?: Error;
@@ -61,20 +52,52 @@ export interface BkOTInstrumentationsConfig {
     };
     xhr?: boolean;
 }
-export interface BkOTRedactConfig {
-    attributes?: (attributes: Attributes) => Attributes;
-    url?: (url: string) => string;
+export interface BkOTOptions {
+    app?: BkOTAppConfig;
+    attributes?: BkOTAttributesConfig;
+    autoStart?: boolean;
+    debug?: boolean;
+    enabled?: boolean;
+    instrumentations?: Instrumentation[];
+    plugins?: BkOTPlugin[];
+    privacy?: BkOTPrivacyConfig;
+    route?: BkOTRouteConfig;
+    rum?: BkOTRumOptions;
+    sampling?: BkOTSamplingConfig;
+    spanBatch?: BkOTBatchConfig;
+    spanProcessor?: BkOTSpanProcessorMode;
+    transport?: BkOTTransportConfig;
+    user?: BkOTUserContext;
+}
+export interface BkOTPrivacyConfig {
+    redactAttributes?: (attributes: Attributes) => Attributes;
+    redactUrl?: (url: string) => string;
+}
+export interface BkOTRouteConfig {
+    /**
+     * 返回低基数路由分组，例如 `/trace/:id`。
+     * SDK 默认退化为 URL pathname；复杂业务路由建议接入方显式提供模板。
+     */
+    getPathGroup?: (url: string) => string | undefined;
 }
-export interface BkOTRumConfig extends BkOTInstrumentationsConfig {
+export interface BkOTRumOptions {
+    instrumentations?: BkOTInstrumentationsConfig;
+    plugins?: BkOTRumPluginOptions;
+}
+export interface BkOTRumPluginOptions {
     cspViolation?: boolean;
     device?: boolean | {
         storageKey?: string;
     };
     httpBody?: BkOTHttpBodyConfig | boolean;
     pageView?: boolean;
+    resource?: boolean;
     routeTiming?: boolean;
     websocket?: boolean;
     webVitals?: boolean;
+    action?: boolean | {
+        eventNames?: Array<'click' | 'input' | 'keydown' | 'pointerdown' | 'scroll' | 'submit'>;
+    };
     blankScreen?: {
         checkDelay?: number;
         ignoreSelectors?: string[];
@@ -94,34 +117,99 @@ export interface BkOTRumConfig extends BkOTInstrumentationsConfig {
         storageKey?: string;
     } | boolean;
 }
+export interface BkOTSamplingConfig {
+    rate?: number;
+}
 export type BkOTSpanProcessorMode = 'batch' | 'simple';
-export interface NormalizedBkOTConfig extends Omit<BkOTConfig, 'attributes' | 'autoStart' | 'debug' | 'enabled' | 'endpoint' | 'environment' | 'instrumentations' | 'logs' | 'metrics' | 'plugins' | 'redact' | 'signalEndpoints' | 'spanProcessor' | 'token' | 'traces'> {
+export interface BkOTTransportConfig {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    signals?: SignalExportersInputConfig;
+    token?: string;
+}
+export interface ResolvedAppConfig {
+    environment: string;
+    name: string;
+    version?: string;
+}
+export interface ResolvedBkOTConfig {
+    app: ResolvedAppConfig;
     autoStart: boolean;
     debug: boolean;
     enabled: boolean;
-    endpoint: string;
-    environment: string;
+    hooks: ResolvedConfigHooks;
     instrumentations: Instrumentation[];
-    logs: SignalExporterConfig;
     metricIntervalMillis: number;
-    metrics: SignalExporterConfig;
     plugins: BkOTPlugin[];
     resourceAttributes: Attributes;
-    sampleRate: number;
+    rum: ResolvedRumConfig;
+    sampling: ResolvedSamplingConfig;
+    spanBatch?: BkOTBatchConfig;
     spanProcessor: BkOTSpanProcessorMode;
-    traces: SignalExporterConfig;
+    transport: ResolvedTransportConfig;
+    user?: BkOTUserContext;
+}
+export interface ResolvedConfigHooks {
     getCustomAttributes: () => Attributes;
     getErrorAttributes: () => Attributes;
     getMetricAttributes: () => Attributes;
     getPageAttributes: () => Attributes;
+    getViewPathGroup: (url: string) => string;
     redactAttributes: (attributes: Attributes) => Attributes;
     redactUrl: (url: string) => string;
-    commonInstrumentations: Required<Pick<BkOTInstrumentationsConfig, 'documentLoad' | 'fetch' | 'xhr'>> & {
+}
+export type ResolvedPluginOption<TConfig extends object = object> = (TConfig & {
+    enabled: true;
+}) | {
+    enabled: false;
+};
+export interface ResolvedRumConfig {
+    plugins: ResolvedRumPluginConfig;
+    instrumentations: Required<Pick<BkOTInstrumentationsConfig, 'documentLoad' | 'fetch' | 'xhr'>> & {
         userInteraction: BkOTInstrumentationsConfig['userInteraction'];
     };
-    rum: Omit<Required<BkOTRumConfig>, 'documentLoad' | 'fetch' | 'httpBody' | 'userInteraction' | 'xhr'> & {
-        httpBody: false | Required<BkOTHttpBodyConfig>;
-    };
+}
+export interface ResolvedRumPluginConfig {
+    cspViolation: ResolvedPluginOption;
+    device: ResolvedPluginOption<{
+        storageKey?: string;
+    }>;
+    error: ResolvedPluginOption<{
+        maxPerWindow: number;
+        windowMs: number;
+    }>;
+    httpBody: ResolvedPluginOption<Required<BkOTHttpBodyConfig>>;
+    longTask: ResolvedPluginOption<{
+        threshold: number;
+    }>;
+    pageView: ResolvedPluginOption;
+    resource: ResolvedPluginOption;
+    routeTiming: ResolvedPluginOption;
+    websocket: ResolvedPluginOption;
+    webVitals: ResolvedPluginOption;
+    action: ResolvedPluginOption<{
+        eventNames: Array<'click' | 'input' | 'keydown' | 'pointerdown' | 'scroll' | 'submit'>;
+    }>;
+    blankScreen: ResolvedPluginOption<{
+        checkDelay: number;
+        ignoreSelectors?: string[];
+        rootSelector?: string;
+        threshold: number;
+    }>;
+    session: ResolvedPluginOption<{
+        inactivityMs: number;
+        maxLifetimeMs: number;
+        storageKey?: string;
+    }>;
+}
+export interface ResolvedSamplingConfig {
+    rate: number;
+}
+export interface ResolvedTransportConfig {
+    endpoint: string;
+    logs: SignalExporterConfig;
+    metrics: SignalExporterConfig;
+    traces: SignalExporterConfig;
 }
 export interface SignalEndpointsConfig {
     logs?: string;
@@ -135,4 +223,10 @@ export interface SignalExporterConfig {
     timeoutMillis?: number;
 }
 export type SignalExporterInputConfig = Partial<SignalExporterConfig>;
-export declare const normalizeConfig: (config: BkOTConfig) => NormalizedBkOTConfig;
+export interface SignalExportersInputConfig {
+    endpoints?: SignalEndpointsConfig;
+    logs?: SignalExporterInputConfig;
+    metrics?: SignalExporterInputConfig;
+    traces?: SignalExporterInputConfig;
+}
+export declare const resolveConfig: (config: BkOTOptions) => ResolvedBkOTConfig;

package/dist/core/plugin.d.ts

@@ -1,15 +1,16 @@
-import type { NormalizedBkOTConfig } from './config';
+import type { ResolvedBkOTConfig } from './config';
+import type { BkOTUserContext, BkOTViewContext } from './runtime-context';
 import type { Attributes, Meter, Span, TimeInput, Tracer } from '@opentelemetry/api';
 import type { Logger, LogRecord } from '@opentelemetry/api-logs';
 export interface BkOTPlugin {
-    enabled?: ((config: NormalizedBkOTConfig) => boolean) | boolean;
+    enabled?: ((config: ResolvedBkOTConfig) => boolean) | boolean;
     name: string;
     flush?: () => Promise<void> | void;
     init: (context: BkOTRuntimeContext) => Promise<void> | void;
     shutdown?: () => Promise<void> | void;
 }
 export interface BkOTRuntimeContext {
-    config: NormalizedBkOTConfig;
+    config: ResolvedBkOTConfig;
     logger: Logger;
     meter: Meter;
     tracer: Tracer;
@@ -19,6 +20,10 @@ export interface BkOTRuntimeContext {
     emitLog: (record: LogRecord) => void;
     getRuntimeAttributes: () => Attributes;
     setRuntimeAttributes: (attributes: Attributes) => void;
+    /** 更新用户上下文；user.id 由接入方传入，SDK 原样透传 */
+    setUser: (user: BkOTUserContext) => void;
+    /** 更新当前 View 上下文，后续 span/log 会自动带上 view.* 关联字段 */
+    setView: (view: BkOTViewContext) => void;
     startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
 }
 /**
@@ -34,7 +39,7 @@ export interface BkOTRuntimeContext {
 export interface BkOTStartSpanOptions {
     startTime?: TimeInput;
 }
-export declare const isPluginEnabled: (plugin: BkOTPlugin, config: NormalizedBkOTConfig) => boolean;
+export declare const isPluginEnabled: (plugin: BkOTPlugin, config: ResolvedBkOTConfig) => boolean;
 export declare const createPlugin: (plugin: BkOTPlugin) => BkOTPlugin;
 export declare class PluginManager {
     private readonly plugins;

package/dist/core/processor.d.ts

@@ -1,4 +1,4 @@
-import type { NormalizedBkOTConfig } from './config';
+import type { ResolvedBkOTConfig } from './config';
 import type { Context } from '@opentelemetry/api';
 import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
 /**
@@ -8,7 +8,7 @@ import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace
 export declare class FilteringSpanProcessor implements SpanProcessor {
     private readonly inner;
     private readonly config;
-    constructor(inner: SpanProcessor, config: NormalizedBkOTConfig);
+    constructor(inner: SpanProcessor, config: ResolvedBkOTConfig);
     forceFlush(): Promise<void>;
     onEnd(span: ReadableSpan): void;
     onStart(span: Span, parentContext: Context): void;

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

@@ -0,0 +1,30 @@
+import type { Attributes } from '@opentelemetry/api';
+export interface BkOTUserContext {
+    /** 由接入方传入并由 SDK 原样透传；SDK 不 hash、不脱敏、不改写。 */
+    id?: string;
+}
+export interface BkOTViewContext {
+    id?: string;
+    loadingType?: 'initial_load' | 'route_change';
+    url?: string;
+    urlPathGroup?: string;
+}
+/**
+ * 管理 SDK 运行期公共属性快照。
+ *
+ * 这里仅保存“后续事件都需要带上”的低成本上下文，Session/View/用户切换时更新快照，
+ * 插件发 span/log 时读取当前快照即可，避免每个插件重复维护公共字段。
+ */
+export declare class RumRuntimeContext {
+    private readonly attributes;
+    private readonly setOptionalAttribute;
+    private user;
+    private view;
+    getAttributes: () => Attributes;
+    getUser: () => BkOTUserContext;
+    getView: () => BkOTViewContext;
+    setAttributes: (attributes: Attributes) => void;
+    setUser: (user: BkOTUserContext) => void;
+    setView: (view: BkOTViewContext) => void;
+    constructor(initialAttributes?: Attributes, user?: BkOTUserContext);
+}

package/dist/core/sampling.d.ts

@@ -1,2 +1,2 @@
-import type { NormalizedBkOTConfig } from './config';
-export declare const isBkOTSampled: ({ sampleRate }: Pick<NormalizedBkOTConfig, "sampleRate">) => boolean;
+import type { ResolvedBkOTConfig } from './config';
+export declare const isBkOTSampled: ({ sampling }: Pick<ResolvedBkOTConfig, "sampling">) => boolean;

package/dist/core/sdk.d.ts

@@ -1,11 +1,15 @@
 import { type Attributes, type Span } from '@opentelemetry/api';
 import { type Instrumentation } from '@opentelemetry/instrumentation';
-import { type BkOTConfig, type BkOTCustomEventPayload, type NormalizedBkOTConfig } from './config';
+import { type BkOTActionEventPayload, type BkOTCustomEventPayload, type BkOTOptions, type ResolvedBkOTConfig } from './config';
 import { type BkOTPlugin, type BkOTRuntimeContext, type BkOTStartSpanOptions } from './plugin';
+import { type BkOTUserContext, type BkOTViewContext } from './runtime-context';
 import type { LogRecord } from '@opentelemetry/api-logs';
 export interface BkOTInstance extends BkOTRuntimeContext {
     flush: () => Promise<void>;
+    reportAction: (payload: BkOTActionEventPayload) => void;
     reportCustomEvent: (payload: BkOTCustomEventPayload) => void;
+    setUser: (user: BkOTUserContext) => void;
+    setView: (view: BkOTViewContext) => void;
     shutdown: () => Promise<void>;
     start: () => Promise<void>;
     use: (plugin: BkOTPlugin) => BkOTInstance;
@@ -18,27 +22,28 @@ export declare class BkOpenTelemetry implements BkOTInstance {
     private readonly pluginManager;
     private readonly plugins;
     private readonly registeredInstrumentations;
-    private readonly runtimeAttributes;
+    private readonly runtimeContext;
     private readonly sampled;
     private readonly teardownCallbacks;
     private readonly tracerProvider;
     private assertBeforeStart;
     readonly applyRedact: (attributes: Attributes) => Attributes;
-    readonly config: NormalizedBkOTConfig;
+    readonly config: ResolvedBkOTConfig;
     readonly emitLog: (record: LogRecord) => void;
     readonly flush: () => Promise<void>;
-    readonly getRuntimeAttributes: () => {
-        [attributeKey: string]: import("@opentelemetry/api").AttributeValue | undefined;
-    };
+    readonly getRuntimeAttributes: () => Attributes;
     readonly logger: BkOTRuntimeContext['logger'];
     readonly meter: BkOTRuntimeContext['meter'];
+    readonly reportAction: ({ attributes, targetTag, targetText, type }: BkOTActionEventPayload) => void;
     readonly reportCustomEvent: ({ attributes, error, name }: BkOTCustomEventPayload) => void;
     readonly setRuntimeAttributes: (attributes: Attributes) => void;
+    readonly setUser: (user: BkOTUserContext) => void;
+    readonly setView: (view: BkOTViewContext) => void;
     readonly shutdown: () => Promise<void>;
     readonly start: () => Promise<void>;
     readonly startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
     readonly tracer: BkOTRuntimeContext['tracer'];
     readonly use: (plugin: BkOTPlugin) => this;
     readonly useInstrumentation: (instrumentation: Instrumentation) => this;
-    constructor(inputConfig: BkOTConfig);
+    constructor(inputConfig: BkOTOptions);
 }

package/dist/core/url.d.ts

@@ -1,4 +1,4 @@
-import type { NormalizedBkOTConfig } from './config';
-export declare const isBkOTEndpoint: (config: NormalizedBkOTConfig, url: string) => boolean;
-export declare const shouldIgnoreUrl: (config: NormalizedBkOTConfig, url: string) => boolean;
-export declare const shouldPropagateTraceHeader: (_config: NormalizedBkOTConfig, url: string) => boolean;
+import type { ResolvedBkOTConfig } from './config';
+export declare const isBkOTEndpoint: (config: ResolvedBkOTConfig, url: string) => boolean;
+export declare const shouldIgnoreUrl: (config: ResolvedBkOTConfig, url: string) => boolean;
+export declare const shouldPropagateTraceHeader: (_config: ResolvedBkOTConfig, url: string) => boolean;

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-export { type BkOTAttributesConfig, type BkOTAttributeValue, type BkOTBatchConfig, type BkOTConfig, type BkOTCustomEventPayload, type BkOTHttpBodyConfig, type BkOTHttpBodyRedactPayload, type BkOTRedactConfig, type BkOTRumConfig, normalizeConfig, type NormalizedBkOTConfig, type SignalExporterConfig, } from './core/config';
+export { type BkOTActionEventPayload, type BkOTAppConfig, type BkOTAttributesConfig, type BkOTAttributeValue, type BkOTBatchConfig, type BkOTCustomEventPayload, type BkOTHttpBodyConfig, type BkOTHttpBodyRedactPayload, type BkOTInstrumentationsConfig, type BkOTOptions, type BkOTPrivacyConfig, type BkOTRumOptions, type BkOTRumPluginOptions, type BkOTSamplingConfig, type BkOTTransportConfig, resolveConfig, type ResolvedBkOTConfig, type ResolvedConfigHooks, type ResolvedPluginOption, type ResolvedRumConfig, type ResolvedRumPluginConfig, type ResolvedTransportConfig, type SignalExporterConfig, type SignalExportersInputConfig, } from './core/config';
 export { type BkOTPlugin, type BkOTRuntimeContext, createPlugin, type PluginManager } from './core/plugin';
 export { FilteringSpanProcessor } from './core/processor';
+export { type BkOTUserContext, type BkOTViewContext, RumRuntimeContext } from './core/runtime-context';
 export { BkOpenTelemetry, type BkOTInstance } from './core/sdk';
+export { RUM_ATTRIBUTES, type RumAttributeKey } from './schema/attributes';
+export { buildRumSpanAttributes, getDurationBucket, RUM_SPAN_RESULT, RUM_SPAN_TYPE, type RumSpanClassification, type RumSpanResult, type RumSpanType, } from './schema/span';
+export { createActionPlugin } from './plugins/action';
 export { createBlankScreenPlugin } from './plugins/blank-screen';
 export { createCommonInstrumentationsPlugin } from './plugins/common';
 export { createCspViolationPlugin } from './plugins/csp-violation';
@@ -10,6 +14,7 @@ export { createErrorPlugin } from './plugins/error';
 export { createHttpBodyPlugin } from './plugins/http-body';
 export { createLongTaskPlugin } from './plugins/long-task';
 export { createPageViewPlugin } from './plugins/page-view';
+export { createResourcePlugin } from './plugins/resource';
 export { createRouteTimingPlugin } from './plugins/route-timing';
 export { createSessionPlugin } from './plugins/session';
 export { createWebVitalsPlugin } from './plugins/web-vitals';