bimquery-api / app /services /query_logger.py
BIM Query Deploy
Claude Opus 4.7 (1M context)
deploy: initial BIM Query API on Hugging Face Spaces
e6be672
Raw History Blame Contribute Delete
10.6 kB
# 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 <https://www.gnu.org/licenses/>.
"""
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