@engjts/nexus 0.1.0

package/src/advanced/observability/AlertManager.ts

@@ -0,0 +1,109 @@
+import { AlertChannelAdapterRegistry, AlertChannelAdapter, AlertDefinition as BaseAlertDefinition } from './adapters';
+import { AlertingOptions } from './types';
+
+/**
+ * Alert manager for monitoring alerts with adapter-based channel system
+ */
+export class AlertManager {
+    private options: AlertingOptions;
+    private alertHistory: Array<{ alert: string; timestamp: number; value: any; }> = [];
+    private alertState: Map<string, { lastTriggered: number; count: number; }> = new Map();
+    private adapterRegistry: AlertChannelAdapterRegistry;
+    private channelConfigs: Record<string, any> = {};
+
+    constructor(options: AlertingOptions = {}) {
+        this.options = options;
+        this.adapterRegistry = new AlertChannelAdapterRegistry();
+
+        // Store channel configurations
+        if (options.channels) {
+            this.channelConfigs = options.channels as Record<string, any>;
+        }
+    }
+
+    /**
+     * Register a custom alert channel adapter
+     */
+    registerAdapter(name: string, adapter: AlertChannelAdapter): void {
+        this.adapterRegistry.register(name, adapter);
+    }
+
+    /**
+     * Get the adapter registry
+     */
+    getAdapterRegistry(): AlertChannelAdapterRegistry {
+        return this.adapterRegistry;
+    }
+
+    async checkAndTrigger(alertName: string, currentValue: number) {
+        const alert = this.options.alerts?.find(a => a.name === alertName);
+        if (!alert) return;
+
+        const threshold = alert.threshold ?? 0;
+        const shouldTrigger = this.evaluateCondition(alert.condition, currentValue, threshold);
+
+        if (shouldTrigger) {
+            const state = this.alertState.get(alertName) || { lastTriggered: 0, count: 0 };
+            const now = Date.now();
+
+            // Prevent alert flooding (minimum 1 minute between same alerts)
+            if (now - state.lastTriggered > 60000) {
+                state.lastTriggered = now;
+                state.count++;
+                this.alertState.set(alertName, state);
+
+                this.alertHistory.push({ alert: alertName, timestamp: now, value: currentValue });
+
+                await this.sendAlert(alert, currentValue);
+            }
+        }
+    }
+
+    private evaluateCondition(condition: string, value: number, threshold: number): boolean {
+        // Simple condition parsing: "error_rate > 0.05" or "p95_duration > 1000"
+        if (condition.includes('>')) {
+            return value > threshold;
+        }
+        if (condition.includes('<')) {
+            return value < threshold;
+        }
+        if (condition.includes('>=')) {
+            return value >= threshold;
+        }
+        if (condition.includes('<=')) {
+            return value <= threshold;
+        }
+        return false;
+    }
+
+    private async sendAlert(alert: BaseAlertDefinition, value: any) {
+        for (const channelName of alert.channels) {
+            try {
+                const adapter = this.adapterRegistry.get(channelName);
+                if (!adapter) {
+                    console.warn(`No adapter registered for channel: ${channelName}`);
+                    continue;
+                }
+
+                const config = this.channelConfigs[channelName];
+                if (!config) {
+                    console.warn(`No configuration for channel: ${channelName}`);
+                    continue;
+                }
+
+                if (!adapter.validate(config)) {
+                    console.warn(`Invalid configuration for channel: ${channelName}`);
+                    continue;
+                }
+
+                await adapter.send(alert, value, config);
+            } catch (error) {
+                console.error(`Failed to send alert to ${channelName}:`, error);
+            }
+        }
+    }
+
+    getAlertHistory() {
+        return [...this.alertHistory];
+    }
+}

package/src/advanced/observability/MetricRegistry.ts

