@noony-serverless/core 0.3.3 → 0.4.0

package/build/core/logger.d.ts

@@ -1,13 +1,22 @@
+import type { Span, Context as OtelContext } from '@opentelemetry/api';
+import { type OTELLogContext } from '../utils/otel.helper';
 export interface LogOptions {
     structuredData?: boolean;
     [key: string]: boolean | string | number | object | undefined;
 }
+export interface LoggerConfig {
+    enableOTEL?: boolean;
+    structuredLogging?: boolean;
+    debugMode?: boolean;
+}
 declare class Logger {
     private logDataPool;
     private isDebugEnabled;
     private timestampCache;
     private lastTimestamp;
-    constructor();
+    private enableOTEL;
+    private otelContext?;
+    constructor(config?: LoggerConfig);
     /**
      * Performance optimized timestamp generation with caching
      * Cache timestamps for up to 1 second to reduce Date object creation
@@ -15,6 +24,7 @@ declare class Logger {
     private getTimestamp;
     /**
      * Optimized log method with object pooling and lazy evaluation
+     * Includes automatic OTEL trace/span ID injection when enabled
      */
     private log;
     /**
@@ -28,6 +38,83 @@ declare class Logger {
      * Performance monitoring method for internal framework use
      */
     logPerformance(operation: string, duration: number, metadata?: Record<string, unknown>): void;
+    /**
+     * Create a child logger with a specific span context
+     *
+     * This method creates a new logger instance that will automatically include
+     * the trace/span IDs from the provided span in all log entries.
+     *
+     * Useful for passing logger instances to services/functions that need
+     * to log within a specific span context.
+     *
+     * @param span - OpenTelemetry span to attach to logs
+     * @returns New logger instance with span context
+     *
+     * @example
+     * ```typescript
+     * import { trace } from '@opentelemetry/api';
+     * import { logger } from '@noony-serverless/core';
+     *
+     * const tracer = trace.getTracer('my-service');
+     * const span = tracer.startSpan('process-order');
+     *
+     * const spanLogger = logger.withSpan(span);
+     * spanLogger.info('Processing order'); // Includes span's trace/span IDs
+     *
+     * span.end();
+     * ```
+     */
+    withSpan(span: Span): Logger;
+    /**
+     * Create a child logger with a specific OTEL context
+     *
+     * This method creates a new logger instance that will automatically include
+     * trace/span IDs from the provided OTEL context in all log entries.
+     *
+     * Useful when working with OTEL Context propagation (e.g., Pub/Sub messages).
+     *
+     * @param context - OpenTelemetry context to extract span from
+     * @returns New logger instance with context
+     *
+     * @example
+     * ```typescript
+     * import { context, propagation } from '@opentelemetry/api';
+     * import { logger } from '@noony-serverless/core';
+     *
+     * // Extract context from Pub/Sub message
+     * const extractedContext = propagation.extract(
+     *   context.active(),
+     *   message.attributes
+     * );
+     *
+     * const contextLogger = logger.withOTEL(extractedContext);
+     * contextLogger.info('Processing message'); // Includes trace/span IDs
+     * ```
+     */
+    withOTEL(otelContext: OtelContext): Logger;
+    /**
+     * Create a child logger with custom OTEL context
+     *
+     * This method creates a new logger instance with manually specified
+     * trace/span IDs. Useful when you have trace context from external sources.
+     *
+     * @param context - OTEL log context with trace/span IDs
+     * @returns New logger instance with custom context
+     *
+     * @example
+     * ```typescript
+     * import { logger } from '@noony-serverless/core';
+     *
+     * const customLogger = logger.withContext({
+     *   traceId: '13ea7e3c2d3b4547baaa399062df1f2d',
+     *   spanId: '1234567890123456',
+     *   traceFlags: 1
+     * });
+     *
+     * customLogger.info('Custom trace context'); // Includes specified IDs
+     * ```
+     */
+    withContext(context: OTELLogContext): Logger;
     /**
      * Get logger statistics for monitoring
      */
@@ -35,6 +122,7 @@ declare class Logger {
         poolSize: number;
         maxPoolSize: number;
         debugEnabled: boolean;
+        otelEnabled: boolean;
     };
 }
 export declare const logger: Logger;

package/build/core/logger.js

