profclaw 0.0.1-beta.1

package/dist/utils/logger.js

@@ -0,0 +1,282 @@
+/**
+ * Structured Logging Utility
+ *
+ * Provides structured logging with:
+ * - Log levels (debug, info, warn, error)
+ * - Correlation IDs for request tracing
+ * - Contextual metadata
+ * - JSON output for production
+ * - Pretty output for development
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "DEBUG";
+    LogLevel["INFO"] = "INFO";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["ERROR"] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+const LOG_LEVEL_PRIORITY = {
+    [LogLevel.DEBUG]: 0,
+    [LogLevel.INFO]: 1,
+    [LogLevel.WARN]: 2,
+    [LogLevel.ERROR]: 3,
+};
+const ERROR_BASE_KEYS = new Set(['name', 'message', 'stack']);
+function getErrorMetadata(error) {
+    const rawError = error;
+    return Object.fromEntries(Object.entries(rawError).filter(([key]) => !ERROR_BASE_KEYS.has(key)));
+}
+/**
+ * Structured logger class
+ */
+export class Logger {
+    config;
+    constructor(config) {
+        this.config = {
+            level: process.env.LOG_LEVEL || LogLevel.INFO,
+            pretty: process.env.NODE_ENV !== 'production',
+            includeTimestamp: true,
+            ...config,
+        };
+    }
+    /**
+     * Log a debug message
+     */
+    debug(message, context) {
+        this.log(LogLevel.DEBUG, message, context);
+    }
+    /**
+     * Log an info message
+     */
+    info(message, context) {
+        this.log(LogLevel.INFO, message, context);
+    }
+    /**
+     * Log a warning
+     */
+    warn(message, context) {
+        this.log(LogLevel.WARN, message, context);
+    }
+    /**
+     * Log an error
+     */
+    error(message, errorOrContext, context) {
+        let error;
+        let finalContext;
+        if (errorOrContext instanceof Error) {
+            error = errorOrContext;
+            finalContext = context;
+        }
+        else {
+            finalContext = errorOrContext;
+        }
+        this.log(LogLevel.ERROR, message, finalContext, error);
+    }
+    /**
+     * Create a child logger with additional default context
+     */
+    child(context) {
+        return new Logger({
+            ...this.config,
+            defaultContext: {
+                ...this.config.defaultContext,
+                ...context,
+            },
+        });
+    }
+    /**
+     * Core logging method
+     */
+    log(level, message, context, error) {
+        // Check if this log level should be output
+        if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.config.level]) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            context: {
+                ...this.config.defaultContext,
+                ...context,
+            },
+        };
+        // Add error information if present
+        if (error) {
+            entry.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+                ...getErrorMetadata(error),
+            };
+        }
+        // Output based on configuration
+        if (this.config.pretty) {
+            this.prettyPrint(entry);
+        }
+        else {
+            this.jsonPrint(entry);
+        }
+    }
+    /**
+     * Pretty print for development
+     */
+    prettyPrint(entry) {
+        const colors = {
+            [LogLevel.DEBUG]: '\x1b[36m', // Cyan
+            [LogLevel.INFO]: '\x1b[32m', // Green
+            [LogLevel.WARN]: '\x1b[33m', // Yellow
+            [LogLevel.ERROR]: '\x1b[31m', // Red
+        };
+        const reset = '\x1b[0m';
+        const color = colors[entry.level];
+        let output = `${color}[${entry.level}]${reset}`;
+        if (this.config.includeTimestamp) {
+            output += ` ${entry.timestamp}`;
+        }
+        output += ` ${entry.message}`;
+        // Add correlation ID prominently if present
+        if (entry.context?.correlationId) {
+            output += ` ${color}[${entry.context.correlationId}]${reset}`;
+        }
+        console.log(output);
+        // Print context
+        if (entry.context && Object.keys(entry.context).length > 0) {
+            const { correlationId: _correlationId, ...otherContext } = entry.context;
+            if (Object.keys(otherContext).length > 0) {
+                console.log('  Context:', otherContext);
+            }
+        }
+        // Print error details
+        if (entry.error) {
+            console.log(`  ${color}Error:${reset}`, entry.error.message);
+            if (entry.error.stack) {
+                console.log('  Stack:', entry.error.stack);
+            }
+        }
+    }
+    /**
+     * JSON print for production
+     */
+    jsonPrint(entry) {
+        console.log(JSON.stringify(entry));
+    }
+    /**
+     * Update logger configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+/**
+ * Default logger instance
+ */
+export const logger = new Logger();
+/**
+ * Generate a correlation ID
+ */
+export function generateCorrelationId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Async local storage for correlation context
+ * Allows maintaining correlation ID across async operations
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+export const correlationStorage = new AsyncLocalStorage();
+/**
+ * Run a function with correlation context
+ */
+export function withCorrelation(correlationId, fn, metadata) {
+    return correlationStorage.run({ correlationId, metadata }, fn);
+}
+/**
+ * Get current correlation ID from context
+ */
+export function getCorrelationId() {
+    return correlationStorage.getStore()?.correlationId;
+}
+/**
+ * Get current correlation metadata
+ */
+export function getCorrelationMetadata() {
+    return correlationStorage.getStore()?.metadata;
+}
+/**
+ * Create a logger that automatically includes correlation context
+ */
+export function createContextualLogger(name) {
+    const baseContext = name ? { component: name } : {};
+    const contextualLogger = new Logger({ defaultContext: baseContext });
+    const mergeContext = (context) => {
+        const correlationId = getCorrelationId();
+        const metadata = getCorrelationMetadata();
+        return {
+            ...context,
+            correlationId: correlationId || context?.correlationId,
+            ...metadata,
+        };
+    };
+    contextualLogger.debug = (message, context) => {
+        Logger.prototype.debug.call(contextualLogger, message, mergeContext(context));
+    };
+    contextualLogger.info = (message, context) => {
+        Logger.prototype.info.call(contextualLogger, message, mergeContext(context));
+    };
+    contextualLogger.warn = (message, context) => {
+        Logger.prototype.warn.call(contextualLogger, message, mergeContext(context));
+    };
+    contextualLogger.error = (message, errorOrContext, context) => {
+        if (errorOrContext instanceof Error) {
+            Logger.prototype.error.call(contextualLogger, message, errorOrContext, mergeContext(context));
+            return;
+        }
+        Logger.prototype.error.call(contextualLogger, message, mergeContext(errorOrContext), context);
+    };
+    return contextualLogger;
+}
+/**
+ * Performance timing utility
+ */
+export class PerformanceTimer {
+    name;
+    logger;
+    startTime;
+    endTime;
+    marks = new Map();
+    constructor(name, logger = logger) {
+        this.name = name;
+        this.logger = logger;
+        this.startTime = performance.now();
+    }
+    /**
+     * Mark a checkpoint
+     */
+    mark(name) {
+        this.marks.set(name, performance.now());
+    }
+    /**
+     * End timing and log
+     */
+    end(context) {
+        this.endTime = performance.now();
+        const duration = this.endTime - this.startTime;
+        const marks = {};
+        for (const [name, time] of this.marks) {
+            marks[name] = Number((time - this.startTime).toFixed(2));
+        }
+        this.logger.info(`Performance: ${this.name}`, {
+            ...context,
+            duration: Number(duration.toFixed(2)),
+            marks: Object.keys(marks).length > 0 ? marks : undefined,
+        });
+        return duration;
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/metrics.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Metrics Tracking System
+ *
+ * Tracks and aggregates metrics for:
+ * - Task processing (duration, success rate, throughput)
+ * - Queue depth and wait times
+ * - Adapter performance
+ * - Circuit breaker states
+ * - Error rates by category
+ */
+import type { TaskStatusType } from "../types/task.js";
+import type { ErrorCategory } from "../types/errors.js";
+import type { CircuitState } from "./circuit-breaker.js";
+/**
+ * Metric types
+ */
+export declare enum MetricType {
+    COUNTER = "COUNTER",// Cumulative count
+    GAUGE = "GAUGE",// Current value
+    HISTOGRAM = "HISTOGRAM",// Distribution of values
+    SUMMARY = "SUMMARY"
+}
+/**
+ * Metric data structure
+ */
+interface Metric {
+    type: MetricType;
+    name: string;
+    value: number;
+    labels?: Record<string, string>;
+    timestamp: Date;
+}
+/**
+ * Histogram bucket for distribution tracking
+ */
+interface HistogramBucket {
+    le: number;
+    count: number;
+}
+/**
+ * Histogram metric data
+ */
+interface HistogramData {
+    count: number;
+    sum: number;
+    buckets: HistogramBucket[];
+}
+/**
+ * Summary metric data (percentiles)
+ */
+interface SummaryData {
+    count: number;
+    sum: number;
+    percentiles: Map<number, number>;
+}
+/**
+ * Metrics collector
+ */
+declare class MetricsCollector {
+    private counters;
+    private gauges;
+    private histograms;
+    private summaries;
+    /**
+     * Increment a counter
+     */
+    incrementCounter(name: string, labels?: Record<string, string>, value?: number): void;
+    /**
+     * Set a gauge value
+     */
+    setGauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Observe a value in histogram
+     */
+    observeHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Observe a value in summary
+     */
+    observeSummary(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Get all metrics
+     */
+    getMetrics(): Metric[];
+    /**
+     * Get histogram metrics
+     */
+    getHistogramMetrics(): Record<string, HistogramData>;
+    /**
+     * Get summary metrics with percentiles
+     */
+    getSummaryMetrics(): Record<string, SummaryData>;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Create histogram buckets
+     */
+    private createBuckets;
+    /**
+     * Calculate percentile
+     */
+    private percentile;
+    /**
+     * Generate key from name and labels
+     */
+    private getKey;
+    /**
+     * Parse key back to name and labels
+     */
+    private parseKey;
+}
+/**
+ * Global metrics collector instance
+ */
+export declare const metrics: MetricsCollector;
+/**
+ * Task-specific metrics tracker
+ */
+export declare class TaskMetrics {
+    /**
+     * Track task started
+     */
+    static taskStarted(status: TaskStatusType, source: string): void;
+    /**
+     * Track task completed
+     */
+    static taskCompleted(success: boolean, duration: number, adapter: string, source: string): void;
+    /**
+     * Track task failed
+     */
+    static taskFailed(errorCategory: ErrorCategory, adapter: string): void;
+    /**
+     * Track queue depth
+     */
+    static setQueueDepth(depth: number, status: TaskStatusType): void;
+    /**
+     * Track adapter health
+     */
+    static setAdapterHealth(adapter: string, healthy: boolean): void;
+    /**
+     * Track circuit breaker state
+     */
+    static setCircuitBreakerState(name: string, state: CircuitState): void;
+}
+/**
+ * HTTP metrics tracker
+ */
+export declare class HTTPMetrics {
+    /**
+     * Track HTTP request
+     */
+    static requestReceived(method: string, path: string): void;
+    /**
+     * Track HTTP response
+     */
+    static responseSent(method: string, path: string, status: number, duration: number): void;
+    /**
+     * Track HTTP errors
+     */
+    static error(method: string, path: string, errorType: string): void;
+}
+/**
+ * Get metrics summary for health check
+ */
+export declare function getMetricsSummary(): {
+    tasks: {
+        total: number;
+        success: number;
+        failure: number;
+        successRate: number;
+    };
+    queue: {
+        depth: Record<string, number>;
+    };
+    http: {
+        total: number;
+        errors: number;
+        errorRate: number;
+    };
+};
+export {};
+//# sourceMappingURL=metrics.d.ts.map