@noony-serverless/core 0.3.4 → 0.4.1

package/build/core/telemetry/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Telemetry Module
+ *
+ * Provides OpenTelemetry integration for the Noony framework with:
+ * - Extensible provider system (OTEL, New Relic, Datadog, Console, Noop)
+ * - Auto-detection from environment variables
+ * - Graceful degradation when configuration is missing
+ * - Zero-configuration local development support
+ *
+ * @example
+ * import { OpenTelemetryMiddleware } from '@noony-serverless/core';
+ *
+ * const handler = new Handler()
+ *   .use(new OpenTelemetryMiddleware()) // Auto-detects provider
+ *   .handle(async (context) => {
+ *     // Your business logic
+ *   });
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultTelemetryConfig = exports.isRunningOnGCP = exports.TelemetryPresets = void 0;
+// Core interfaces and types
+__exportStar(require("./provider"), exports);
+// Configuration and presets (explicit exports to avoid conflict)
+var config_1 = require("./config");
+Object.defineProperty(exports, "TelemetryPresets", { enumerable: true, get: function () { return config_1.TelemetryPresets; } });
+Object.defineProperty(exports, "isRunningOnGCP", { enumerable: true, get: function () { return config_1.isRunningOnGCP; } });
+Object.defineProperty(exports, "getDefaultTelemetryConfig", { enumerable: true, get: function () { return config_1.getDefaultTelemetryConfig; } });
+// Provider implementations
+__exportStar(require("./providers"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,203 @@
+import { Context } from '../core';
+/**
+ * Validation result from TelemetryProvider.validate()
+ */
+export interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Generic span interface that works across different telemetry providers
+ * This provides a common interface for OTEL, New Relic, Datadog, etc.
+ */
+export interface GenericSpan {
+    setAttributes(attributes: Record<string, unknown>): void;
+    recordException(error: Error): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    end(): void;
+}
+/**
+ * Base interface for telemetry providers
+ *
+ * This interface allows custom implementations for different APM platforms:
+ * - Standard OpenTelemetry SDK
+ * - New Relic Agent
+ * - Datadog Tracer
+ * - Custom implementations
+ *
+ * All providers must implement validation to ensure graceful degradation
+ * when configuration is missing or invalid.
+ */
+export interface TelemetryProvider {
+    /**
+     * Provider name for identification
+     * Examples: 'opentelemetry', 'newrelic', 'datadog', 'console', 'noop'
+     */
+    readonly name: string;
+    /**
+     * Validate provider configuration before initialization
+     *
+     * This method checks:
+     * - Required environment variables are set
+     * - Required npm packages are installed
+     * - Configuration is valid (e.g., valid URLs)
+     *
+     * @returns Validation result with optional reason if invalid
+     *
+     * @example
+     * const result = await provider.validate();
+     * if (!result.valid) {
+     *   console.warn(`Provider validation failed: ${result.reason}`);
+     *   // Fall back to NoopProvider
+     * }
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Initialize the telemetry provider with configuration
+     *
+     * This is called once at application startup, not per-request.
+     * Providers should set up SDK, exporters, and any global configuration.
+     *
+     * @param config Telemetry configuration
+     * @throws Should not throw - errors should be caught and logged internally
+     *
+     * @example
+     * await provider.initialize({
+     *   serviceName: 'order-service',
+     *   serviceVersion: '1.0.0',
+     *   environment: 'production'
+     * });
+     */
+    initialize(config: TelemetryConfig): Promise<void>;
+    /**
+     * Create a span for the current request
+     *
+     * This is called in the middleware `before` hook for each request.
+     * Returns undefined if provider is not ready or span creation fails.
+     *
+     * @param context The Noony request context
+     * @returns Span object or undefined if span creation fails
+     *
+     * @example
+     * const span = provider.createSpan(context);
+     * if (span) {
+     *   span.setAttributes({ 'user.id': context.user?.id });
+     *   context.businessData.set('otel_span', span);
+     * }
+     */
+    createSpan(context: Context<unknown, unknown>): GenericSpan | undefined;
+    /**
+     * Record a metric (histogram, counter, gauge, etc.)
+     *
+     * @param name Metric name (e.g., 'http.request.duration')
+     * @param value Metric value
+     * @param attributes Optional metric attributes/tags
+     *
+     * @example
+     * provider.recordMetric('http.request.duration', 123.45, {
+     *   'http.method': 'POST',
+     *   'http.status_code': 200
+     * });
+     */
+    recordMetric(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /**
+     * Log with trace correlation
+     *
+     * Logs should include trace and span IDs when available for correlation.
+     *
+     * @param level Log level (info, error, warn, debug)
+     * @param message Log message
+     * @param attributes Additional log attributes
+     *
+     * @example
+     * provider.log('error', 'Request failed', {
+     *   'error.type': 'ValidationError',
+     *   'user.id': userId
+     * });
+     */
+    log(level: string, message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Check if provider is initialized and ready to use
+     *
+     * @returns True if provider is ready, false otherwise
+     *
+     * @example
+     * if (!provider.isReady()) {
+     *   console.warn('Provider not ready, skipping telemetry');
+     * }
+     */
+    isReady(): boolean;
+    /**
+     * Shutdown the provider gracefully
+     *
+     * Called during application shutdown to flush any pending telemetry data.
+     *
+     * @example
+     * process.on('SIGTERM', async () => {
+     *   await provider.shutdown();
+     *   process.exit(0);
+     * });
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Telemetry configuration interface
+ */
+export interface TelemetryConfig {
+    /** Enable telemetry (defaults to true) */
+    enabled?: boolean;
+    /** Service name for telemetry */
+    serviceName: string;
+    /** Service version (optional) */
+    serviceVersion?: string;
+    /** Environment (e.g., 'production', 'staging', 'development') */
+    environment?: string;
+    /** Exporter configurations */
+    exporters?: {
+        traces?: OTLPExporterConfig[];
+        metrics?: OTLPExporterConfig[];
+        logs?: OTLPExporterConfig[];
+    };
+    /** Sampling configuration */
+    sampling?: {
+        /** Sampling ratio (0.0 to 1.0) */
+        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[];
+    };
+}
+/**
+ * OTLP Exporter configuration
+ */
+export interface OTLPExporterConfig {
+    /** Exporter endpoint URL */
+    endpoint: string;
+    /** Optional headers (e.g., API keys) */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds (optional) */
+    timeout?: number;
+}
+//# sourceMappingURL=provider.d.ts.map

package/build/core/telemetry/provider.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=provider.js.map

package/build/core/telemetry/providers/console-provider.d.ts

@@ -0,0 +1,54 @@
+import { Context } from '../../core';
+import { TelemetryProvider, ValidationResult, GenericSpan, TelemetryConfig } from '../provider';
+/**
+ * Console Telemetry Provider
+ *
+ * Logs all telemetry data to the console for local development and debugging.
+ * This provider is useful for:
+ * 1. Local development without external telemetry infrastructure
+ * 2. Debugging telemetry integration
+ * 3. Testing span creation and attributes
+ *
+ * Auto-selected when NODE_ENV=development and no OTEL endpoint is configured.
+ *
+ * @example
+ * // Auto-detected in development
+ * NODE_ENV=development
+ *
+ * // Or explicitly configured
+ * const provider = new ConsoleProvider();
+ * await provider.initialize({ serviceName: 'my-service' });
+ */
+export declare class ConsoleProvider implements TelemetryProvider {
+    readonly name = "console";
+    private enabled;
+    /**
+     * Console provider is always valid (useful for local testing)
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Initialize console provider
+     */
+    initialize(config: TelemetryConfig): Promise<void>;
+    /**
+     * Create a console span that logs to stdout
+     */
+    createSpan(context: Context<unknown, unknown>): GenericSpan | undefined;
+    /**
+     * Log metric to console
+     */
+    recordMetric(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /**
+     * Log message to console with level
+     */
+    log(level: string, message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Console provider is always ready if enabled
+     */
+    isReady(): boolean;
+    /**
+     * Shutdown console provider
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=console-provider.d.ts.map

package/build/core/telemetry/providers/console-provider.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleProvider = void 0;
+/**
+ * Console Telemetry Provider
+ *
+ * Logs all telemetry data to the console for local development and debugging.
+ * This provider is useful for:
+ * 1. Local development without external telemetry infrastructure
+ * 2. Debugging telemetry integration
+ * 3. Testing span creation and attributes
+ *
+ * Auto-selected when NODE_ENV=development and no OTEL endpoint is configured.
+ *
+ * @example
+ * // Auto-detected in development
+ * NODE_ENV=development
+ *
+ * // Or explicitly configured
+ * const provider = new ConsoleProvider();
+ * await provider.initialize({ serviceName: 'my-service' });
+ */
+class ConsoleProvider {
+    name = 'console';
+    enabled = false;
+    /**
+     * Console provider is always valid (useful for local testing)
+     */
+    async validate() {
+        return { valid: true };
+    }
+    /**
+     * Initialize console provider
+     */
+    async initialize(config) {
+        this.enabled = config.enabled !== false;
+        if (this.enabled) {
+            console.log('[Telemetry] Console provider initialized');
+            console.log('[Telemetry] Service:', config.serviceName);
+            console.log('[Telemetry] Version:', config.serviceVersion || 'unknown');
+            console.log('[Telemetry] Environment:', config.environment || 'development');
+        }
+    }
+    /**
+     * Create a console span that logs to stdout
+     */
+    createSpan(context) {
+        if (!this.enabled)
+            return undefined;
+        const spanData = {
+            startTime: Date.now(),
+            method: context.req.method,
+            path: context.req.path || context.req.url,
+            requestId: context.requestId,
+        };
+        console.log('[Telemetry] 🟢 Span started:', spanData);
+        return {
+            setAttributes: (attrs) => {
+                console.log('[Telemetry] 📊 Span attributes:', attrs);
+            },
+            recordException: (error) => {
+                console.error('[Telemetry] ❌ Exception:', {
+                    message: error.message,
+                    name: error.name,
+                    stack: error.stack,
+                });
+            },
+            setStatus: (status) => {
+                const statusIcon = status.code === 0 ? '✅' : '⚠️';
+                console.log(`[Telemetry] ${statusIcon} Span status:`, status);
+            },
+            end: () => {
+                const duration = Date.now() - spanData.startTime;
+                console.log('[Telemetry] 🔴 Span ended:', {
+                    ...spanData,
+                    duration: `${duration}ms`,
+                });
+            },
+        };
+    }
+    /**
+     * Log metric to console
+     */
+    recordMetric(name, value, attributes) {
+        if (!this.enabled)
+            return;
+        console.log('[Telemetry] 📈 Metric:', {
+            name,
+            value,
+            attributes,
+        });
+    }
+    /**
+     * Log message to console with level
+     */
+    log(level, message, attributes) {
+        if (!this.enabled)
+            return;
+        const levelIcon = {
+            info: 'ℹ️',
+            error: '❌',
+            warn: '⚠️',
+            debug: '🔍',
+        }[level] || '📝';
+        console.log(`[Telemetry] ${levelIcon} Log [${level}]:`, message, attributes);
+    }
+    /**
+     * Console provider is always ready if enabled
+     */
+    isReady() {
+        return this.enabled;
+    }
+    /**
+     * Shutdown console provider
+     */
+    async shutdown() {
+        if (this.enabled) {
+            console.log('[Telemetry] Console provider shutdown');
+        }
+        this.enabled = false;
+    }
+}
+exports.ConsoleProvider = ConsoleProvider;
+//# sourceMappingURL=console-provider.js.map

package/build/core/telemetry/providers/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Telemetry Providers
+ *
+ * This module exports all available telemetry providers.
+ * Providers can be used directly or auto-detected by OpenTelemetryMiddleware.
+ */
+export { NoopProvider } from './noop-provider';
+export { ConsoleProvider } from './console-provider';
+export { OpenTelemetryProvider } from './opentelemetry-provider';
+//# sourceMappingURL=index.d.ts.map

package/build/core/telemetry/providers/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Telemetry Providers
+ *
+ * This module exports all available telemetry providers.
+ * Providers can be used directly or auto-detected by OpenTelemetryMiddleware.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenTelemetryProvider = exports.ConsoleProvider = exports.NoopProvider = void 0;
+var noop_provider_1 = require("./noop-provider");
+Object.defineProperty(exports, "NoopProvider", { enumerable: true, get: function () { return noop_provider_1.NoopProvider; } });
+var console_provider_1 = require("./console-provider");
+Object.defineProperty(exports, "ConsoleProvider", { enumerable: true, get: function () { return console_provider_1.ConsoleProvider; } });
+var opentelemetry_provider_1 = require("./opentelemetry-provider");
+Object.defineProperty(exports, "OpenTelemetryProvider", { enumerable: true, get: function () { return opentelemetry_provider_1.OpenTelemetryProvider; } });
+// Note: New Relic and Datadog providers are optional and can be added when needed
+// export { NewRelicProvider } from './newrelic-provider';
+// export { DatadogProvider } from './datadog-provider';
+//# sourceMappingURL=index.js.map

package/build/core/telemetry/providers/noop-provider.d.ts

@@ -0,0 +1,51 @@
+import { Context } from '../../core';
+import { TelemetryProvider, ValidationResult, GenericSpan, TelemetryConfig } from '../provider';
+/**
+ * Noop (No-operation) Telemetry Provider
+ *
+ * This provider does nothing and is used as:
+ * 1. Fallback when other providers fail validation
+ * 2. Default when telemetry is disabled (NODE_ENV=test)
+ * 3. Placeholder when no configuration is provided
+ *
+ * It implements all TelemetryProvider methods as no-ops to ensure
+ * the application continues to work even when telemetry fails.
+ *
+ * @example
+ * // Automatically used as fallback
+ * const provider = new NoopProvider();
+ * await provider.initialize({ serviceName: 'test' });
+ * const span = provider.createSpan(context); // Returns undefined
+ */
+export declare class NoopProvider implements TelemetryProvider {
+    readonly name = "noop";
+    /**
+     * Noop provider is always valid
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * No-op initialization
+     */
+    initialize(_config: TelemetryConfig): Promise<void>;
+    /**
+     * Always returns undefined (no span created)
+     */
+    createSpan(_context: Context<unknown, unknown>): GenericSpan | undefined;
+    /**
+     * No-op metric recording
+     */
+    recordMetric(_name: string, _value: number, _attributes?: Record<string, unknown>): void;
+    /**
+     * No-op logging
+     */
+    log(_level: string, _message: string, _attributes?: Record<string, unknown>): void;
+    /**
+     * Always ready (does nothing, so always ready)
+     */
+    isReady(): boolean;
+    /**
+     * No-op shutdown
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=noop-provider.d.ts.map

package/build/core/telemetry/providers/noop-provider.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopProvider = void 0;
+/**
+ * Noop (No-operation) Telemetry Provider
+ *
+ * This provider does nothing and is used as:
+ * 1. Fallback when other providers fail validation
+ * 2. Default when telemetry is disabled (NODE_ENV=test)
+ * 3. Placeholder when no configuration is provided
+ *
+ * It implements all TelemetryProvider methods as no-ops to ensure
+ * the application continues to work even when telemetry fails.
+ *
+ * @example
+ * // Automatically used as fallback
+ * const provider = new NoopProvider();
+ * await provider.initialize({ serviceName: 'test' });
+ * const span = provider.createSpan(context); // Returns undefined
+ */
+class NoopProvider {
+    name = 'noop';
+    /**
+     * Noop provider is always valid
+     */
+    async validate() {
+        return { valid: true };
+    }
+    /**
+     * No-op initialization
+     */
+    async initialize(_config) {
+        // Do nothing
+    }
+    /**
+     * Always returns undefined (no span created)
+     */
+    createSpan(_context) {
+        return undefined;
+    }
+    /**
+     * No-op metric recording
+     */
+    recordMetric(_name, _value, _attributes) {
+        // Do nothing
+    }
+    /**
+     * No-op logging
+     */
+    log(_level, _message, _attributes) {
+        // Do nothing
+    }
+    /**
+     * Always ready (does nothing, so always ready)
+     */
+    isReady() {
+        return true;
+    }
+    /**
+     * No-op shutdown
+     */
+    async shutdown() {
+        // Do nothing
+    }
+}
+exports.NoopProvider = NoopProvider;
+//# sourceMappingURL=noop-provider.js.map

package/build/core/telemetry/providers/opentelemetry-provider.d.ts

@@ -0,0 +1,102 @@
+import { Context } from '../../core';
+import { TelemetryProvider, ValidationResult, GenericSpan, TelemetryConfig } from '../provider';
+/**
+ * Standard OpenTelemetry SDK 2.0 Provider
+ *
+ * Implements telemetry using the official OpenTelemetry JavaScript SDK.
+ * Supports OTLP exporters for traces, metrics, and logs.
+ *
+ * Requirements:
+ * - Node.js >= 18.19.0 or >= 20.6.0
+ * - OTEL_EXPORTER_OTLP_ENDPOINT environment variable
+ * - @opentelemetry/sdk-node and related packages installed
+ *
+ * Auto-selected when OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ *
+ * @example
+ * // Environment setup
+ * OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
+ *
+ * // Usage
+ * const provider = new OpenTelemetryProvider();
+ * const validation = await provider.validate();
+ * if (validation.valid) {
+ *   await provider.initialize({
+ *     serviceName: 'my-service',
+ *     serviceVersion: '1.0.0'
+ *   });
+ * }
+ */
+export declare class OpenTelemetryProvider implements TelemetryProvider {
+    readonly name = "opentelemetry";
+    private sdk?;
+    private tracer?;
+    private meter?;
+    private ready;
+    /**
+     * Validate OpenTelemetry configuration
+     *
+     * Checks:
+     * 1. OTEL_EXPORTER_OTLP_ENDPOINT is set
+     * 2. Endpoint is a valid URL
+     * 3. Required packages are available (checked lazily during init)
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Initialize OpenTelemetry SDK
+     *
+     * Sets up:
+     * - Resource attributes (service name, version, environment)
+     * - OTLP trace exporter
+     * - Composite propagator (W3C + Cloud Trace)
+     * - Tracer and Meter providers
+     */
+    initialize(config: TelemetryConfig): Promise<void>;
+    /**
+     * Create an OpenTelemetry span
+     *
+     * Creates a SERVER span with HTTP semantic conventions.
+     * Returns undefined if provider is not ready.
+     */
+    createSpan(context: Context<unknown, unknown>): GenericSpan | undefined;
+    /**
+     * Record a metric as a histogram
+     */
+    recordMetric(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /**
+     * Log with trace correlation
+     *
+     * Adds trace and span IDs to log output when available.
+     */
+    log(level: string, message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Check if OpenTelemetry provider is ready
+     */
+    isReady(): boolean;
+    /**
+     * Shutdown OpenTelemetry SDK
+     *
+     * Flushes pending telemetry data and closes exporters.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Create composite propagator based on configuration
+     *
+     * Supports:
+     * - W3C Trace Context (traceparent/tracestate)
+     * - Google Cloud Trace Context (X-Cloud-Trace-Context)
+     *
+     * When running on GCP, both formats are enabled by default for compatibility.
+     * This allows trace IDs to be synchronized between Cloud Run Load Balancer
+     * and your application.
+     *
+     * @param config Telemetry configuration
+     * @returns Configured propagator (W3C, Cloud Trace, or Composite)
+     */
+    private createPropagator;
+    /**
+     * Detect if running on Google Cloud Platform
+     */
+    private isRunningOnGCP;
+}
+//# sourceMappingURL=opentelemetry-provider.d.ts.map