@@ -1,6 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Logger = exports.logger = void 0;
+const otel_helper_1 = require("../utils/otel.helper");
+// Import trace for dynamic OTEL operations
+let trace = null;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    trace = require('@opentelemetry/api').trace;
+}
+catch {
+    // OTEL not available
+    trace = null;
+}
 // Performance optimization: Object pool for log data to reduce GC pressure
 class LogDataPool {
     pool = [];
@@ -45,12 +56,20 @@ class Logger {
     isDebugEnabled;
     timestampCache = '';
     lastTimestamp = 0;
-    constructor() {
+    enableOTEL;
+    otelContext;
+    constructor(config) {
         // Performance optimization: Cache debug mode check
         this.isDebugEnabled =
-            process.env.NODE_ENV === 'development' ||
-                process.env.DEBUG === 'true' ||
-                process.env.LOG_LEVEL === 'debug';
+            config?.debugMode ??
+                (process.env.NODE_ENV === 'development' ||
+                    process.env.DEBUG === 'true' ||
+                    process.env.LOG_LEVEL === 'debug');
+        // Enable OTEL integration if configured or in production
+        this.enableOTEL =
+            config?.enableOTEL ??
+                (process.env.OTEL_ENABLED === 'true' ||
+                    process.env.NODE_ENV === 'production');
     }
     /**
      * Performance optimized timestamp generation with caching
@@ -67,6 +86,7 @@ class Logger {
     }
     /**
      * Optimized log method with object pooling and lazy evaluation
+     * Includes automatic OTEL trace/span ID injection when enabled
      */
     log(level, message, options) {
         // Performance optimization: Early return for debug logs in production
@@ -78,7 +98,16 @@ class Logger {
         logData.timestamp = this.getTimestamp();
         logData.level = level;
         logData.message = message;
-        // Add options if provided
+        // Add OTEL context if enabled (automatic trace/span ID injection)
+        if (this.enableOTEL) {
+            // Use stored context if available (from withSpan/withOTEL)
+            // Otherwise, get from active span (createOTELMixin)
+            const otelContext = this.otelContext || (0, otel_helper_1.createOTELMixin)();
+            if (otelContext && Object.keys(otelContext).length > 0) {
+                Object.assign(logData, otelContext);
+            }
+        }
+        // Add options if provided (options override OTEL context if keys conflict)
         if (options) {
             Object.assign(logData, options);
         }
@@ -119,6 +148,107 @@ class Logger {
             });
         }
     }
+    /**
+     * Create a child logger with a specific span context
+     *
+     * This method creates a new logger instance that will automatically include
+     * the trace/span IDs from the provided span in all log entries.
+     *
+     * Useful for passing logger instances to services/functions that need
+     * to log within a specific span context.
+     *
+     * @param span - OpenTelemetry span to attach to logs
+     * @returns New logger instance with span context
+     *
+     * @example
+     * ```typescript
+     * import { trace } from '@opentelemetry/api';
+     * import { logger } from '@noony-serverless/core';
+     *
+     * const tracer = trace.getTracer('my-service');
+     * const span = tracer.startSpan('process-order');
+     *
+     * const spanLogger = logger.withSpan(span);
+     * spanLogger.info('Processing order'); // Includes span's trace/span IDs
+     *
+     * span.end();
+     * ```
+     */
+    withSpan(span) {
+        const childLogger = new Logger({
+            enableOTEL: this.enableOTEL,
+            debugMode: this.isDebugEnabled,
+        });
+        childLogger.otelContext = (0, otel_helper_1.getOTELContextFromSpan)(span);
+        return childLogger;
+    }
+    /**
+     * Create a child logger with a specific OTEL context
+     *
+     * This method creates a new logger instance that will automatically include
+     * trace/span IDs from the provided OTEL context in all log entries.
+     *
+     * Useful when working with OTEL Context propagation (e.g., Pub/Sub messages).
+     *
+     * @param context - OpenTelemetry context to extract span from
+     * @returns New logger instance with context
+     *
+     * @example
+     * ```typescript
+     * import { context, propagation } from '@opentelemetry/api';
+     * import { logger } from '@noony-serverless/core';
+     *
+     * // Extract context from Pub/Sub message
+     * const extractedContext = propagation.extract(
+     *   context.active(),
+     *   message.attributes
+     * );
+     *
+     * const contextLogger = logger.withOTEL(extractedContext);
+     * contextLogger.info('Processing message'); // Includes trace/span IDs
+     * ```
+     */
+    withOTEL(otelContext) {
+        if (!trace) {
+            // OTEL not available, return this logger unchanged
+            return this;
+        }
+        const span = trace.getSpan(otelContext);
+        if (!span) {
+            return this;
+        }
+        return this.withSpan(span);
+    }
+    /**
+     * Create a child logger with custom OTEL context
+     *
+     * This method creates a new logger instance with manually specified
+     * trace/span IDs. Useful when you have trace context from external sources.
+     *
+     * @param context - OTEL log context with trace/span IDs
+     * @returns New logger instance with custom context
+     *
+     * @example
+     * ```typescript
+     * import { logger } from '@noony-serverless/core';
+     *
+     * const customLogger = logger.withContext({
+     *   traceId: '13ea7e3c2d3b4547baaa399062df1f2d',
+     *   spanId: '1234567890123456',
+     *   traceFlags: 1
+     * });
+     *
+     * customLogger.info('Custom trace context'); // Includes specified IDs
+     * ```
+     */
+    withContext(context) {
+        const childLogger = new Logger({
+            enableOTEL: this.enableOTEL,
+            debugMode: this.isDebugEnabled,
+        });
+        childLogger.otelContext = context;
+        return childLogger;
+    }
     /**
      * Get logger statistics for monitoring
      */
@@ -127,6 +257,7 @@ class Logger {
             poolSize: this.logDataPool['pool'].length,
             maxPoolSize: this.logDataPool['maxPoolSize'],
             debugEnabled: this.isDebugEnabled,
+            otelEnabled: this.enableOTEL,
         };
     }
 }

