@blueking/open-telemetry 0.0.5 → 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,26 +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;
-    token?: string;
-    traces?: SignalExporterInputConfig;
-}
 export interface BkOTCustomEventPayload {
     attributes?: Attributes;
     error?: Error;
@@ -60,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[];
@@ -89,35 +113,103 @@ export interface BkOTRumConfig extends BkOTInstrumentationsConfig {
     } | boolean;
     session?: {
         inactivityMs?: number;
+        maxLifetimeMs?: number;
         storageKey?: string;
     } | boolean;
 }
-export interface NormalizedBkOTConfig extends Omit<BkOTConfig, 'attributes' | 'autoStart' | 'debug' | 'enabled' | 'endpoint' | 'environment' | 'instrumentations' | 'logs' | 'metrics' | 'plugins' | 'redact' | 'signalEndpoints' | 'token' | 'traces'> {
+export interface BkOTSamplingConfig {
+    rate?: number;
+}
+export type BkOTSpanProcessorMode = 'batch' | 'simple';
+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;
-    traces: SignalExporterConfig;
+    rum: ResolvedRumConfig;
+    sampling: ResolvedSamplingConfig;
+    spanBatch?: BkOTBatchConfig;
+    spanProcessor: BkOTSpanProcessorMode;
+    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;
@@ -131,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/id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 生成随机 ID。优先用 `crypto.randomUUID`（standards-compliant UUID v4），不可用时回退到
+ * `${prefix}-${timestamp}-${rand}` 形式。
+ *
+ * 注意：fallback 实现使用 Math.random，**不是密码学安全**，仅适用于设备/会话/事件标识等场景，
+ * 不要复用此函数生成 token、CSRF 防护等安全相关的值。
+ */
+export declare const createRandomId: (prefix: string) => string;

package/dist/core/plugin.d.ts

@@ -1,15 +1,16 @@
-import type { NormalizedBkOTConfig } from './config';
-import type { Attributes, Meter, Span, Tracer } from '@opentelemetry/api';
+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,9 +20,26 @@ export interface BkOTRuntimeContext {
     emitLog: (record: LogRecord) => void;
     getRuntimeAttributes: () => Attributes;
     setRuntimeAttributes: (attributes: Attributes) => void;
-    startSpan: (name: string, attributes?: Attributes) => Span;
+    /** 更新用户上下文；user.id 由接入方传入，SDK 原样透传 */
+    setUser: (user: BkOTUserContext) => void;
+    /** 更新当前 View 上下文，后续 span/log 会自动带上 view.* 关联字段 */
+    setView: (view: BkOTViewContext) => void;
+    startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
 }
-export declare const isPluginEnabled: (plugin: BkOTPlugin, config: NormalizedBkOTConfig) => boolean;
+/**
+ * startSpan 的扩展选项。
+ *
+ * 用于"事件实际发生在过去某个时刻，但 span 现在才创建"的场景：
+ * 例如 route-timing 在 raf+setTimeout 链路结束后才上报，但希望 span 的时间窗
+ * 反映真实的"路由切换瞬间到渲染完成"区间，方便 trace 视图与并发请求对齐。
+ *
+ * startTime 接受 OT TimeInput；常用 epoch 毫秒（performance.timeOrigin + performance.now()）。
+ * 配合 span.end(endTime?) 可控制结束时间。
+ */
+export interface BkOTStartSpanOptions {
+    startTime?: TimeInput;
+}
+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 BkOTPlugin, type BkOTRuntimeContext } from './plugin';
+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) => Span;
+    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/throttle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 简易 djb2 字符串 hash。结果稳定、短（base36），足以区分常见 fingerprint 字符串组合。
+ * 不是密码学安全 hash，仅用于事件聚合分组场景。
+ */
+export declare const hashString: (input: string) => string;
+export interface ThrottleResult {
+    /** 是否允许本次上报 */
+    allowed: boolean;
+    /** 当前窗口内同 fingerprint 的总触发次数（含本次，含被丢弃次数），便于下游感知是否被节流 */
+    count: number;
+}
+/**
+ * 时间窗节流：同一 key 在 windowMs 窗口内最多允许 maxPerWindow 次通过；
+ * 超出则被拦截，但 `count` 仍累加，便于下游感知风暴规模。
+ *
+ * 长会话场景下避免 records 无限累积——按窗口长度节奏轻量清理一次过期 entry。
+ */
+export declare const createThrottle: (windowMs: number, maxPerWindow: number) => {
+    allow(key: string): ThrottleResult;
+};

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';