# Copyright (C) 2026 Mattia Zatelli # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU Affero General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Affero General Public License for more details. # # You should have received a copy of the GNU Affero General Public License # along with this program. If not, see . """ Comprehensive query logging service for debugging and auditing """ import logging import json from datetime import datetime from typing import Dict, Any, Optional, List from pathlib import Path logger = logging.getLogger(__name__) class QueryLogger: """Comprehensive query logging for debugging""" def __init__(self, log_dir: str = "logs/queries"): self.log_dir = Path(log_dir) self.log_dir.mkdir(parents=True, exist_ok=True) self.query_logger = logging.getLogger("query_audit") self.query_logger.setLevel(logging.INFO) if not self.query_logger.handlers: handler = logging.FileHandler( self.log_dir / "query_audit.jsonl", encoding='utf-8' ) handler.setFormatter(logging.Formatter('%(message)s')) self.query_logger.addHandler(handler) def log_query_start( self, query_id: str, project_id: str, tenant_id: str, query_text: str, query_type: str, request_id: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None ): """Log when a query starts processing""" log_entry = { "event": "query_start", "timestamp": datetime.now().isoformat(), "query_id": query_id, "project_id": project_id, "tenant_id": tenant_id, "request_id": request_id, "query": { "text": query_text, "type": query_type, "length": len(query_text), }, "metadata": metadata or {} } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) logger.info(f"Query started: {query_id} - '{query_text[:100]}'") def log_query_parsing( self, query_id: str, intent: Optional[str] = None, entities: Optional[List[str]] = None, filters: Optional[Dict[str, Any]] = None, metrics: Optional[List[str]] = None, confidence: Optional[float] = None, llm_model: Optional[str] = None, llm_tokens: Optional[int] = None, parsing_time_ms: Optional[int] = None ): """Log query parsing results""" log_entry = { "event": "query_parsing", "timestamp": datetime.now().isoformat(), "query_id": query_id, "parsing": { "intent": intent, "entities": entities or [], "filters": filters or {}, "metrics": metrics or [], "confidence": confidence, }, "llm": { "model": llm_model, "tokens_used": llm_tokens, }, "performance": { "parsing_time_ms": parsing_time_ms, } } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) logger.info(f"Query parsed: {query_id} - intent: {intent}, confidence: {confidence}") def log_query_execution( self, query_id: str, sql_query: Optional[str] = None, execution_time_ms: Optional[int] = None, rows_scanned: Optional[int] = None, rows_returned: Optional[int] = None, cache_hit: Optional[str] = None, indexes_used: Optional[List[str]] = None ): """Log query execution details""" log_entry = { "event": "query_execution", "timestamp": datetime.now().isoformat(), "query_id": query_id, "execution": { "sql_query": sql_query, "execution_time_ms": execution_time_ms, "rows_scanned": rows_scanned, "rows_returned": rows_returned, "cache_hit": cache_hit, "indexes_used": indexes_used or [], } } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) logger.info(f"Query executed: {query_id} - {rows_returned} results in {execution_time_ms}ms") def log_query_results( self, query_id: str, result_count: int, result_summary: Optional[Dict[str, Any]] = None, result_explanation: Optional[str] = None, top_results: Optional[List[Dict[str, Any]]] = None, aggregations: Optional[Dict[str, Any]] = None ): """Log query results""" log_entry = { "event": "query_results", "timestamp": datetime.now().isoformat(), "query_id": query_id, "results": { "count": result_count, "summary": result_summary, "explanation": result_explanation, "top_results": top_results or [], "aggregations": aggregations or {}, } } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) logger.info(f"Query results: {query_id} - {result_count} elements") def log_query_completion( self, query_id: str, status: str, total_time_ms: int, cache_hit: Optional[str] = None, error: Optional[str] = None, error_details: Optional[Dict[str, Any]] = None ): """Log when a query completes (success or failure)""" log_entry = { "event": "query_completion", "timestamp": datetime.now().isoformat(), "query_id": query_id, "completion": { "status": status, "total_time_ms": total_time_ms, "cache_hit": cache_hit, } } if error: log_entry["error"] = { "message": error, "details": error_details or {} } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) if status == "success": logger.info(f"Query completed: {query_id} - {total_time_ms}ms") else: logger.error(f"Query failed: {query_id} - {error}") def log_query_feedback( self, query_id: str, rating: Optional[int] = None, comment: Optional[str] = None, marked_as_favorite: Optional[bool] = None ): """Log user feedback on query""" log_entry = { "event": "query_feedback", "timestamp": datetime.now().isoformat(), "query_id": query_id, "feedback": { "rating": rating, "comment": comment, "marked_as_favorite": marked_as_favorite, } } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) logger.info(f"Query feedback: {query_id} - rating: {rating}") def log_vector_search( self, query_id: str, embedding_model: str, embedding_time_ms: int, vector_dimension: int, search_time_ms: int, candidates_scanned: int, results_returned: int, similarity_threshold: float, top_similarities: Optional[List[float]] = None ): """Log vector similarity search details""" log_entry = { "event": "vector_search", "timestamp": datetime.now().isoformat(), "query_id": query_id, "vector_search": { "embedding": { "model": embedding_model, "dimension": vector_dimension, "time_ms": embedding_time_ms, }, "search": { "time_ms": search_time_ms, "candidates_scanned": candidates_scanned, "results_returned": results_returned, "similarity_threshold": similarity_threshold, "top_similarities": top_similarities or [], } } } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) logger.info(f"Vector search: {query_id} - {results_returned} results from {candidates_scanned} candidates") def log_cache_operation( self, query_id: str, operation: str, cache_key: str, cache_level: Optional[str] = None, hit: Optional[bool] = None, ttl: Optional[int] = None ): """Log cache operations""" log_entry = { "event": "cache_operation", "timestamp": datetime.now().isoformat(), "query_id": query_id, "cache": { "operation": operation, "key": cache_key, "level": cache_level, "hit": hit, "ttl": ttl, } } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) if hit: logger.info(f"Cache hit ({cache_level}): {query_id}") elif hit is False: logger.info(f"Cache miss ({cache_level}): {query_id}") def log_performance_metrics( self, query_id: str, breakdown: Dict[str, int] ): """Log detailed performance breakdown""" log_entry = { "event": "performance_metrics", "timestamp": datetime.now().isoformat(), "query_id": query_id, "performance": breakdown } self.query_logger.info(json.dumps(log_entry, ensure_ascii=False)) total_time = sum(breakdown.values()) logger.info(f"Performance: {query_id} - total: {total_time}ms, breakdown: {breakdown}") # Singleton instance _query_logger_instance = None def get_query_logger() -> QueryLogger: """Get singleton query logger instance""" global _query_logger_instance if _query_logger_instance is None: _query_logger_instance = QueryLogger() return _query_logger_instance