package/build/core/telemetry/config.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Telemetry Configuration
+ *
+ * Centralized configuration for OpenTelemetry setup including:
+ * - Service resource attributes
+ * - Trace exporters and propagators
+ * - Metrics configuration
+ * - Platform-specific presets
+ */
+/**
+ * Span processor configuration for aggressive export in serverless environments
+ */
+export interface SpanProcessorConfig {
+    /**
+     * Maximum queue size before dropping spans
+     * @default 100
+     */
+    maxQueueSize?: number;
+    /**
+     * Maximum number of spans to export in a single batch
+     * For scale-to-zero environments, set to 1 for immediate export
+     * @default 1 (immediate export for serverless)
+     */
+    maxExportBatchSize?: number;
+    /**
+     * Delay in milliseconds between export attempts
+     * For scale-to-zero environments, use aggressive timing (100ms)
+     * @default 100 (very aggressive for Cloud Run)
+     */
+    scheduledDelayMillis?: number;
+    /**
+     * Timeout in milliseconds for export operations
+     * @default 30000 (30 seconds)
+     */
+    exportTimeoutMillis?: number;
+    /**
+     * Enable detailed export logging for debugging
+     * @default false
+     */
+    enableExportLogging?: boolean;
+}
+/**
+ * HTTP instrumentation configuration
+ */
+export interface HttpInstrumentationConfig {
+    /**
+     * Enable HTTP instrumentation
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Require parent span for incoming HTTP requests
+     * Set to false to create root spans for all requests
+     * @default false (creates root spans)
+     */
+    requireParentforIncomingSpans?: boolean;
+    /**
+     * Require parent span for outgoing HTTP requests
+     * @default false
+     */
+    requireParentforOutgoingSpans?: boolean;
+    /**
+     * Ignore health check endpoints
+     * @default true
+     */
+    ignoreHealthChecks?: boolean;
+    /**
+     * Trace OPTIONS requests (CORS preflight)
+     * @default false (reduces noise)
+     */
+    traceOptionsRequests?: boolean;
+    /**
+     * Custom URL patterns to ignore (regex strings)
+     */
+    ignoreUrls?: string[];
+}
+/**
+ * Auto-instrumentation configuration
+ */
+export interface InstrumentationConfig {
+    /**
+     * Enable HTTP instrumentation
+     * @default true
+     */
+    http?: boolean | HttpInstrumentationConfig;
+    /**
+     * Enable MongoDB instrumentation
+     * @default true
+     */
+    mongodb?: boolean;
+    /**
+     * Enable Pino logger instrumentation
+     * @default true
+     */
+    pino?: boolean;
+    /**
+     * Enable Fastify instrumentation
+     * WARNING: Should be disabled when using HTTP instrumentation to prevent duplicates
+     * @default false (prevents duplicate spans)
+     */
+    fastify?: boolean;
+    /**
+     * Enable DNS instrumentation
+     * @default false (reduces noise)
+     */
+    dns?: boolean;
+    /**
+     * Enable Net instrumentation
+     * @default false (reduces noise)
+     */
+    net?: boolean;
+    /**
+     * Enable FS instrumentation
+     * @default false (reduces noise)
+     */
+    fs?: boolean;
+}
+/**
+ * Metrics configuration
+ */
+export interface MetricsConfig {
+    /**
+     * Enable metrics collection
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Export interval in milliseconds
+     * @default 60000 (60 seconds)
+     */
+    exportIntervalMillis?: number;
+}
+/**
+ * Telemetry configuration interface
+ */
+export interface TelemetryConfig {
+    /**
+     * Service name for identification in traces
+     * @example 'order-service'
+     */
+    serviceName: string;
+    /**
+     * Service version for deployment tracking
+     * @example '2.1.0'
+     */
+    serviceVersion: string;
+    /**
+     * Deployment environment
+     * @example 'production', 'staging', 'development'
+     */
+    environment: string;
+    /**
+     * Trace exporters configuration
+     */
+    exporters?: {
+        traces?: Array<{
+            endpoint: string;
+            headers?: Record<string, string>;
+        }>;
+        metrics?: Array<{
+            endpoint: string;
+            headers?: Record<string, string>;
+        }>;
+    };
+    /**
+     * Sampling configuration for traces
+     */
+    sampling?: {
+        ratio: number;
+    };
+    /**
+     * Propagation format configuration
+     * Controls which trace context formats to support
+     */
+    propagation?: {
+        /**
+         * Enable Cloud Trace propagation for Google Cloud Platform
+         * Uses X-Cloud-Trace-Context header format
+         * @default true when running on GCP
+         */
+        cloudTrace?: boolean;
+        /**
+         * Enable W3C Trace Context propagation
+         * Uses traceparent/tracestate header format
+         * @default true
+         */
+        w3c?: boolean;
+        /**
+         * Additional custom propagators
+         */
+        custom?: string[];
+    };
+    /**
+     * Span processor configuration for aggressive export
+     * Optimized for scale-to-zero serverless environments
+     */
+    spanProcessor?: SpanProcessorConfig;
+    /**
+     * Auto-instrumentation configuration
+     * Controls which libraries are automatically instrumented
+     */
+    instrumentation?: InstrumentationConfig;
+    /**
+     * Metrics configuration
+     */
+    metrics?: MetricsConfig;
+    /**
+     * Auto-initialize SDK at module load
+     * When true, OTEL SDK initializes automatically when telemetry.config.ts is imported
+     * @default false (manual initialization via middleware)
+     */
+    autoInitialize?: boolean;
+}
+/**
+ * Platform-specific telemetry presets
+ */
+export declare const TelemetryPresets: {
+    /**
+     * Google Cloud Platform preset with Cloud Trace integration
+     */
+    readonly GCP: {
+        readonly propagation: {
+            readonly cloudTrace: true;
+            readonly w3c: true;
+        };
+    };
+    /**
+     * Cloud Run optimized preset with aggressive span export
+     * Prevents data loss during scale-to-zero container termination
+     */
+    readonly CLOUD_RUN: {
+        readonly propagation: {
+            readonly cloudTrace: true;
+            readonly w3c: true;
+        };
+        readonly spanProcessor: {
+            readonly maxQueueSize: 100;
+            readonly maxExportBatchSize: 1;
+            readonly scheduledDelayMillis: 100;
+            readonly exportTimeoutMillis: 30000;
+            readonly enableExportLogging: true;
+        };
+        readonly instrumentation: {
+            readonly http: {
+                readonly enabled: true;
+                readonly requireParentforIncomingSpans: false;
+                readonly ignoreHealthChecks: true;
+                readonly traceOptionsRequests: false;
+            };
+            readonly mongodb: true;
+            readonly pino: true;
+            readonly fastify: false;
+            readonly dns: false;
+            readonly net: false;
+            readonly fs: false;
+        };
+        readonly metrics: {
+            readonly enabled: true;
+            readonly exportIntervalMillis: 60000;
+        };
+        readonly autoInitialize: true;
+    };
+    /**
+     * New Relic APM preset
+     */
+    readonly NEW_RELIC: {
+        readonly propagation: {
+            readonly cloudTrace: false;
+            readonly w3c: true;
+        };
+    };
+    /**
+     * Datadog APM preset
+     */
+    readonly DATADOG: {
+        readonly propagation: {
+            readonly cloudTrace: false;
+            readonly w3c: true;
+        };
+    };
+    /**
+     * Standard OpenTelemetry preset (OTLP)
+     */
+    readonly OTLP: {
+        readonly propagation: {
+            readonly cloudTrace: false;
+            readonly w3c: true;
+        };
+    };
+    /**
+     * Jaeger local development preset
+     */
+    readonly JAEGER_LOCAL: {
+        readonly exporters: {
+            readonly traces: readonly [{
+                readonly endpoint: "http://localhost:4318/v1/traces";
+            }];
+        };
+        readonly propagation: {
+            readonly cloudTrace: false;
+            readonly w3c: true;
+        };
+    };
+    /**
+     * Development preset (console output only)
+     */
+    readonly DEVELOPMENT: {
+        readonly propagation: {
+            readonly cloudTrace: false;
+            readonly w3c: true;
+        };
+    };
+    /**
+     * Disabled preset (no telemetry)
+     */
+    readonly DISABLED: {
+        readonly propagation: {
+            readonly cloudTrace: false;
+            readonly w3c: false;
+        };
+    };
+};
+/**
+ * Detect if running on Google Cloud Platform
+ */
+export declare function isRunningOnGCP(): boolean;
+/**
+ * Get default telemetry configuration based on environment
+ */
+export declare function getDefaultTelemetryConfig(): Partial<TelemetryConfig>;
+//# sourceMappingURL=config.d.ts.map