@blueking/open-telemetry 0.0.4 → 0.0.6

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+import { BkOpenTelemetry } from './core/sdk';
+export default BkOpenTelemetry;

package/dist/core/config.d.ts

@@ -0,0 +1,138 @@
+import type { BkOTPlugin } from './plugin';
+import type { Attributes } from '@opentelemetry/api';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+export interface BkOTAttributesConfig {
+    custom?: () => Attributes;
+    error?: () => Attributes;
+    metric?: () => Attributes;
+    page?: () => Attributes;
+}
+export type BkOTAttributeValue = boolean | number | string;
+export interface BkOTBatchConfig {
+    exportTimeoutMillis?: number;
+    maxExportBatchSize?: number;
+    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;
+    name: string;
+}
+export interface BkOTHttpBodyConfig {
+    maxBodySize?: number;
+    redact?: (payload: BkOTHttpBodyRedactPayload) => string;
+}
+export interface BkOTHttpBodyRedactPayload {
+    body: string;
+    contentType?: string;
+    method: string;
+    status?: number;
+    truncated: boolean;
+    type: 'request' | 'response';
+    url: string;
+}
+export interface BkOTInstrumentationsConfig {
+    documentLoad?: boolean;
+    fetch?: boolean;
+    userInteraction?: boolean | {
+        eventNames?: string[];
+    };
+    xhr?: boolean;
+}
+export interface BkOTRedactConfig {
+    attributes?: (attributes: Attributes) => Attributes;
+    url?: (url: string) => string;
+}
+export interface BkOTRumConfig extends BkOTInstrumentationsConfig {
+    cspViolation?: boolean;
+    device?: boolean | {
+        storageKey?: string;
+    };
+    httpBody?: BkOTHttpBodyConfig | boolean;
+    pageView?: boolean;
+    routeTiming?: boolean;
+    websocket?: boolean;
+    webVitals?: boolean;
+    blankScreen?: {
+        checkDelay?: number;
+        ignoreSelectors?: string[];
+        rootSelector?: string;
+        threshold?: number;
+    } | boolean;
+    error?: {
+        maxPerWindow?: number;
+        windowMs?: number;
+    } | boolean;
+    longTask?: {
+        threshold?: number;
+    } | boolean;
+    session?: {
+        inactivityMs?: number;
+        maxLifetimeMs?: number;
+        storageKey?: string;
+    } | boolean;
+}
+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'> {
+    autoStart: boolean;
+    debug: boolean;
+    enabled: boolean;
+    endpoint: string;
+    environment: string;
+    instrumentations: Instrumentation[];
+    logs: SignalExporterConfig;
+    metricIntervalMillis: number;
+    metrics: SignalExporterConfig;
+    plugins: BkOTPlugin[];
+    resourceAttributes: Attributes;
+    sampleRate: number;
+    spanProcessor: BkOTSpanProcessorMode;
+    traces: SignalExporterConfig;
+    getCustomAttributes: () => Attributes;
+    getErrorAttributes: () => Attributes;
+    getMetricAttributes: () => Attributes;
+    getPageAttributes: () => Attributes;
+    redactAttributes: (attributes: Attributes) => Attributes;
+    redactUrl: (url: string) => string;
+    commonInstrumentations: Required<Pick<BkOTInstrumentationsConfig, 'documentLoad' | 'fetch' | 'xhr'>> & {
+        userInteraction: BkOTInstrumentationsConfig['userInteraction'];
+    };
+    rum: Omit<Required<BkOTRumConfig>, 'documentLoad' | 'fetch' | 'httpBody' | 'userInteraction' | 'xhr'> & {
+        httpBody: false | Required<BkOTHttpBodyConfig>;
+    };
+}
+export interface SignalEndpointsConfig {
+    logs?: string;
+    metrics?: string;
+    traces?: string;
+}
+export interface SignalExporterConfig {
+    concurrencyLimit?: number;
+    endpoint: string;
+    headers?: Record<string, string>;
+    timeoutMillis?: number;
+}
+export type SignalExporterInputConfig = Partial<SignalExporterConfig>;
+export declare const normalizeConfig: (config: BkOTConfig) => NormalizedBkOTConfig;

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

