Skip to main content

Table of Contents

Module spoon_ai.llm.monitoring

Comprehensive monitoring, debugging, and metrics collection for LLM operations.

RequestMetrics Objects​

@dataclass
class RequestMetrics()

Metrics for a single LLM request.

ProviderStats Objects​

@dataclass
class ProviderStats()

Aggregated statistics for a provider.

get​

def get(key: str, default=None)

Get attribute value with default fallback for dictionary-like access.

Arguments:

  • key - Attribute name
  • default - Default value if attribute doesn't exist

Returns:

Attribute value or default

success_rate​

@property
def success_rate() -> float

Calculate success rate as a percentage.

avg_response_time​

@property
def avg_response_time() -> float

Get average response time.

DebugLogger Objects​

class DebugLogger()

Comprehensive logging and debugging system for LLM operations.

__init__​

def __init__(max_history: int = 1000, enable_detailed_logging: bool = True)

Initialize debug logger.

Arguments:

  • max_history - Maximum number of requests to keep in history
  • enable_detailed_logging - Whether to enable detailed request/response logging

log_request​

def log_request(provider: str, method: str, params: Dict[str, Any]) -> str

Log request with unique ID.

Arguments:

  • provider - Provider name
  • method - Method being called (chat, completion, etc.)
  • params - Request parameters

Returns:

  • str - Unique request ID

log_response​

def log_response(request_id: str, response: LLMResponse,
                 duration: float) -> None

Log response with timing information.

Arguments:

  • request_id - Request ID from log_request
  • response - LLM response object
  • duration - Request duration in seconds

log_error​

def log_error(request_id: str, error: Exception, context: Dict[str,
                                                               Any]) -> None

Log error with context.

Arguments:

  • request_id - Request ID from log_request
  • error - Exception that occurred
  • context - Additional error context

log_fallback​

def log_fallback(from_provider: str, to_provider: str, reason: str) -> None

Log provider fallback event.

Arguments:

  • from_provider - Provider that failed
  • to_provider - Provider being used as fallback
  • reason - Reason for fallback

get_request_history​

def get_request_history(provider: Optional[str] = None,
                        limit: Optional[int] = None) -> List[RequestMetrics]

Get request history.

Arguments:

  • provider - Filter by provider (optional)
  • limit - Maximum number of requests to return (optional)

Returns:

  • List[RequestMetrics] - List of request metrics

get_active_requests​

def get_active_requests() -> List[RequestMetrics]

Get currently active requests.

Returns:

  • List[RequestMetrics] - List of active request metrics

clear_history​

def clear_history() -> None

Clear request history.

MetricsCollector Objects​

class MetricsCollector()

Collects and aggregates performance metrics for LLM providers.

__init__​

def __init__(window_size: int = 3600)

Initialize metrics collector.

Arguments:

  • window_size - Time window in seconds for rolling metrics

record_request​

def record_request(provider: str,
                   method: str,
                   duration: float,
                   success: bool,
                   tokens: int = 0,
                   model: str = '',
                   error: Optional[str] = None) -> None

Record request metrics.

Arguments:

  • provider - Provider name
  • method - Method called
  • duration - Request duration in seconds
  • success - Whether request was successful
  • tokens - Number of tokens used
  • model - Model name
  • error - Error message if failed

get_provider_stats​

def get_provider_stats(provider: str) -> Optional[ProviderStats]

Get statistics for a specific provider.

Arguments:

  • provider - Provider name

Returns:

  • Optional[ProviderStats] - Provider statistics or None if not found

get_all_stats​

def get_all_stats() -> Dict[str, ProviderStats]

Get statistics for all providers.

Returns:

Dict[str, ProviderStats]: Dictionary of provider statistics

get_rolling_metrics​

def get_rolling_metrics(provider: Optional[str] = None,
                        method: Optional[str] = None) -> List[Dict[str, Any]]

Get rolling metrics with optional filtering.

Arguments:

  • provider - Filter by provider (optional)
  • method - Filter by method (optional)

Returns:

List[Dict[str, Any]]: List of metrics

get_summary​

def get_summary() -> Dict[str, Any]

Get overall summary statistics.

Returns:

Dict[str, Any]: Summary statistics

reset_stats​

def reset_stats(provider: Optional[str] = None) -> None

Reset statistics.

Arguments:

  • provider - Reset specific provider only (optional)

get_debug_logger​

def get_debug_logger() -> DebugLogger

Get global debug logger instance.

Returns:

  • DebugLogger - Global debug logger

get_metrics_collector​

def get_metrics_collector() -> MetricsCollector

Get global metrics collector instance.

Returns:

  • MetricsCollector - Global metrics collector