observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/observability/instrumentation.d.ts

@@ -0,0 +1,158 @@
+/**
+ * OpenTelemetry SDK Self-Instrumentation
+ *
+ * Opt-in OTel instrumentation for tracing observability-toolkit's own operations.
+ * Disabled by default - enable via OTEL_ENABLED=true environment variable.
+ *
+ * Architecture (A1 fix):
+ * State is encapsulated in InstrumentationManager class. A default singleton is
+ * used for production, while tests can create isolated instances. Module-level
+ * exports delegate to the default instance for backward compatibility.
+ *
+ * Environment Variables:
+ * - OTEL_ENABLED: Enable instrumentation (default: false)
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP collector URL (required when enabled)
+ * - OTEL_SERVICE_NAME: Service name (default: observability-toolkit)
+ */
+import type { Tracer, Span } from '@opentelemetry/api';
+/** Configuration for instrumentation initialization */
+export interface InstrumentationConfig {
+    enabled?: boolean;
+    endpoint?: string;
+    serviceName?: string;
+    /** Enable metrics export via OTLP. Defaults to true when OTel is enabled. */
+    metricsEnabled?: boolean;
+    /** Enable logs export via OTLP. Defaults to true when OTel is enabled. */
+    logsEnabled?: boolean;
+}
+/** Initialization status for M1-B4 fix */
+export type InitializationStatus = 'pending' | 'initializing' | 'ready' | 'disabled' | 'failed';
+/** Result of initialization for M1-B4 fix */
+export interface InitializationResult {
+    status: InitializationStatus;
+    error?: string;
+    retryCount?: number;
+}
+/** Span kind enum values matching OTel semantic conventions */
+export type SpanKind = 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+/**
+ * InstrumentationManager encapsulates all OTel instrumentation state.
+ * A1 fix: Eliminates global mutable state for better testability.
+ *
+ * Usage:
+ * - Production: Use the default singleton via module-level exports
+ * - Testing: Create isolated instances with `new InstrumentationManager()`
+ */
+export declare class InstrumentationManager {
+    private tracer;
+    private sdkInstance;
+    private otelApi;
+    private initialized;
+    private initRetryCount;
+    private initRetryTimer;
+    private initStatus;
+    private initError;
+    private initCompleteResolve;
+    private initCompletePromise;
+    /**
+     * Check if instrumentation is enabled based on environment or config
+     */
+    isEnabled(config?: InstrumentationConfig): boolean;
+    /**
+     * Initialize the OpenTelemetry SDK for self-instrumentation.
+     * Only initializes if enabled and endpoint is configured.
+     * Safe to call multiple times - subsequent calls are no-ops.
+     *
+     * M1-B4 fix: Use waitForInitialization() to await completion including retries.
+     */
+    initialize(config?: InstrumentationConfig): Promise<void>;
+    /**
+     * Get the tracer instance, or null if instrumentation is disabled
+     */
+    getTracer(): Tracer | null;
+    /**
+     * M1-B4 fix: Wait for initialization to complete (including all retries).
+     * Returns immediately if initialization hasn't started or is already complete.
+     */
+    waitForInitialization(): Promise<InitializationResult>;
+    /**
+     * M1-B4 fix: Get current initialization status synchronously.
+     */
+    getInitializationStatus(): InitializationResult;
+    /**
+     * Gracefully shutdown the instrumentation SDK.
+     * Flushes any pending spans and releases resources.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Reset all state. For testing only.
+     * @internal
+     */
+    reset(): void;
+    /**
+     * Set the OTel API reference for sync span operations.
+     * @internal
+     */
+    setOtelApi(api: typeof import('@opentelemetry/api')): void;
+    /**
+     * Execute an async function wrapped in a span.
+     * When instrumentation is disabled, executes the function directly without overhead.
+     */
+    withSpan<T>(name: string, attributes: Record<string, string | number | boolean | undefined> | (() => Record<string, string | number | boolean | undefined>), fn: (span: Span | null) => Promise<T>, kind?: SpanKind): Promise<T>;
+    /**
+     * Execute a sync function wrapped in a span.
+     * When instrumentation is disabled, executes the function directly without overhead.
+     */
+    withSpanSync<T>(name: string, attributes: Record<string, string | number | boolean | undefined> | (() => Record<string, string | number | boolean | undefined>), fn: (span: Span | null) => T, kind?: SpanKind): T;
+}
+/**
+ * Check if instrumentation is enabled based on environment or config
+ */
+export declare function isInstrumentationEnabled(config?: InstrumentationConfig): boolean;
+/**
+ * Initialize the OpenTelemetry SDK for self-instrumentation.
+ * Only initializes if enabled and endpoint is configured.
+ * Safe to call multiple times - subsequent calls are no-ops.
+ */
+export declare function initializeInstrumentation(config?: InstrumentationConfig): Promise<void>;
+/**
+ * Get the tracer instance, or null if instrumentation is disabled
+ */
+export declare function getTracer(): Tracer | null;
+/**
+ * M1-B4 fix: Wait for initialization to complete (including all retries).
+ */
+export declare function waitForInitialization(): Promise<InitializationResult>;
+/**
+ * M1-B4 fix: Get current initialization status synchronously.
+ */
+export declare function getInitializationStatus(): InitializationResult;
+/**
+ * Gracefully shutdown the instrumentation SDK.
+ */
+export declare function shutdownInstrumentation(): Promise<void>;
+/**
+ * Reset instrumentation state for testing.
+ * @internal
+ */
+export declare function resetInstrumentationForTesting(): void;
+/**
+ * Set the OTel API reference for sync span operations.
+ * @internal
+ */
+export declare function setOtelApi(api: typeof import('@opentelemetry/api')): void;
+/**
+ * Execute an async function wrapped in a span.
+ */
+export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean | undefined> | (() => Record<string, string | number | boolean | undefined>), fn: (span: Span | null) => Promise<T>, kind?: SpanKind): Promise<T>;
+/**
+ * Execute a sync function wrapped in a span.
+ */
+export declare function withSpanSync<T>(name: string, attributes: Record<string, string | number | boolean | undefined> | (() => Record<string, string | number | boolean | undefined>), fn: (span: Span | null) => T, kind?: SpanKind): T;
+/**
+ * Get the default InstrumentationManager instance.
+ * Useful for advanced use cases or testing.
+ */
+export declare function getDefaultManager(): InstrumentationManager;
+export { emitEvaluationEvent, type EmitEvaluationEventOptions } from './evaluation-events.js';
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/lib/observability/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAkB,MAAM,oBAAoB,CAAC;AAkBvE,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,0CAA0C;AAC1C,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEhG,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAElF;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAkD;IACrE,OAAO,CAAC,OAAO,CAAoD;IACnE,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,mBAAmB,CAAyD;IACpF,OAAO,CAAC,mBAAmB,CAA8C;IAEzE;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO;IAOlD;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2O/D;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;;OAGG;IACG,qBAAqB,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAO5D;;OAEG;IACH,uBAAuB,IAAI,oBAAoB;IAQ/C;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B/B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAgBb;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,cAAc,oBAAoB,CAAC,GAAG,IAAI;IAI1D;;;OAGG;IACG,QAAQ,CAAC,CAAC,EACd,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,EACjI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,IAAI,GAAE,QAAqB,GAC1B,OAAO,CAAC,CAAC,CAAC;IA6Bb;;;OAGG;IACH,YAAY,CAAC,CAAC,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,EACjI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,CAAC,EAC5B,IAAI,GAAE,QAAqB,GAC1B,CAAC;CA8BL;AAYD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAEhF;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAE3E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAE9D;AAED;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,oBAAoB,CAAC,GAAG,IAAI,CAEzE;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,EACjI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,IAAI,GAAE,QAAqB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,EACjI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,CAAC,EAC5B,IAAI,GAAE,QAAqB,GAC1B,CAAC,CAEH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,sBAAsB,CAE1D;AAKD,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/lib/observability/instrumentation.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=instrumentation.integration.test.d.ts.map

package/dist/lib/observability/instrumentation.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.integration.test.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/instrumentation.integration.test.ts"],"names":[],"mappings":""}