@@ -0,0 +1,46 @@
+import type { NormalizedBkOTConfig } from './config';
+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;
+    name: string;
+    flush?: () => Promise<void> | void;
+    init: (context: BkOTRuntimeContext) => Promise<void> | void;
+    shutdown?: () => Promise<void> | void;
+}
+export interface BkOTRuntimeContext {
+    config: NormalizedBkOTConfig;
+    logger: Logger;
+    meter: Meter;
+    tracer: Tracer;
+    /** 对外提供的属性脱敏入口，所有插件在 emit 前都应过一次 */
+    applyRedact: (attributes: Attributes) => Attributes;
+    /** 包装 logger.emit，自动应用 redact 与 runtime attributes */
+    emitLog: (record: LogRecord) => void;
+    getRuntimeAttributes: () => Attributes;
+    setRuntimeAttributes: (attributes: Attributes) => void;
+    startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
+}
+/**
+ * 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: NormalizedBkOTConfig) => boolean;
+export declare const createPlugin: (plugin: BkOTPlugin) => BkOTPlugin;
+export declare class PluginManager {
+    private readonly plugins;
+    private startedPlugins;
+    constructor(plugins: BkOTPlugin[]);
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    start(context: BkOTRuntimeContext): Promise<void>;
+}

package/dist/core/processor.d.ts

@@ -0,0 +1,16 @@
+import type { NormalizedBkOTConfig } from './config';
+import type { Context } from '@opentelemetry/api';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+/**
+ * 包装 SpanProcessor，在 onEnd 阶段过滤指向自身上报 endpoint 的 span，
+ * 兜底防止 official fetch/xhr 拦截器对 OTel 自身请求产生回环 span。
+ */
+export declare class FilteringSpanProcessor implements SpanProcessor {
+    private readonly inner;
+    private readonly config;
+    constructor(inner: SpanProcessor, config: NormalizedBkOTConfig);
+    forceFlush(): Promise<void>;
+    onEnd(span: ReadableSpan): void;
+    onStart(span: Span, parentContext: Context): void;
+    shutdown(): Promise<void>;
+}

package/dist/core/route-observer.d.ts

@@ -0,0 +1,9 @@
+export interface RouteChangeEvent {
+    fromUrl: string;
+    source: RouteChangeSource;
+    toUrl: string;
+}
+export type RouteChangeSource = 'hashchange' | 'popstate' | 'pushState' | 'replaceState';
+type RouteChangeHandler = (event: RouteChangeEvent) => void;
+export declare const subscribeRouteChange: (handler: RouteChangeHandler) => () => void;
+export {};

package/dist/core/sampling.d.ts

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

package/dist/core/sdk.d.ts

@@ -0,0 +1,44 @@
+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, type BkOTStartSpanOptions } from './plugin';
+import type { LogRecord } from '@opentelemetry/api-logs';
+export interface BkOTInstance extends BkOTRuntimeContext {
+    flush: () => Promise<void>;
+    reportCustomEvent: (payload: BkOTCustomEventPayload) => void;
+    shutdown: () => Promise<void>;
+    start: () => Promise<void>;
+    use: (plugin: BkOTPlugin) => BkOTInstance;
+    useInstrumentation: (instrumentation: Instrumentation) => BkOTInstance;
+}
+export declare class BkOpenTelemetry implements BkOTInstance {
+    private readonly loggerProvider;
+    private readonly meterProvider;
+    private phase;
+    private readonly pluginManager;
+    private readonly plugins;
+    private readonly registeredInstrumentations;
+    private readonly runtimeAttributes;
+    private readonly sampled;
+    private readonly teardownCallbacks;
+    private readonly tracerProvider;
+    private assertBeforeStart;
+    readonly applyRedact: (attributes: Attributes) => Attributes;
+    readonly config: NormalizedBkOTConfig;
+    readonly emitLog: (record: LogRecord) => void;
+    readonly flush: () => Promise<void>;
+    readonly getRuntimeAttributes: () => {
+        [attributeKey: string]: import("@opentelemetry/api").AttributeValue | undefined;
+    };
+    readonly logger: BkOTRuntimeContext['logger'];
+    readonly meter: BkOTRuntimeContext['meter'];
+    readonly reportCustomEvent: ({ attributes, error, name }: BkOTCustomEventPayload) => void;
+    readonly setRuntimeAttributes: (attributes: Attributes) => 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);
+}

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

@@ -0,0 +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;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+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 BkOTPlugin, type BkOTRuntimeContext, createPlugin, type PluginManager } from './core/plugin';
+export { FilteringSpanProcessor } from './core/processor';
+export { BkOpenTelemetry, type BkOTInstance } from './core/sdk';
+export { createBlankScreenPlugin } from './plugins/blank-screen';
+export { createCommonInstrumentationsPlugin } from './plugins/common';
+export { createCspViolationPlugin } from './plugins/csp-violation';
+export { createDevicePlugin } from './plugins/device';
+export { createErrorPlugin } from './plugins/error';
+export { createHttpBodyPlugin } from './plugins/http-body';
+export { createLongTaskPlugin } from './plugins/long-task';
+export { createPageViewPlugin } from './plugins/page-view';
+export { createRouteTimingPlugin } from './plugins/route-timing';
+export { createSessionPlugin } from './plugins/session';
+export { createWebVitalsPlugin } from './plugins/web-vitals';
+export { createWebSocketPlugin } from './plugins/websocket';