confused-ai-core 0.1.0

package/src/observability/console-logger.ts

@@ -0,0 +1,123 @@
+/**
+ * Console Logger Implementation
+ *
+ * Simple console-based logging for development and debugging
+ */
+
+import { Logger, LogLevel, LogEntry, LogContext } from './types.js';
+
+/**
+ * Console logger configuration
+ */
+export interface ConsoleLoggerConfig {
+    readonly minLevel?: LogLevel;
+    readonly includeTimestamp?: boolean;
+    readonly prefix?: string;
+}
+
+/**
+ * Console logger implementation
+ */
+export class ConsoleLogger implements Logger {
+    private minLevel: LogLevel;
+    private includeTimestamp: boolean;
+    private prefix: string;
+    private context: Partial<LogContext> = {};
+
+    private static readonly LEVEL_PRIORITY: Record<LogLevel, number> = {
+        [LogLevel.DEBUG]: 0,
+        [LogLevel.INFO]: 1,
+        [LogLevel.WARN]: 2,
+        [LogLevel.ERROR]: 3,
+        [LogLevel.FATAL]: 4,
+    };
+
+    constructor(config: ConsoleLoggerConfig = {}) {
+        this.minLevel = config.minLevel ?? LogLevel.INFO;
+        this.includeTimestamp = config.includeTimestamp ?? true;
+        this.prefix = config.prefix ?? '[AgentFramework]';
+    }
+
+    debug(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        this.log(LogLevel.DEBUG, message, context, metadata);
+    }
+
+    info(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        this.log(LogLevel.INFO, message, context, metadata);
+    }
+
+    warn(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        this.log(LogLevel.WARN, message, context, metadata);
+    }
+
+    error(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        this.log(LogLevel.ERROR, message, context, metadata);
+    }
+
+    fatal(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        this.log(LogLevel.FATAL, message, context, metadata);
+    }
+
+    log(level: LogLevel, message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+
+        const entry: LogEntry = {
+            id: this.generateId(),
+            timestamp: new Date(),
+            level,
+            message,
+            source: this.prefix,
+            context: { ...this.context, ...context },
+            metadata,
+        };
+
+        this.output(entry);
+    }
+
+    child(additionalContext: Partial<LogContext>): Logger {
+        const childLogger = new ConsoleLogger({
+            minLevel: this.minLevel,
+            includeTimestamp: this.includeTimestamp,
+            prefix: this.prefix,
+        });
+        childLogger.context = { ...this.context, ...additionalContext };
+        return childLogger;
+    }
+
+    private shouldLog(level: LogLevel): boolean {
+        return ConsoleLogger.LEVEL_PRIORITY[level] >= ConsoleLogger.LEVEL_PRIORITY[this.minLevel];
+    }
+
+    private output(entry: LogEntry): void {
+        const timestamp = this.includeTimestamp
+            ? `[${entry.timestamp.toISOString()}]`
+            : '';
+        const level = `[${entry.level.toUpperCase()}]`;
+        const prefix = entry.source;
+
+        const parts = [timestamp, prefix, level, entry.message].filter(Boolean);
+        const formattedMessage = parts.join(' ');
+
+        switch (entry.level) {
+            case LogLevel.DEBUG:
+                console.debug(formattedMessage, entry.metadata ?? '');
+                break;
+            case LogLevel.INFO:
+                console.info(formattedMessage, entry.metadata ?? '');
+                break;
+            case LogLevel.WARN:
+                console.warn(formattedMessage, entry.metadata ?? '');
+                break;
+            case LogLevel.ERROR:
+            case LogLevel.FATAL:
+                console.error(formattedMessage, entry.metadata ?? '');
+                break;
+        }
+    }
+
+    private generateId(): string {
+        return `log-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+}

package/src/observability/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Observability module exports
+ */
+
+export * from './types.js';
+export { ConsoleLogger } from './console-logger.js';
+export { InMemoryTracer } from './tracer.js';
+export { MetricsCollectorImpl } from './metrics.js';
+
+// OTLP Export
+export { OTLPTraceExporter, OTLPMetricsExporter } from './otlp-exporter.js';
+export type { OTLPExporterConfig } from './otlp-exporter.js';

package/src/observability/metrics.ts

@@ -0,0 +1,85 @@
+/**
+ * Metrics Collector Implementation
+ *
+ * In-memory metrics collection for monitoring and observability
+ */
+
+import { MetricsCollector, MetricValue, MetricType } from './types.js';
+
+/**
+ * Metrics collector implementation
+ */
+export class MetricsCollectorImpl implements MetricsCollector {
+    private metrics: MetricValue[] = [];
+
+    counter(name: string, value = 1, labels: Record<string, string> = {}): void {
+        this.metrics.push({
+            name,
+            type: MetricType.COUNTER,
+            value,
+            labels,
+            timestamp: new Date(),
+        });
+    }
+
+    gauge(name: string, value: number, labels: Record<string, string> = {}): void {
+        // Remove previous gauge with same name and labels
+        this.metrics = this.metrics.filter(m =>
+            !(m.name === name &&
+                m.type === MetricType.GAUGE &&
+                JSON.stringify(m.labels) === JSON.stringify(labels))
+        );
+
+        this.metrics.push({
+            name,
+            type: MetricType.GAUGE,
+            value,
+            labels,
+            timestamp: new Date(),
+        });
+    }
+
+    histogram(name: string, value: number, labels: Record<string, string> = {}): void {
+        this.metrics.push({
+            name,
+            type: MetricType.HISTOGRAM,
+            value,
+            labels,
+            timestamp: new Date(),
+        });
+    }
+
+    getMetrics(): MetricValue[] {
+        return [...this.metrics];
+    }
+
+    clear(): void {
+        this.metrics = [];
+    }
+
+    /**
+     * Get metrics by name
+     */
+    getMetricsByName(name: string): MetricValue[] {
+        return this.metrics.filter(m => m.name === name);
+    }
+
+    /**
+     * Get metrics by type
+     */
+    getMetricsByType(type: MetricType): MetricValue[] {
+        return this.metrics.filter(m => m.type === type);
+    }
+
+    /**
+     * Get the latest value for a metric
+     */
+    getLatestValue(name: string): number | undefined {
+        const metrics = this.getMetricsByName(name);
+        if (metrics.length === 0) return undefined;
+
+        return metrics.sort((a, b) =>
+            b.timestamp.getTime() - a.timestamp.getTime()
+        )[0].value;
+    }
+}

package/src/observability/otlp-exporter.ts

@@ -0,0 +1,417 @@
+/**
+ * OTLP Exporter - OpenTelemetry Protocol Export for Distributed Tracing
+ *
+ * Production-grade observability export supporting:
+ * - OTLP/HTTP trace export (Jaeger, Datadog, Honeycomb, etc.)
+ * - Batched export with configurable intervals
+ * - W3C trace context propagation
+ * - Automatic retry with backoff
+ */
+
+import type { TraceSpan, SpanStatus, MetricValue } from './types.js';
+
+/** OTLP export configuration */
+export interface OTLPExporterConfig {
+    /** OTLP endpoint URL (e.g., https://api.honeycomb.io/v1/traces) */
+    readonly endpoint: string;
+    /** Service name for trace attribution */
+    readonly serviceName: string;
+    /** Optional headers (e.g., API keys) */
+    readonly headers?: Record<string, string>;
+    /** Batch size before export (default: 50) */
+    readonly batchSize?: number;
+    /** Export interval in ms (default: 5000) */
+    readonly exportIntervalMs?: number;
+    /** Max queue size before dropping (default: 2048) */
+    readonly maxQueueSize?: number;
+    /** Export timeout in ms (default: 30000) */
+    readonly timeoutMs?: number;
+    /** Enable console logging for debug (default: false) */
+    readonly debug?: boolean;
+}
+
+/** OTLP span format */
+interface OTLPSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    status: { code: number; message?: string };
+    attributes: Array<{ key: string; value: { stringValue?: string; intValue?: number; boolValue?: boolean } }>;
+    events: Array<{
+        name: string;
+        timeUnixNano: string;
+        attributes?: Array<{ key: string; value: { stringValue: string } }>;
+    }>;
+}
+
+/** Export batch request */
+interface OTLPTraceRequest {
+    resourceSpans: Array<{
+        resource: {
+            attributes: Array<{ key: string; value: { stringValue: string } }>;
+        };
+        scopeSpans: Array<{
+            scope: { name: string; version: string };
+            spans: OTLPSpan[];
+        }>;
+    }>;
+}
+
+/**
+ * OTLP Trace Exporter - exports spans to OTLP-compatible backends.
+ *
+ * @example
+ * const exporter = new OTLPTraceExporter({
+ *   endpoint: 'https://api.honeycomb.io/v1/traces',
+ *   serviceName: 'my-agent',
+ *   headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY },
+ * });
+ *
+ * // Export spans
+ * exporter.addSpan(span);
+ *
+ * // Start automatic export
+ * exporter.start();
+ *
+ * // Clean shutdown
+ * await exporter.shutdown();
+ */
+export class OTLPTraceExporter {
+    private readonly config: Required<Omit<OTLPExporterConfig, 'headers'>> &
+        Pick<OTLPExporterConfig, 'headers'>;
+    private spanQueue: TraceSpan[] = [];
+    private exportTimer: NodeJS.Timeout | null = null;
+    private isShuttingDown = false;
+
+    constructor(config: OTLPExporterConfig) {
+        this.config = {
+            endpoint: config.endpoint,
+            serviceName: config.serviceName,
+            headers: config.headers,
+            batchSize: config.batchSize ?? 50,
+            exportIntervalMs: config.exportIntervalMs ?? 5_000,
+            maxQueueSize: config.maxQueueSize ?? 2048,
+            timeoutMs: config.timeoutMs ?? 30_000,
+            debug: config.debug ?? false,
+        };
+    }
+
+    /** Add a span to the export queue */
+    addSpan(span: TraceSpan): void {
+        if (this.isShuttingDown) return;
+
+        if (this.spanQueue.length >= this.config.maxQueueSize) {
+            this.log('warn', `Queue full (${this.config.maxQueueSize}), dropping oldest spans`);
+            this.spanQueue.shift();
+        }
+
+        this.spanQueue.push(span);
+
+        // Export immediately if batch is full
+        if (this.spanQueue.length >= this.config.batchSize) {
+            this.export().catch(e => this.log('error', `Export failed: ${e}`));
+        }
+    }
+
+    /** Add multiple spans */
+    addSpans(spans: TraceSpan[]): void {
+        for (const span of spans) {
+            this.addSpan(span);
+        }
+    }
+
+    /** Start automatic periodic export */
+    start(): void {
+        if (this.exportTimer) return;
+
+        this.exportTimer = setInterval(() => {
+            this.export().catch(e => this.log('error', `Periodic export failed: ${e}`));
+        }, this.config.exportIntervalMs);
+
+        this.log('debug', `Started with interval ${this.config.exportIntervalMs}ms`);
+    }
+
+    /** Stop automatic export and flush remaining spans */
+    async shutdown(): Promise<void> {
+        this.isShuttingDown = true;
+
+        if (this.exportTimer) {
+            clearInterval(this.exportTimer);
+            this.exportTimer = null;
+        }
+
+        // Flush remaining spans
+        if (this.spanQueue.length > 0) {
+            await this.export();
+        }
+
+        this.log('debug', 'Shutdown complete');
+    }
+
+    /** Force export current batch */
+    async export(): Promise<{ success: boolean; exported: number; errors?: string[] }> {
+        if (this.spanQueue.length === 0) {
+            return { success: true, exported: 0 };
+        }
+
+        const batch = this.spanQueue.splice(0, this.config.batchSize);
+        const request = this.buildRequest(batch);
+
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+            const response = await fetch(this.config.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.config.headers,
+                },
+                body: JSON.stringify(request),
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.log('error', `Export failed: ${response.status} ${errorText}`);
+                // Re-queue failed spans
+                this.spanQueue.unshift(...batch);
+                return { success: false, exported: 0, errors: [errorText] };
+            }
+
+            this.log('debug', `Exported ${batch.length} spans`);
+            return { success: true, exported: batch.length };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.log('error', `Export error: ${message}`);
+            // Re-queue failed spans
+            this.spanQueue.unshift(...batch);
+            return { success: false, exported: 0, errors: [message] };
+        }
+    }
+
+    /** Get current queue size */
+    getQueueSize(): number {
+        return this.spanQueue.length;
+    }
+
+    // --- Private methods ---
+
+    private buildRequest(spans: TraceSpan[]): OTLPTraceRequest {
+        return {
+            resourceSpans: [
+                {
+                    resource: {
+                        attributes: [
+                            { key: 'service.name', value: { stringValue: this.config.serviceName } },
+                        ],
+                    },
+                    scopeSpans: [
+                        {
+                            scope: { name: '@confused-ai/core', version: '0.1.0' },
+                            spans: spans.map(span => this.convertSpan(span)),
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+
+    private convertSpan(span: TraceSpan): OTLPSpan {
+        return {
+            traceId: span.traceId,
+            spanId: String(span.id),
+            parentSpanId: span.parentId ? String(span.parentId) : undefined,
+            name: span.name,
+            kind: 1, // INTERNAL
+            startTimeUnixNano: String(span.startTime.getTime() * 1_000_000),
+            endTimeUnixNano: span.endTime ? String(span.endTime.getTime() * 1_000_000) : undefined,
+            status: {
+                code: this.statusToCode(span.status),
+            },
+            attributes: Object.entries(span.attributes).map(([key, value]) => ({
+                key,
+                value: this.convertAttributeValue(value),
+            })),
+            events: span.events.map(event => ({
+                name: event.name,
+                timeUnixNano: String(event.timestamp.getTime() * 1_000_000),
+                attributes: event.attributes
+                    ? Object.entries(event.attributes).map(([key, value]) => ({
+                        key,
+                        value: { stringValue: String(value) },
+                    }))
+                    : undefined,
+            })),
+        };
+    }
+
+    private statusToCode(status: SpanStatus): number {
+        switch (status) {
+            case 'ok':
+                return 1;
+            case 'error':
+                return 2;
+            default:
+                return 0;
+        }
+    }
+
+    private convertAttributeValue(value: unknown): { stringValue?: string; intValue?: number; boolValue?: boolean } {
+        if (typeof value === 'string') {
+            return { stringValue: value };
+        }
+        if (typeof value === 'number') {
+            return { intValue: value };
+        }
+        if (typeof value === 'boolean') {
+            return { boolValue: value };
+        }
+        return { stringValue: String(value) };
+    }
+
+    private log(level: 'debug' | 'warn' | 'error', message: string): void {
+        if (!this.config.debug && level === 'debug') return;
+
+        const prefix = `[OTLPExporter] [${level.toUpperCase()}]`;
+        if (level === 'error') {
+            console.error(prefix, message);
+        } else if (level === 'warn') {
+            console.warn(prefix, message);
+        } else {
+            console.log(prefix, message);
+        }
+    }
+}
+
+/**
+ * OTLP Metrics Exporter - exports metrics to OTLP-compatible backends.
+ */
+export class OTLPMetricsExporter {
+    private readonly config: Required<Omit<OTLPExporterConfig, 'headers'>> &
+        Pick<OTLPExporterConfig, 'headers'>;
+    private metricsQueue: MetricValue[] = [];
+    private exportTimer: NodeJS.Timeout | null = null;
+    private isShuttingDown = false;
+
+    constructor(config: OTLPExporterConfig) {
+        this.config = {
+            endpoint: config.endpoint,
+            serviceName: config.serviceName,
+            headers: config.headers,
+            batchSize: config.batchSize ?? 100,
+            exportIntervalMs: config.exportIntervalMs ?? 10_000,
+            maxQueueSize: config.maxQueueSize ?? 4096,
+            timeoutMs: config.timeoutMs ?? 30_000,
+            debug: config.debug ?? false,
+        };
+    }
+
+    /** Add a metric to the export queue */
+    addMetric(metric: MetricValue): void {
+        if (this.isShuttingDown) return;
+
+        if (this.metricsQueue.length >= this.config.maxQueueSize) {
+            this.metricsQueue.shift();
+        }
+
+        this.metricsQueue.push(metric);
+    }
+
+    /** Start automatic periodic export */
+    start(): void {
+        if (this.exportTimer) return;
+
+        this.exportTimer = setInterval(() => {
+            this.export().catch(e => console.error('[OTLPMetrics] Export failed:', e));
+        }, this.config.exportIntervalMs);
+    }
+
+    /** Stop and flush */
+    async shutdown(): Promise<void> {
+        this.isShuttingDown = true;
+
+        if (this.exportTimer) {
+            clearInterval(this.exportTimer);
+            this.exportTimer = null;
+        }
+
+        if (this.metricsQueue.length > 0) {
+            await this.export();
+        }
+    }
+
+    /** Export current batch */
+    async export(): Promise<{ success: boolean; exported: number }> {
+        if (this.metricsQueue.length === 0) {
+            return { success: true, exported: 0 };
+        }
+
+        const batch = this.metricsQueue.splice(0, this.config.batchSize);
+
+        try {
+            const response = await fetch(this.config.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.config.headers,
+                },
+                body: JSON.stringify(this.buildMetricsRequest(batch)),
+            });
+
+            if (!response.ok) {
+                this.metricsQueue.unshift(...batch);
+                return { success: false, exported: 0 };
+            }
+
+            return { success: true, exported: batch.length };
+        } catch {
+            this.metricsQueue.unshift(...batch);
+            return { success: false, exported: 0 };
+        }
+    }
+
+    private buildMetricsRequest(metrics: MetricValue[]) {
+        return {
+            resourceMetrics: [
+                {
+                    resource: {
+                        attributes: [
+                            { key: 'service.name', value: { stringValue: this.config.serviceName } },
+                        ],
+                    },
+                    scopeMetrics: [
+                        {
+                            scope: { name: '@confused-ai/core', version: '0.1.0' },
+                            metrics: metrics.map(m => ({
+                                name: m.name,
+                                description: '',
+                                unit: '',
+                                sum: {
+                                    dataPoints: [
+                                        {
+                                            asDouble: m.value,
+                                            timeUnixNano: String(m.timestamp.getTime() * 1_000_000),
+                                            attributes: Object.entries(m.labels).map(([k, v]) => ({
+                                                key: k,
+                                                value: { stringValue: v },
+                                            })),
+                                        },
+                                    ],
+                                    aggregationTemporality: 2, // CUMULATIVE
+                                    isMonotonic: m.type === 'counter',
+                                },
+                            })),
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+}