mcp-ai-agent-guidelines/dist/tools/shared/trace-logger.d.ts

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * Trace Logger for A2A Orchestration
 *
 * Provides structured tracing and observability for tool chains:
 * - Correlation ID propagation
 * - Execution timeline visualization
 * - Performance metrics
 * - Error tracking
 * - Distributed tracing support
 */
import type { A2AContext } from "./a2a-context.js";
/**
 * Trace event types
 */
export type TraceEventType = "chain_start" | "chain_end" | "tool_start" | "tool_end" | "tool_error" | "context_update";
/**
 * Trace event
 */
export interface TraceEvent {
    /** Event type */
    type: TraceEventType;
    /** Timestamp */
    timestamp: Date;
    /** Correlation ID */
    correlationId: string;
    /** Tool name (if applicable) */
    toolName?: string;
    /** Execution depth */
    depth?: number;
    /** Additional event data */
    data?: Record<string, unknown>;
}
/**
 * Trace span for a tool invocation
 */
export interface TraceSpan {
    /** Span ID */
    spanId: string;
    /** Parent span ID (if nested) */
    parentSpanId?: string;
    /** Correlation ID */
    correlationId: string;
    /** Tool name */
    toolName: string;
    /** Start time */
    startTime: Date;
    /** End time */
    endTime?: Date;
    /** Duration in milliseconds */
    durationMs?: number;
    /** Execution depth */
    depth: number;
    /** Status */
    status: "success" | "error" | "pending";
    /** Error message if failed */
    error?: string;
    /** Input hash */
    inputHash: string;
    /** Output summary */
    outputSummary?: string;
}
/**
 * Trace Logger class for managing traces
 */
export declare class TraceLogger {
    private events;
    private spans;
    private activeSpans;
    /**
     * Start a new chain trace
     *
     * @param context - A2A context
     */
    startChain(context: A2AContext): void;
    /**
     * End a chain trace
     *
     * @param context - A2A context
     * @param success - Whether chain succeeded
     * @param error - Error message if failed
     */
    endChain(context: A2AContext, success: boolean, error?: string): void;
    /**
     * Start a tool span
     *
     * @param context - A2A context
     * @param toolName - Tool name
     * @param inputHash - Input hash
     * @returns Span ID
     */
    startToolSpan(context: A2AContext, toolName: string, inputHash: string): string;
    /**
     * End a tool span
     *
     * @param spanId - Span ID
     * @param success - Whether tool succeeded
     * @param outputSummary - Output summary
     * @param error - Error message if failed
     */
    endToolSpan(spanId: string, success: boolean, outputSummary?: string, error?: string): void;
    /**
     * Get all spans for a correlation ID
     *
     * @param correlationId - Correlation ID
     * @returns Array of spans
     */
    getSpans(correlationId: string): TraceSpan[];
    /**
     * Get all events for a correlation ID
     *
     * @param correlationId - Correlation ID
     * @returns Array of events
     */
    getEvents(correlationId: string): TraceEvent[];
    /**
     * Get execution timeline for a correlation ID
     *
     * @param correlationId - Correlation ID
     * @returns Timeline visualization data
     */
    getTimeline(correlationId: string): {
        spans: TraceSpan[];
        totalDurationMs: number;
        criticalPath: string[];
    };
    /**
     * Export trace data for external systems
     *
     * @param correlationId - Correlation ID
     * @param format - Export format
     * @returns Formatted trace data
     */
    exportTrace(correlationId: string, format?: "json" | "otlp"): string;
    /**
     * Clear all traces (for testing)
     */
    clear(): void;
    /**
     * Get summary statistics
     */
    getSummary(): {
        totalChains: number;
        totalSpans: number;
        totalEvents: number;
        avgSpansPerChain: number;
    };
    /**
     * Maximum number of events to keep in memory
     */
    private static readonly MAX_EVENTS;
    /**
     * Maximum number of spans to keep in memory per correlation ID
     */
    private static readonly MAX_SPANS_PER_CORRELATION;
    /**
     * Maximum age of spans to keep (in milliseconds)
     */
    private static readonly MAX_SPAN_AGE_MS;
    /**
     * Add a trace event
     */
    private addEvent;
    /**
     * Clean up old spans to prevent memory leaks in long-running servers
     */
    private cleanupOldSpans;
    /**
     * Force run cleanup of old spans (public wrapper for tests)
     *
     * NOTE: Deterministic API used by tests to exercise cleanup branches.
     */
    forceCleanupOldSpans(): void;
    /**
     * Generate a unique span ID
     */
    private generateSpanId;
    /**
     * Find critical path through spans
     */
    private findCriticalPath;
}
/**
 * Singleton trace logger instance
 */
export declare const traceLogger: TraceLogger;
/**
 * Helper: Create trace from A2A context execution log
 *
 * @param context - A2A context
 * @returns Trace data
 */
export declare function createTraceFromContext(context: A2AContext): {
    correlationId: string;
    spans: TraceSpan[];
    totalDurationMs: number;
};
//# sourceMappingURL=trace-logger.d.ts.map