@@ -0,0 +1,151 @@
+import { LabeledMetric, HistogramRecord, GaugeRecord, MetricDefinition } from './types';
+
+/**
+ * Enhanced metric registry with labels, gauges, and proper Prometheus formatting
+ */
+export class MetricRegistry {
+    private counters: LabeledMetric<number> = new Map();
+    private histograms: LabeledMetric<HistogramRecord> = new Map();
+    private gauges: LabeledMetric<GaugeRecord> = new Map();
+    private definitions: Map<string, MetricDefinition> = new Map();
+    private defaultLabels: Record<string, string> = {};
+
+    setDefaultLabels(labels: Record<string, string>) {
+        this.defaultLabels = labels;
+    }
+
+    define(definition: MetricDefinition) {
+        this.definitions.set(definition.name, definition);
+    }
+
+    private formatLabels(labels: Record<string, string> = {}): string {
+        const allLabels = { ...this.defaultLabels, ...labels };
+        const entries = Object.entries(allLabels);
+        if (entries.length === 0) return '';
+        return '{' + entries.map(([k, v]) => `${k}="${v}"`).join(',') + '}';
+    }
+
+    private getKey(name: string, labels: Record<string, string> = {}): string {
+        return name + this.formatLabels(labels);
+    }
+
+    increment(name: string, value: number = 1, labels: Record<string, string> = {}) {
+        const key = this.getKey(name, labels);
+        this.counters.set(key, (this.counters.get(key) || 0) + value);
+    }
+
+    decrement(name: string, value: number = 1, labels: Record<string, string> = {}) {
+        this.increment(name, -value, labels);
+    }
+
+    gauge(name: string, value: number, labels: Record<string, string> = {}) {
+        const key = this.getKey(name, labels);
+        this.gauges.set(key, { value, timestamp: Date.now() });
+    }
+
+    observe(
+        name: string,
+        value: number,
+        labels: Record<string, string> = {},
+        buckets: number[] = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+    ) {
+        const key = this.getKey(name, labels);
+        const existing = this.histograms.get(key);
+        const record: HistogramRecord = existing || {
+            count: 0,
+            sum: 0,
+            buckets: buckets.map(() => 0),
+            bucketBoundaries: buckets
+        };
+
+        record.count += 1;
+        record.sum += value;
+        record.buckets = record.buckets.map((bucketValue, index) => {
+            return bucketValue + (value <= record.bucketBoundaries[index] ? 1 : 0);
+        });
+
+        this.histograms.set(key, record);
+    }
+
+    toPrometheus(): string {
+        const lines: string[] = [];
+        const processedMetrics = new Set<string>();
+
+        // Counters
+        for (const [key, value] of this.counters.entries()) {
+            const baseName = key.split('{')[0];
+            if (!processedMetrics.has(`counter:${baseName}`)) {
+                const def = this.definitions.get(baseName);
+                if (def?.help) lines.push(`# HELP ${baseName} ${def.help}`);
+                lines.push(`# TYPE ${baseName} counter`);
+                processedMetrics.add(`counter:${baseName}`);
+            }
+            lines.push(`${key} ${value}`);
+        }
+
+        // Gauges
+        for (const [key, record] of this.gauges.entries()) {
+            const baseName = key.split('{')[0];
+            if (!processedMetrics.has(`gauge:${baseName}`)) {
+                const def = this.definitions.get(baseName);
+                if (def?.help) lines.push(`# HELP ${baseName} ${def.help}`);
+                lines.push(`# TYPE ${baseName} gauge`);
+                processedMetrics.add(`gauge:${baseName}`);
+            }
+            lines.push(`${key} ${record.value}`);
+        }
+
+        // Histograms
+        for (const [key, record] of this.histograms.entries()) {
+            const baseName = key.split('{')[0];
+            const labelsPart = key.includes('{') ? key.slice(key.indexOf('{')) : '';
+            const labelsInner = labelsPart.slice(1, -1);
+
+            if (!processedMetrics.has(`histogram:${baseName}`)) {
+                const def = this.definitions.get(baseName);
+                if (def?.help) lines.push(`# HELP ${baseName} ${def.help}`);
+                lines.push(`# TYPE ${baseName} histogram`);
+                processedMetrics.add(`histogram:${baseName}`);
+            }
+
+            record.bucketBoundaries.forEach((boundary, index) => {
+                const bucketLabels = labelsInner ? `${labelsInner},le="${boundary}"` : `le="${boundary}"`;
+                lines.push(`${baseName}_bucket{${bucketLabels}} ${record.buckets[index]}`);
+            });
+
+            const infLabels = labelsInner ? `${labelsInner},le="+Inf"` : `le="+Inf"`;
+            lines.push(`${baseName}_bucket{${infLabels}} ${record.count}`);
+
+            if (labelsPart) {
+                lines.push(`${baseName}_sum${labelsPart} ${record.sum}`);
+                lines.push(`${baseName}_count${labelsPart} ${record.count}`);
+            } else {
+                lines.push(`${baseName}_sum ${record.sum}`);
+                lines.push(`${baseName}_count ${record.count}`);
+            }
+        }
+
+        return lines.join('\n');
+    }
+
+    snapshot() {
+        return {
+            counters: Object.fromEntries(this.counters),
+            gauges: Object.fromEntries(
+                Array.from(this.gauges.entries()).map(([k, v]) => [k, v.value])
+            ),
+            histograms: Object.fromEntries(
+                Array.from(this.histograms.entries()).map(([k, v]) => [
+                    k,
+                    { count: v.count, sum: v.sum, mean: v.count > 0 ? v.sum / v.count : 0 }
+                ])
+            )
+        };
+    }
+
+    reset() {
+        this.counters.clear();
+        this.histograms.clear();
+        this.gauges.clear();
+    }
+}

