@compilr-dev/agents 0.0.1

package/dist/tracing/manager.js

@@ -0,0 +1,468 @@
+/**
+ * TracingManager - Manages distributed tracing for agent execution
+ *
+ * Provides:
+ * - Trace and span management with correlation IDs
+ * - OpenTelemetry-compatible span structure
+ * - Event emission for observability integrations
+ * - Optional export to OTel backends
+ */
+/**
+ * Default maximum spans per trace
+ */
+const DEFAULT_MAX_SPANS = 1000;
+/**
+ * Manages distributed tracing for agent operations
+ *
+ * @example
+ * ```typescript
+ * const tracing = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   defaultAttributes: { environment: 'production' },
+ * });
+ *
+ * // Start a trace
+ * const traceId = tracing.startTrace();
+ *
+ * // Create spans
+ * const span = tracing.startSpan({ name: 'process-request' });
+ * span.attributes['request.id'] = '123';
+ *
+ * // End span and trace
+ * tracing.endSpan(span.spanId, { status: 'ok' });
+ * const trace = tracing.endTrace(traceId);
+ * ```
+ */
+export class TracingManager {
+    serviceName;
+    serviceVersion;
+    defaultAttributes;
+    maxSpansPerTrace;
+    autoGenerateTraceId;
+    // Storage
+    traces = new Map();
+    spans = new Map();
+    activeSpanStack = [];
+    // Event handling
+    eventHandlers = new Set();
+    // Optional OTel exporter
+    otelExporter;
+    // ID generation
+    spanIdCounter = 0;
+    traceIdCounter = 0;
+    constructor(options = {}) {
+        this.serviceName = options.serviceName ?? 'agent';
+        this.serviceVersion = options.serviceVersion ?? '1.0.0';
+        this.defaultAttributes = {
+            'service.name': this.serviceName,
+            'service.version': this.serviceVersion,
+            ...options.defaultAttributes,
+        };
+        this.maxSpansPerTrace = options.maxSpansPerTrace ?? DEFAULT_MAX_SPANS;
+        this.autoGenerateTraceId = options.autoGenerateTraceId ?? true;
+        this.otelExporter = options.otelExporter;
+        if (options.onEvent) {
+            this.eventHandlers.add(options.onEvent);
+        }
+    }
+    // ============================================================================
+    // Trace Management
+    // ============================================================================
+    /**
+     * Start a new trace
+     *
+     * @param attributes - Additional trace-level attributes
+     * @returns Trace ID
+     */
+    startTrace(attributes) {
+        const traceId = this.generateTraceId();
+        const now = Date.now();
+        const trace = {
+            traceId,
+            rootSpanId: '', // Will be set when first span is created
+            spans: [],
+            startTime: now,
+            attributes: {
+                ...this.defaultAttributes,
+                ...attributes,
+            },
+        };
+        this.traces.set(traceId, trace);
+        this.emit({ type: 'trace:started', traceId, timestamp: now });
+        return traceId;
+    }
+    /**
+     * End a trace and optionally export it
+     *
+     * @param traceId - Trace ID to end
+     * @returns Completed trace or undefined if not found
+     */
+    endTrace(traceId) {
+        const trace = this.traces.get(traceId);
+        if (!trace)
+            return undefined;
+        const now = Date.now();
+        trace.endTime = now;
+        trace.durationMs = now - trace.startTime;
+        // End any remaining active spans in this trace
+        for (const span of trace.spans) {
+            if (span.endTime === undefined) {
+                this.endSpan(span.spanId, { status: 'unset' });
+            }
+        }
+        this.emit({
+            type: 'trace:ended',
+            traceId,
+            durationMs: trace.durationMs,
+            spanCount: trace.spans.length,
+        });
+        // Export if exporter is configured
+        if (this.otelExporter) {
+            void this.exportTrace(trace);
+        }
+        return trace;
+    }
+    /**
+     * Get a trace by ID
+     */
+    getTrace(traceId) {
+        return this.traces.get(traceId);
+    }
+    /**
+     * Get all active traces
+     */
+    getActiveTraces() {
+        return Array.from(this.traces.values()).filter((t) => t.endTime === undefined);
+    }
+    /**
+     * Clear a trace from memory
+     */
+    clearTrace(traceId) {
+        const trace = this.traces.get(traceId);
+        if (!trace)
+            return false;
+        // Remove all spans
+        for (const span of trace.spans) {
+            this.spans.delete(span.spanId);
+        }
+        this.traces.delete(traceId);
+        return true;
+    }
+    // ============================================================================
+    // Span Management
+    // ============================================================================
+    /**
+     * Start a new span
+     *
+     * @param options - Span options
+     * @returns Created span
+     */
+    startSpan(options) {
+        const spanId = this.generateSpanId();
+        const now = options.startTime ?? Date.now();
+        // Determine parent context
+        let traceId;
+        let parentSpanId;
+        if (options.parentContext) {
+            traceId = options.parentContext.traceId;
+            parentSpanId = options.parentContext.parentSpanId;
+        }
+        else if (this.activeSpanStack.length > 0) {
+            // Use current span as parent
+            const currentSpan = this.getCurrentSpan();
+            if (currentSpan) {
+                traceId = currentSpan.traceId;
+                parentSpanId = currentSpan.spanId;
+            }
+            else {
+                // No active span, create new trace if auto-generate is on
+                traceId = this.autoGenerateTraceId ? this.startTrace() : this.generateTraceId();
+            }
+        }
+        else {
+            // No context, create new trace if auto-generate is on
+            traceId = this.autoGenerateTraceId ? this.startTrace() : this.generateTraceId();
+        }
+        const span = {
+            spanId,
+            traceId,
+            parentSpanId,
+            name: options.name,
+            kind: options.kind ?? 'internal',
+            startTime: now,
+            status: 'unset',
+            attributes: {
+                ...this.defaultAttributes,
+                ...options.attributes,
+            },
+            events: [],
+        };
+        // Store span
+        this.spans.set(spanId, span);
+        this.activeSpanStack.push(spanId);
+        // Add to trace
+        const trace = this.traces.get(traceId);
+        if (trace) {
+            // Check max spans limit
+            if (trace.spans.length >= this.maxSpansPerTrace) {
+                // Remove oldest span to make room
+                const oldest = trace.spans.shift();
+                if (oldest) {
+                    this.spans.delete(oldest.spanId);
+                }
+            }
+            trace.spans.push(span);
+            // Set root span if this is the first
+            if (!trace.rootSpanId) {
+                trace.rootSpanId = spanId;
+            }
+        }
+        this.emit({
+            type: 'span:started',
+            spanId,
+            traceId,
+            name: span.name,
+            parentSpanId,
+        });
+        return span;
+    }
+    /**
+     * End a span
+     *
+     * @param spanId - Span ID to end
+     * @param options - End options
+     * @returns Ended span or undefined if not found
+     */
+    endSpan(spanId, options) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return undefined;
+        const now = options?.endTime ?? Date.now();
+        span.endTime = now;
+        span.durationMs = now - span.startTime;
+        if (options?.status) {
+            span.status = options.status;
+        }
+        if (options?.statusMessage) {
+            span.statusMessage = options.statusMessage;
+        }
+        if (options?.attributes) {
+            Object.assign(span.attributes, options.attributes);
+        }
+        // Remove from active stack
+        const stackIndex = this.activeSpanStack.indexOf(spanId);
+        if (stackIndex !== -1) {
+            this.activeSpanStack.splice(stackIndex, 1);
+        }
+        this.emit({
+            type: 'span:ended',
+            spanId,
+            traceId: span.traceId,
+            durationMs: span.durationMs,
+            status: span.status,
+        });
+        return span;
+    }
+    /**
+     * Get a span by ID
+     */
+    getSpan(spanId) {
+        return this.spans.get(spanId);
+    }
+    /**
+     * Get the current active span
+     */
+    getCurrentSpan() {
+        if (this.activeSpanStack.length === 0)
+            return undefined;
+        const currentId = this.activeSpanStack[this.activeSpanStack.length - 1];
+        return this.spans.get(currentId);
+    }
+    /**
+     * Get current span context for propagation
+     */
+    getCurrentContext() {
+        const currentSpan = this.getCurrentSpan();
+        if (!currentSpan)
+            return undefined;
+        return {
+            traceId: currentSpan.traceId,
+            parentSpanId: currentSpan.spanId,
+        };
+    }
+    // ============================================================================
+    // Span Modification
+    // ============================================================================
+    /**
+     * Add an event to a span
+     *
+     * @param spanId - Span ID
+     * @param name - Event name
+     * @param attributes - Event attributes
+     */
+    addSpanEvent(spanId, name, attributes) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return;
+        const event = {
+            name,
+            timestamp: Date.now(),
+            attributes,
+        };
+        span.events.push(event);
+        this.emit({
+            type: 'span:event',
+            spanId,
+            traceId: span.traceId,
+            eventName: name,
+        });
+    }
+    /**
+     * Set attributes on a span
+     *
+     * @param spanId - Span ID
+     * @param attributes - Attributes to set
+     */
+    setSpanAttributes(spanId, attributes) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return;
+        Object.assign(span.attributes, attributes);
+    }
+    /**
+     * Set span status
+     *
+     * @param spanId - Span ID
+     * @param status - Status
+     * @param message - Optional status message
+     */
+    setSpanStatus(spanId, status, message) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return;
+        span.status = status;
+        if (message) {
+            span.statusMessage = message;
+        }
+    }
+    /**
+     * Record an error on a span
+     *
+     * @param spanId - Span ID
+     * @param error - Error to record
+     */
+    recordError(spanId, error) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return;
+        span.status = 'error';
+        span.statusMessage = error.message;
+        this.addSpanEvent(spanId, 'exception', {
+            'exception.type': error.name,
+            'exception.message': error.message,
+            'exception.stacktrace': error.stack ?? '',
+        });
+        this.emit({
+            type: 'span:error',
+            spanId,
+            traceId: span.traceId,
+            error,
+        });
+    }
+    // ============================================================================
+    // Event Handling
+    // ============================================================================
+    /**
+     * Subscribe to tracing events
+     *
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Silently ignore handler errors
+            }
+        }
+    }
+    // ============================================================================
+    // Export
+    // ============================================================================
+    /**
+     * Export a trace to configured exporter
+     */
+    async exportTrace(trace) {
+        if (!this.otelExporter)
+            return;
+        try {
+            await this.otelExporter.export(trace.spans);
+            this.emit({
+                type: 'export:success',
+                traceId: trace.traceId,
+                exporter: this.otelExporter.name,
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'export:error',
+                traceId: trace.traceId,
+                exporter: this.otelExporter.name,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    /**
+     * Manually export a trace
+     */
+    async export(traceId) {
+        const trace = this.traces.get(traceId);
+        if (trace && this.otelExporter) {
+            await this.exportTrace(trace);
+        }
+    }
+    // ============================================================================
+    // Utility Methods
+    // ============================================================================
+    generateTraceId() {
+        // Generate a 32-character hex string (128-bit) compatible with W3C Trace Context
+        const timestamp = Date.now().toString(16).padStart(12, '0');
+        const counter = (++this.traceIdCounter).toString(16).padStart(4, '0');
+        const random = Math.random().toString(16).slice(2, 18).padStart(16, '0');
+        return `${timestamp}${counter}${random}`.slice(0, 32);
+    }
+    generateSpanId() {
+        // Generate a 16-character hex string (64-bit) compatible with W3C Trace Context
+        const timestamp = Date.now().toString(16).padStart(8, '0');
+        const counter = (++this.spanIdCounter).toString(16).padStart(4, '0');
+        const random = Math.random().toString(16).slice(2, 6);
+        return `${timestamp}${counter}${random}`.slice(0, 16);
+    }
+    // ============================================================================
+    // Statistics
+    // ============================================================================
+    /**
+     * Get tracing statistics
+     */
+    getStats() {
+        return {
+            activeTraces: this.getActiveTraces().length,
+            totalSpans: this.spans.size,
+            activeSpans: this.activeSpanStack.length,
+        };
+    }
+    /**
+     * Clear all traces and spans
+     */
+    clear() {
+        this.traces.clear();
+        this.spans.clear();
+        this.activeSpanStack.length = 0;
+    }
+}

package/dist/tracing/otel.d.ts

@@ -0,0 +1,102 @@
+/**
+ * OpenTelemetry Integration
+ *
+ * Provides optional integration with OpenTelemetry for exporting traces
+ * to OTel-compatible backends (Jaeger, Zipkin, etc.)
+ *
+ * Requires optional peer dependency: @opentelemetry/api
+ */
+import type { OTelExporter } from './types.js';
+/**
+ * Error thrown when OpenTelemetry SDK is not installed
+ */
+export declare class OTelNotInstalledError extends Error {
+    constructor();
+}
+/**
+ * Check if a value is an OTelNotInstalledError
+ */
+export declare function isOTelNotInstalledError(error: unknown): error is OTelNotInstalledError;
+/**
+ * Create an OpenTelemetry exporter that wraps OTel spans
+ *
+ * This exporter converts our internal Span format to OpenTelemetry spans
+ * and uses the configured OTel tracer to export them.
+ *
+ * @param tracerName - Name for the OTel tracer
+ * @param tracerVersion - Version for the OTel tracer
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * // First, set up OpenTelemetry in your application:
+ * // import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * // const provider = new NodeTracerProvider();
+ * // provider.register();
+ *
+ * // Then use with TracingManager:
+ * const exporter = await createOTelExporter('my-agent', '1.0.0');
+ * const tracingManager = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   otelExporter: exporter,
+ * });
+ * ```
+ */
+export declare function createOTelExporter(tracerName?: string, tracerVersion?: string): Promise<OTelExporter>;
+/**
+ * Create a console exporter for debugging
+ *
+ * This exporter simply logs spans to the console in a readable format.
+ * Useful for development and debugging.
+ *
+ * @param options - Console exporter options
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * const exporter = createConsoleExporter({ prettyPrint: true });
+ * const tracingManager = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   otelExporter: exporter,
+ * });
+ * ```
+ */
+export declare function createConsoleExporter(options?: {
+    prettyPrint?: boolean;
+    output?: (message: string) => void;
+}): OTelExporter;
+/**
+ * Create a batch exporter that buffers spans and exports in batches
+ *
+ * @param innerExporter - The actual exporter to use
+ * @param options - Batch options
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * const otelExporter = await createOTelExporter();
+ * const batchExporter = createBatchExporter(otelExporter, {
+ *   maxBatchSize: 100,
+ *   flushIntervalMs: 5000,
+ * });
+ * ```
+ */
+export declare function createBatchExporter(innerExporter: OTelExporter, options?: {
+    maxBatchSize?: number;
+    flushIntervalMs?: number;
+}): OTelExporter;
+/**
+ * Create a multi-exporter that sends to multiple backends
+ *
+ * @param exporters - List of exporters to use
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * const multiExporter = createMultiExporter([
+ *   createConsoleExporter(),
+ *   await createOTelExporter(),
+ * ]);
+ * ```
+ */
+export declare function createMultiExporter(exporters: OTelExporter[]): OTelExporter;