@atrim/instrument-node 1.0.0

package/target/dist/index.d.cts

@@ -0,0 +1,548 @@
+import { Effect } from 'effect';
+import { NodeSDKConfiguration, NodeSDK } from '@opentelemetry/sdk-node';
+import { Instrumentation } from '@opentelemetry/instrumentation';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { ConfigLoaderOptions, InstrumentationConfig, PatternMatcher } from '@atrim/instrument-core';
+export { ConfigLoaderOptions, InstrumentationConfig, PatternConfig, PatternMatcher, getPatternMatcher, loadConfig, shouldInstrumentSpan } from '@atrim/instrument-core';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { Context, Span as Span$1 } from '@opentelemetry/api';
+
+/**
+ * OTLP Exporter Factory
+ *
+ * Creates and configures OTLP trace exporters with smart defaults
+ */
+
+interface OtlpExporterOptions {
+    /**
+     * OTLP endpoint URL
+     * Defaults to OTEL_EXPORTER_OTLP_ENDPOINT or http://localhost:4318/v1/traces
+     */
+    endpoint?: string;
+    /**
+     * Custom headers to send with requests
+     * Useful for authentication, custom routing, etc.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Create an OTLP trace exporter with smart defaults
+ *
+ * Priority for endpoint:
+ * 1. Explicit endpoint option
+ * 2. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT environment variable
+ * 3. OTEL_EXPORTER_OTLP_ENDPOINT environment variable
+ * 4. Default: http://localhost:4318/v1/traces
+ */
+declare function createOtlpExporter(options?: OtlpExporterOptions): OTLPTraceExporter;
+/**
+ * Get the OTLP endpoint that would be used with current configuration
+ *
+ * Useful for debugging and logging
+ */
+declare function getOtlpEndpoint(options?: OtlpExporterOptions): string;
+
+/**
+ * NodeSDK Initialization
+ *
+ * Provides comprehensive OpenTelemetry SDK initialization with smart defaults
+ */
+
+interface SdkInitializationOptions extends ConfigLoaderOptions {
+    /**
+     * OTLP exporter configuration
+     */
+    otlp?: OtlpExporterOptions;
+    /**
+     * Service name
+     * If not provided, auto-detects from OTEL_SERVICE_NAME or package.json
+     */
+    serviceName?: string;
+    /**
+     * Service version
+     * If not provided, auto-detects from OTEL_SERVICE_VERSION or package.json
+     */
+    serviceVersion?: string;
+    /**
+     * Enable auto-instrumentation
+     * Default: auto-detected based on your runtime and framework
+     * - true: Enables Express, HTTP, and other common instrumentations
+     * - false: Disables all auto-instrumentation (manual spans only)
+     * - undefined: Smart detection (checks for Effect-TS usage)
+     */
+    autoInstrument?: boolean;
+    /**
+     * Custom instrumentations to add
+     * These are added in addition to auto-instrumentations (if enabled)
+     */
+    instrumentations?: Instrumentation[];
+    /**
+     * Advanced: Full NodeSDK configuration override
+     * Provides complete control over SDK initialization
+     */
+    sdk?: Partial<NodeSDKConfiguration>;
+    /**
+     * Disable automatic shutdown handler registration
+     * Default: false (automatic shutdown is enabled)
+     */
+    disableAutoShutdown?: boolean;
+}
+/**
+ * Get the current SDK instance
+ */
+declare function getSdkInstance(): NodeSDK | null;
+/**
+ * Shutdown the SDK
+ */
+declare function shutdownSdk(): Promise<void>;
+/**
+ * Reset SDK instance (useful for testing)
+ */
+declare function resetSdk(): void;
+
+/**
+ * Typed error hierarchy for @atrim/instrumentation
+ *
+ * These errors use Effect's Data.TaggedError for typed error handling
+ * with proper discriminated unions.
+ */
+declare const ConfigError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigError";
+} & Readonly<A>;
+/**
+ * Base error for configuration-related failures
+ */
+declare class ConfigError extends ConfigError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ConfigUrlError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigUrlError";
+} & Readonly<A>;
+/**
+ * Error when fetching configuration from a URL fails
+ */
+declare class ConfigUrlError extends ConfigUrlError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ConfigValidationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigValidationError";
+} & Readonly<A>;
+/**
+ * Error when configuration validation fails (invalid YAML, schema mismatch)
+ */
+declare class ConfigValidationError extends ConfigValidationError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ConfigFileError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigFileError";
+} & Readonly<A>;
+/**
+ * Error when reading configuration from a file fails
+ */
+declare class ConfigFileError extends ConfigFileError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ServiceDetectionError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ServiceDetectionError";
+} & Readonly<A>;
+/**
+ * Error when service detection fails (package.json not found, invalid format)
+ */
+declare class ServiceDetectionError extends ServiceDetectionError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const InitializationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "InitializationError";
+} & Readonly<A>;
+/**
+ * Error when OpenTelemetry SDK initialization fails
+ */
+declare class InitializationError extends InitializationError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ExportError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ExportError";
+} & Readonly<A>;
+/**
+ * Error when span export fails (e.g., ECONNREFUSED to collector)
+ */
+declare class ExportError extends ExportError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ShutdownError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ShutdownError";
+} & Readonly<A>;
+/**
+ * Error when shutting down the SDK fails
+ */
+declare class ShutdownError extends ShutdownError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+
+/**
+ * Public API for standard OpenTelemetry usage
+ *
+ * This module provides the main entry point for complete OpenTelemetry
+ * initialization including NodeSDK, OTLP export, and pattern-based filtering.
+ *
+ * Available in two flavors:
+ * - Effect API (primary): For typed error handling and composability
+ * - Promise API (backward compatible): For traditional async/await usage
+ */
+
+/**
+ * Initialize OpenTelemetry instrumentation with complete SDK setup
+ *
+ * This function provides a single-line initialization for OpenTelemetry:
+ * - Loads instrumentation.yaml configuration
+ * - Creates and configures OTLP exporter
+ * - Sets up pattern-based span filtering
+ * - Initializes NodeSDK with auto-instrumentations
+ * - Registers graceful shutdown handlers
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Explicit config object (options.config)
+ * 2. Environment variable (ATRIM_INSTRUMENTATION_CONFIG)
+ * 3. Explicit path/URL (options.configPath or options.configUrl)
+ * 4. Project root file (./instrumentation.yaml)
+ * 5. Default config (built-in defaults)
+ *
+ * OTLP endpoint priority:
+ * 1. options.otlp.endpoint
+ * 2. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT environment variable
+ * 3. OTEL_EXPORTER_OTLP_ENDPOINT environment variable
+ * 4. Default: http://localhost:4318/v1/traces
+ *
+ * Service name priority:
+ * 1. options.serviceName
+ * 2. OTEL_SERVICE_NAME environment variable
+ * 3. package.json name field
+ * 4. Default: 'unknown-service'
+ *
+ * @param options - Initialization options
+ * @returns The initialized NodeSDK instance
+ *
+ * @example
+ * ```typescript
+ * // Zero-config initialization (recommended)
+ * await initializeInstrumentation()
+ * // Auto-detects everything from env vars and package.json
+ *
+ * // With custom OTLP endpoint
+ * await initializeInstrumentation({
+ *   otlp: {
+ *     endpoint: 'https://otel-collector.company.com:4318'
+ *   }
+ * })
+ *
+ * // With custom service name
+ * await initializeInstrumentation({
+ *   serviceName: 'my-api-service',
+ *   serviceVersion: '2.0.0'
+ * })
+ *
+ * // Disable auto-instrumentation (manual spans only)
+ * await initializeInstrumentation({
+ *   autoInstrument: false
+ * })
+ *
+ * // With custom config file
+ * await initializeInstrumentation({
+ *   configPath: './config/custom-instrumentation.yaml'
+ * })
+ *
+ * // With remote config URL
+ * await initializeInstrumentation({
+ *   configUrl: 'https://config.company.com/instrumentation.yaml',
+ *   cacheTimeout: 300_000 // 5 minutes
+ * })
+ *
+ * // Advanced: Full control
+ * await initializeInstrumentation({
+ *   otlp: {
+ *     endpoint: process.env.CUSTOM_ENDPOINT,
+ *     headers: { 'x-api-key': 'secret' }
+ *   },
+ *   serviceName: 'my-service',
+ *   autoInstrument: true,
+ *   instrumentations: [], // custom instrumentations
+ *   sdk: {
+ *     // Additional NodeSDK configuration
+ *   }
+ * })
+ * ```
+ */
+declare function initializeInstrumentation(options?: SdkInitializationOptions): Promise<NodeSDK | null>;
+/**
+ * Legacy initialization function for pattern-only mode
+ *
+ * This function only initializes pattern matching without setting up the NodeSDK.
+ * Use this if you want to manually configure OpenTelemetry while still using
+ * pattern-based filtering.
+ *
+ * @deprecated Use initializeInstrumentation() instead for complete setup
+ */
+declare function initializePatternMatchingOnly(options?: SdkInitializationOptions): Promise<void>;
+/**
+ * Initialize OpenTelemetry instrumentation (Effect version)
+ *
+ * Provides typed error handling and composability with Effect ecosystem.
+ * All errors are returned in the error channel, not thrown.
+ *
+ * @param options - Initialization options
+ * @returns Effect that yields the initialized NodeSDK or null
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { initializeInstrumentationEffect } from '@atrim/instrumentation'
+ *
+ * // Basic usage
+ * const program = initializeInstrumentationEffect()
+ *
+ * await Effect.runPromise(program)
+ *
+ * // With error handling
+ * const program = initializeInstrumentationEffect().pipe(
+ *   Effect.catchTag('ConfigError', (error) => {
+ *     console.error('Config error:', error.reason)
+ *     return Effect.succeed(null)
+ *   }),
+ *   Effect.catchTag('InitializationError', (error) => {
+ *     console.error('Init error:', error.reason)
+ *     return Effect.succeed(null)
+ *   })
+ * )
+ *
+ * await Effect.runPromise(program)
+ *
+ * // With custom options
+ * const program = initializeInstrumentationEffect({
+ *   otlp: { endpoint: 'https://otel.company.com:4318' },
+ *   serviceName: 'my-service'
+ * })
+ * ```
+ */
+declare const initializeInstrumentationEffect: (options?: SdkInitializationOptions) => Effect.Effect<NodeSDK | null, InitializationError | ConfigError>;
+/**
+ * Initialize pattern matching only (Effect version)
+ *
+ * Use this if you want manual OpenTelemetry setup with pattern filtering.
+ *
+ * @param options - Configuration options
+ * @returns Effect that yields void
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { initializePatternMatchingOnlyEffect } from '@atrim/instrumentation'
+ *
+ * const program = initializePatternMatchingOnlyEffect({
+ *   configPath: './instrumentation.yaml'
+ * }).pipe(
+ *   Effect.catchAll((error) => {
+ *     console.error('Pattern matching setup failed:', error.reason)
+ *     return Effect.succeed(undefined)
+ *   })
+ * )
+ *
+ * await Effect.runPromise(program)
+ * ```
+ */
+declare const initializePatternMatchingOnlyEffect: (options?: SdkInitializationOptions) => Effect.Effect<void, ConfigError>;
+
+/**
+ * Service Detection Utilities
+ *
+ * Auto-detects service name and version from environment variables and package.json
+ * Uses Effect for typed error handling and composability
+ */
+
+interface ServiceInfo {
+    name: string;
+    version?: string | undefined;
+}
+/**
+ * Detect service name and version (Effect version)
+ *
+ * Priority order:
+ * 1. OTEL_SERVICE_NAME environment variable
+ * 2. package.json name field
+ * 3. Fallback to 'unknown-service'
+ *
+ * Version:
+ * 1. OTEL_SERVICE_VERSION environment variable
+ * 2. package.json version field
+ * 3. undefined (not set)
+ *
+ * @returns Effect that yields ServiceInfo or ServiceDetectionError
+ */
+declare const detectServiceInfo: Effect.Effect<ServiceInfo, ServiceDetectionError>;
+/**
+ * Get service name with fallback (Effect version)
+ *
+ * Never fails - returns 'unknown-service' if detection fails
+ */
+declare const getServiceName: Effect.Effect<string, never>;
+/**
+ * Get service version with fallback (Effect version)
+ *
+ * Never fails - returns undefined if detection fails
+ */
+declare const getServiceVersion: Effect.Effect<string | undefined, never>;
+/**
+ * Get service info with fallback (Effect version)
+ *
+ * Never fails - returns default ServiceInfo if detection fails
+ */
+declare const getServiceInfoWithFallback: Effect.Effect<ServiceInfo, never>;
+/**
+ * Detect service name and version (Promise version)
+ *
+ * @deprecated Use `detectServiceInfo` Effect API for better error handling
+ * @returns Promise that resolves to ServiceInfo with fallback
+ */
+declare function detectServiceInfoAsync(): Promise<ServiceInfo>;
+/**
+ * Get service name with fallback (Promise version)
+ *
+ * @deprecated Use `getServiceName` Effect API
+ */
+declare function getServiceNameAsync(): Promise<string>;
+/**
+ * Get service version if available (Promise version)
+ *
+ * @deprecated Use `getServiceVersion` Effect API
+ */
+declare function getServiceVersionAsync(): Promise<string | undefined>;
+
+/**
+ * OpenTelemetry SpanProcessor for pattern-based filtering
+ *
+ * This processor filters spans based on configured patterns before they are exported.
+ * It wraps another processor (typically BatchSpanProcessor) and only forwards spans
+ * that match the instrumentation patterns.
+ */
+
+/**
+ * SpanProcessor that filters spans based on pattern configuration
+ *
+ * This processor sits in the processing pipeline and decides whether a span
+ * should be forwarded to the next processor (for export) or dropped.
+ *
+ * Usage:
+ * ```typescript
+ * const exporter = new OTLPTraceExporter()
+ * const batchProcessor = new BatchSpanProcessor(exporter)
+ * const patternProcessor = new PatternSpanProcessor(config, batchProcessor)
+ *
+ * const sdk = new NodeSDK({
+ *   spanProcessor: patternProcessor
+ * })
+ * ```
+ */
+declare class PatternSpanProcessor implements SpanProcessor {
+    private matcher;
+    private wrappedProcessor;
+    constructor(config: InstrumentationConfig, wrappedProcessor: SpanProcessor);
+    /**
+     * Called when a span is started
+     *
+     * We check if the span should be instrumented here. If not, we can mark it
+     * to be dropped later in onEnd().
+     */
+    onStart(span: Span, parentContext: Context): void;
+    /**
+     * Called when a span is ended
+     *
+     * This is where we make the final decision on whether to export the span.
+     */
+    onEnd(span: ReadableSpan): void;
+    /**
+     * Shutdown the processor
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush any pending spans
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Get the pattern matcher (for debugging/testing)
+     */
+    getPatternMatcher(): PatternMatcher;
+}
+
+/**
+ * Standard OpenTelemetry span helpers (no Effect dependency)
+ *
+ * These helpers work with any OpenTelemetry span and don't require Effect-TS.
+ */
+
+/**
+ * Set multiple attributes on a span at once
+ */
+declare function setSpanAttributes(span: Span$1, attributes: Record<string, string | number | boolean>): void;
+/**
+ * Record an exception on a span with optional context
+ */
+declare function recordException(span: Span$1, error: Error, context?: Record<string, string | number | boolean>): void;
+/**
+ * Mark a span as successful (OK status)
+ */
+declare function markSpanSuccess(span: Span$1): void;
+/**
+ * Mark a span as failed with an error message
+ */
+declare function markSpanError(span: Span$1, message?: string): void;
+/**
+ * Helper for HTTP request spans
+ */
+declare function annotateHttpRequest(span: Span$1, method: string, url: string, statusCode?: number): void;
+/**
+ * Helper for database query spans
+ */
+declare function annotateDbQuery(span: Span$1, system: string, statement: string, table?: string): void;
+/**
+ * Helper for cache operation spans
+ */
+declare function annotateCacheOperation(span: Span$1, operation: 'get' | 'set' | 'delete' | 'clear', key: string, hit?: boolean): void;
+
+/**
+ * Test utilities for handling shutdown errors during testing
+ */
+/**
+ * Suppress ECONNREFUSED errors during shutdown in test environments
+ *
+ * This function installs error handlers that ignore connection refused errors
+ * when the OpenTelemetry SDK tries to export spans during shutdown. This is
+ * expected behavior when collectors are stopped before child processes finish.
+ *
+ * @example
+ * ```typescript
+ * import { suppressShutdownErrors } from '@atrim/instrumentation/test-utils'
+ *
+ * // Call at the start of your main function
+ * suppressShutdownErrors()
+ * ```
+ */
+declare function suppressShutdownErrors(): void;
+
+export { ConfigError, ConfigFileError, ConfigUrlError, ConfigValidationError, ExportError, InitializationError, type OtlpExporterOptions, PatternSpanProcessor, type SdkInitializationOptions, ServiceDetectionError, type ServiceInfo, ShutdownError, annotateCacheOperation, annotateDbQuery, annotateHttpRequest, createOtlpExporter, detectServiceInfoAsync as detectServiceInfo, detectServiceInfo as detectServiceInfoEffect, getOtlpEndpoint, getSdkInstance, getServiceInfoWithFallback, getServiceNameAsync as getServiceName, getServiceName as getServiceNameEffect, getServiceVersionAsync as getServiceVersion, getServiceVersion as getServiceVersionEffect, initializeInstrumentation, initializeInstrumentationEffect, initializePatternMatchingOnly, initializePatternMatchingOnlyEffect, markSpanError, markSpanSuccess, recordException, resetSdk, setSpanAttributes, shutdownSdk, suppressShutdownErrors };