package/src/advanced/observability/ObservabilityCenter.ts

@@ -0,0 +1,304 @@
+import { performance } from 'perf_hooks';
+import { Context, Response } from '../../core/types';
+import { AlertManager } from './AlertManager';
+import { APMManager } from './APMManager';
+import { MetricRegistry } from './MetricRegistry';
+import { StructuredLogger } from './StructuredLogger';
+import { TracingManager } from './TracingManager';
+import { ObservabilityOptions, Span, LogEntry } from './types';
+
+/**
+ * Enhanced Observability Center with full APM, tracing, logging, and alerting
+ */
+
+
+export class ObservabilityCenter {
+    private metrics: MetricRegistry = new MetricRegistry();
+    private tracing?: TracingManager;
+    private logger: StructuredLogger;
+    private apm?: APMManager;
+    private alertManager?: AlertManager;
+    private options: ObservabilityOptions;
+
+    constructor(options: ObservabilityOptions = {}) {
+        this.options = options;
+
+        // Initialize logger
+        this.logger = new StructuredLogger(options.logging);
+
+        // Initialize tracing if enabled
+        if (options.tracing?.enabled) {
+            this.tracing = new TracingManager(options.tracing);
+        }
+
+        // Initialize APM if enabled
+        if (options.apm?.enabled) {
+            this.apm = new APMManager(options.apm);
+        }
+
+        // Initialize alerting if enabled
+        if (options.alerting?.enabled) {
+            this.alertManager = new AlertManager(options.alerting);
+        }
+
+        // Set default labels for metrics
+        if (options.metrics?.defaultLabels) {
+            this.metrics.setDefaultLabels(options.metrics.defaultLabels);
+        }
+
+        // Register custom metrics
+        if (options.metrics?.custom) {
+            for (const def of options.metrics.custom) {
+                this.metrics.define(def);
+            }
+        }
+
+        // Register default metrics
+        this.metrics.define({ name: 'http_requests_total', type: 'counter', help: 'Total HTTP requests' });
+        this.metrics.define({ name: 'http_request_duration_seconds', type: 'histogram', help: 'HTTP request duration in seconds' });
+        this.metrics.define({ name: 'http_request_size_bytes', type: 'histogram', help: 'HTTP request size in bytes' });
+        this.metrics.define({ name: 'http_response_size_bytes', type: 'histogram', help: 'HTTP response size in bytes' });
+    }
+
+    /**
+     * Record an HTTP request
+     */
+    recordRequest(ctx: Context, response: Response, durationMs: number, error?: Error) {
+        const labels = {
+            method: ctx.method,
+            path: this.normalizePath(ctx.path),
+            status: String(response.statusCode)
+        };
+
+        if (this.options.metrics?.enabled) {
+            this.metrics.increment('http_requests_total', 1, labels);
+            this.metrics.observe('http_request_duration_seconds', durationMs / 1000, labels);
+        }
+
+        // Log request if enabled
+        if (this.options.logging?.requests?.enabled) {
+            const excludePaths = this.options.logging.requests.excludePaths ?? [];
+            if (!excludePaths.some(p => ctx.path.startsWith(p))) {
+                this.logger.info('HTTP Request', {
+                    method: ctx.method,
+                    path: ctx.path,
+                    status: response.statusCode,
+                    duration: `${durationMs.toFixed(2)}ms`,
+                    ...(this.options.logging.requests.includeBody && ctx.body ? { body: ctx.body } : {})
+                }, ctx.correlationId);
+            }
+        }
+
+        // Check for slow requests and alert
+        if (this.alertManager && durationMs > (this.options.apm?.slowQueryThreshold ?? 1000)) {
+            this.alertManager.checkAndTrigger('High Response Time', durationMs);
+        }
+
+        // Record error if present
+        if (error) {
+            this.logger.error('Request error', error, { path: ctx.path, method: ctx.method }, ctx.correlationId);
+            this.metrics.increment('http_errors_total', 1, { method: ctx.method, path: this.normalizePath(ctx.path) });
+        }
+    }
+
+    /**
+     * Start a new trace span
+     */
+    startSpan(name: string, ctx?: Context): Span | undefined {
+        if (!this.tracing) return undefined;
+
+        let traceContext: { traceId?: string; parentSpanId?: string; } = {};
+        if (ctx?.headers) {
+            traceContext = this.tracing.extractContext(ctx.headers as Record<string, string | string[] | undefined>);
+        }
+
+        const shouldSample = ctx ? this.tracing.shouldSample(ctx.path) : true;
+        if (!shouldSample) return undefined;
+
+        return this.tracing.startSpan(name, traceContext.parentSpanId, traceContext.traceId);
+    }
+
+    /**
+     * End a trace span
+     */
+    endSpan(spanId: string, status: 'ok' | 'error' = 'ok', error?: Error) {
+        this.tracing?.endSpan(spanId, status, error);
+    }
+
+    /**
+     * Add event to a span
+     */
+    addSpanEvent(spanId: string, name: string, attributes?: Record<string, any>) {
+        this.tracing?.addEvent(spanId, name, attributes);
+    }
+
+    /**
+     * Set span attributes
+     */
+    setSpanAttributes(spanId: string, attributes: Record<string, any>) {
+        this.tracing?.setAttributes(spanId, attributes);
+    }
+
+    /**
+     * Record a database query for APM
+     */
+    recordQuery(query: string, durationMs: number) {
+        this.apm?.recordQuery(query, durationMs);
+    }
+
+    /**
+     * Get the structured logger
+     */
+    getLogger(): StructuredLogger {
+        return this.logger;
+    }
+
+    /**
+     * Metrics endpoint handler
+     */
+    metricsHandler() {
+        return (ctx: Context): Response => {
+            const format = this.options.metrics?.format ?? 'prometheus';
+            if (format === 'json') {
+                return ctx.json(this.metrics.snapshot());
+            }
+            return {
+                statusCode: 200,
+                headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+                body: this.metrics.toPrometheus()
+            };
+        };
+    }
+
+    /**
+     * Health check handler
+     */
+    healthHandler() {
+        return async (_ctx: Context): Promise<Response> => {
+            const checks = this.options.health?.checks ?? [];
+            const results: Record<string, { status: 'up' | 'down'; details?: Record<string, any>; duration?: number; }> = {};
+
+            let overallStatus: 'up' | 'down' = 'up';
+
+            for (const check of checks) {
+                const start = performance.now();
+                try {
+                    const timeout = check.timeout ?? 5000;
+                    const result = await Promise.race([
+                        check.check(),
+                        new Promise<never>((_, reject) => setTimeout(() => reject(new Error('Health check timeout')), timeout)
+                        )
+                    ]);
+                    const duration = performance.now() - start;
+
+                    results[check.name] = { ...result, duration };
+                    if (result.status === 'down' && check.critical !== false) {
+                        overallStatus = 'down';
+                    }
+                } catch (error: any) {
+                    const duration = performance.now() - start;
+                    if (check.critical !== false) {
+                        overallStatus = 'down';
+                    }
+                    results[check.name] = {
+                        status: 'down',
+                        duration,
+                        details: { message: error?.message ?? 'Health check failed' }
+                    };
+                }
+            }
+
+            const statusCode = overallStatus === 'up' ? 200 : 503;
+
+            return {
+                statusCode,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    status: overallStatus,
+                    timestamp: new Date().toISOString(),
+                    checks: results
+                })
+            };
+        };
+    }
+
+    /**
+     * Get all traces
+     */
+    getTraces(): Span[] {
+        return this.tracing?.getSpans() ?? [];
+    }
+
+    /**
+     * Get slow queries from APM
+     */
+    getSlowQueries() {
+        return this.apm?.getSlowQueries() ?? [];
+    }
+
+    /**
+     * Get memory statistics
+     */
+    getMemoryStats() {
+        return this.apm?.getMemoryStats();
+    }
+
+    /**
+     * Get alert history
+     */
+    getAlertHistory() {
+        return this.alertManager?.getAlertHistory() ?? [];
+    }
+
+    /**
+     * Get the alert manager
+     */
+    getAlertManager() {
+        return this.alertManager;
+    }
+
+    /**
+     * Get logs with optional filtering
+     */
+    getLogs(filter?: { level?: LogEntry['level']; since?: number; limit?: number; }) {
+        return this.logger.getLogs(filter);
+    }
+
+    /**
+     * Increment a custom counter metric
+     */
+    incrementCounter(name: string, value: number = 1, labels: Record<string, string> = {}) {
+        this.metrics.increment(name, value, labels);
+    }
+
+    /**
+     * Set a gauge metric value
+     */
+    setGauge(name: string, value: number, labels: Record<string, string> = {}) {
+        this.metrics.gauge(name, value, labels);
+    }
+
+    /**
+     * Observe a histogram metric
+     */
+    observeHistogram(name: string, value: number, labels: Record<string, string> = {}) {
+        this.metrics.observe(name, value, labels);
+    }
+
+    /**
+     * Cleanup resources
+     */
+    shutdown() {
+        this.apm?.stop();
+    }
+
+    /**
+     * Normalize path for metrics (replace dynamic segments)
+     */
+    private normalizePath(path: string): string {
+        return path
+            .replace(/\/\d+/g, '/:id')
+            .replace(/\/[a-f0-9-]{36}/gi, '/:uuid')
+            .replace(/\/[a-f0-9]{24}/gi, '/:objectId');
+    }
+}