@hivetechs/hive-ai
Version:
Real-time streaming AI consensus platform with HTTP+SSE MCP integration for Claude Code, VS Code, Cursor, and Windsurf - powered by OpenRouter's unified API
202 lines • 5.56 kB
TypeScript
/**
* Pipeline Tracer - Expert-level pipeline tracing and profiling
*
* Provides comprehensive request tracing through all 4 consensus stages,
* performance bottleneck identification, and detailed profiling capabilities.
*/
export interface TraceSpan {
id: string;
traceId: string;
parentId?: string;
operationName: string;
component: 'consensus' | 'openrouter' | 'database' | 'validator' | 'system';
startTime: number;
endTime?: number;
duration?: number;
tags: Record<string, string | number | boolean>;
logs: TraceLog[];
status: 'active' | 'success' | 'error' | 'timeout';
error?: Error;
metrics: {
cpuTime?: number;
memoryUsage?: number;
tokensProcessed?: number;
apiCalls?: number;
dbQueries?: number;
};
}
export interface TraceLog {
timestamp: number;
level: 'debug' | 'info' | 'warn' | 'error';
message: string;
fields?: Record<string, any>;
}
export interface Trace {
id: string;
conversationId?: string;
operationType: 'consensus_pipeline' | 'single_stage' | 'api_call' | 'system_operation';
startTime: number;
endTime?: number;
totalDuration?: number;
spans: TraceSpan[];
rootSpan: TraceSpan;
user?: string;
environment: string;
tags: Record<string, string | number>;
performance: {
criticalPath: string[];
bottlenecks: BottleneckAnalysis[];
efficiency: number;
recommendations: string[];
};
}
export interface BottleneckAnalysis {
spanId: string;
operationName: string;
component: string;
impact: 'low' | 'medium' | 'high' | 'critical';
duration: number;
percentageOfTotal: number;
cause: string;
recommendation: string;
}
export interface TracingConfig {
enabled: boolean;
samplingRate: number;
maxTraces: number;
retentionDays: number;
detailLevel: 'minimal' | 'standard' | 'verbose';
components: {
consensus: boolean;
openrouter: boolean;
database: boolean;
validator: boolean;
system: boolean;
};
profiling: {
enabled: boolean;
memoryTracking: boolean;
cpuProfiling: boolean;
stackTraces: boolean;
};
}
export declare class PipelineTracer {
private traces;
private activeSpans;
private config;
private cleanupTimer?;
constructor(config?: Partial<TracingConfig>);
/**
* Start a new trace
*/
startTrace(operationType: Trace['operationType'], operationName: string, options?: {
conversationId?: string;
user?: string;
tags?: Record<string, string | number>;
}): string | null;
/**
* Start a new span within a trace
*/
startSpan(traceId: string, operationName: string, component: TraceSpan['component'], options?: {
parentId?: string;
tags?: Record<string, string | number | boolean>;
}): string | null;
/**
* Finish a span
*/
finishSpan(spanId: string, status?: TraceSpan['status'], error?: Error): void;
/**
* Add a log entry to a span
*/
addSpanLog(spanId: string, level: TraceLog['level'], message: string, fields?: Record<string, any>): void;
/**
* Set span tags
*/
setSpanTags(spanId: string, tags: Record<string, string | number | boolean>): void;
/**
* Finish a trace and perform analysis
*/
private finishTrace;
/**
* Analyze trace performance and identify bottlenecks
*/
private analyzeTrace;
/**
* Calculate the critical path through the trace
*/
private calculateCriticalPath;
/**
* Identify performance bottlenecks
*/
private identifyBottlenecks;
/**
* Calculate trace efficiency
*/
private calculateEfficiency;
/**
* Generate performance recommendations
*/
private generateRecommendations;
/**
* Get trace by ID
*/
getTrace(traceId: string): Trace | undefined;
/**
* Get all traces with optional filtering
*/
getTraces(filter?: {
operationType?: string;
conversationId?: string;
user?: string;
since?: Date;
status?: 'active' | 'completed' | 'error';
}): Trace[];
/**
* Get trace statistics
*/
getTracingStats(): {
totalTraces: number;
activeTraces: number;
averageDuration: number;
averageEfficiency: number;
componentBreakdown: Record<string, number>;
bottleneckFrequency: Record<string, number>;
};
/**
* Export trace data
*/
exportTraces(format?: 'json' | 'jaeger' | 'zipkin'): string;
/**
* Helper methods
*/
private shouldSample;
private isComponentEnabled;
private captureInitialMetrics;
private captureFinalMetrics;
private categorizeImpact;
private identifyBottleneckCause;
private generateBottleneckRecommendation;
private findSequentialSpans;
private formatAsJaeger;
private formatAsZipkin;
private startCleanupTimer;
private cleanupOldTraces;
private enforceTraceLimit;
/**
* Update tracing configuration
*/
updateConfig(newConfig: Partial<TracingConfig>): void;
/**
* Get current configuration
*/
getConfig(): TracingConfig;
/**
* Cleanup and stop tracing
*/
shutdown(): void;
}
/**
* Global pipeline tracer instance
*/
export declare const globalPipelineTracer: PipelineTracer;
//# sourceMappingURL=pipeline-tracer.d.ts.map