File size: 7,226 Bytes
22087d0 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | """
LLM Debug Logger - Logs INPUT/OUTPUT/DB_WRITE with date-first sorted filenames.
Usage:
from core.utils.llm_debugger import llm_debug
# Log LLM input
correlation_id = llm_debug.log_input(model="gpt-4", messages=[...])
# Log LLM output
llm_debug.log_output(model="gpt-4", content="...", correlation_id=correlation_id)
# Log DB write
llm_debug.log_db_write(operation="INSERT", table="messages", record_id="...")
Files are saved to debug_streams/ with date-first filenames for proper sorting:
- 20260122_103045_123456_INPUT.json
- 20260122_103045_234567_OUTPUT.json
- 20260122_103045_345678_DB_WRITE.json
Enable with DEBUG_SAVE_LLM_IO=true in config.
"""
import json
import uuid
from pathlib import Path
from datetime import datetime, timezone
from typing import Dict, Any, List, Optional
from core.utils.logger import logger
class LLMDebugLogger:
"""
Centralized debug logger for LLM operations.
Logs are saved to debug_streams/ with date-first filenames for proper sorting.
Each log includes a correlation_id to track related operations.
"""
_instance = None
_debug_dir: Path = None
def __new__(cls):
if cls._instance is None:
cls._instance = super().__new__(cls)
cls._instance._debug_dir = Path("debug_streams")
return cls._instance
def _is_enabled(self) -> bool:
"""Check if debug logging is enabled (lazy check for config availability)."""
try:
from core.utils.config import config
return config and getattr(config, 'DEBUG_SAVE_LLM_IO', False)
except ImportError:
return False
def _get_filename(self, event_type: str) -> str:
"""Generate date-first filename: YYYYMMDD_HHMMSS_microseconds_TYPE.json"""
now = datetime.now(timezone.utc)
timestamp = now.strftime("%Y%m%d_%H%M%S")
micros = now.strftime("%f")[:6]
return f"{timestamp}_{micros}_{event_type}.json"
def _ensure_dir(self) -> bool:
"""Ensure debug directory exists."""
try:
self._debug_dir.mkdir(exist_ok=True)
return True
except Exception as e:
logger.warning(f"[LLM_DEBUG] Failed to create debug dir: {e}")
return False
def _write_log(self, event_type: str, data: Dict[str, Any]) -> Optional[str]:
"""Write a debug log file. Returns filepath on success."""
if not self._is_enabled():
return None
if not self._ensure_dir():
return None
try:
filename = self._get_filename(event_type)
filepath = self._debug_dir / filename
# Add metadata
data["_event_type"] = event_type
data["_timestamp"] = datetime.now(timezone.utc).isoformat()
with open(filepath, 'w', encoding='utf-8') as f:
json.dump(data, f, indent=2, ensure_ascii=False, default=str)
logger.debug(f"[LLM_DEBUG] Saved {event_type} to: {filename}")
return str(filepath)
except Exception as e:
logger.warning(f"[LLM_DEBUG] Error saving {event_type}: {e}")
return None
def log_input(
self,
model: str,
messages: List[Dict[str, Any]],
correlation_id: Optional[str] = None,
**kwargs
) -> Optional[str]:
"""
Log LLM API call INPUT.
Returns correlation_id for tracking related OUTPUT log.
"""
corr_id = correlation_id or str(uuid.uuid4())[:8]
if not self._is_enabled():
return corr_id
data = {
"correlation_id": corr_id,
"model": model,
"messages": messages,
"message_count": len(messages),
"parameters": {
k: v for k, v in kwargs.items()
if k in ["temperature", "max_tokens", "stop", "stream", "tools",
"tool_choice", "frequency_penalty", "top_p", "response_format"]
}
}
# Add tool names if present
if kwargs.get("tools"):
data["tool_names"] = [t.get("function", {}).get("name", "unknown")
for t in kwargs.get("tools", [])]
self._write_log("INPUT", data)
return corr_id
def log_output(
self,
model: str,
content: str,
tool_calls: Optional[List[Dict[str, Any]]] = None,
finish_reason: Optional[str] = None,
chunk_count: int = 0,
duration_seconds: float = 0,
correlation_id: Optional[str] = None,
**kwargs
) -> None:
"""Log LLM API call OUTPUT (streaming response accumulated)."""
if not self._is_enabled():
return
data = {
"correlation_id": correlation_id or "unknown",
"model": model,
"duration_seconds": round(duration_seconds, 2),
"chunk_count": chunk_count,
"finish_reason": finish_reason,
"content": content,
"content_length": len(content) if content else 0,
}
if tool_calls:
data["tool_calls"] = tool_calls
data["tool_call_count"] = len(tool_calls)
# Add any extra kwargs
data.update(kwargs)
self._write_log("OUTPUT", data)
def log_db_write(
self,
operation: str,
table: str,
record_id: Optional[str] = None,
thread_id: Optional[str] = None,
message_type: Optional[str] = None,
content_preview: Optional[str] = None,
correlation_id: Optional[str] = None,
**kwargs
) -> None:
"""
Log database write operation.
Args:
operation: Type of operation (INSERT, UPDATE, DELETE)
table: Table name (messages, threads, etc.)
record_id: Primary key of the record
thread_id: Associated thread ID
message_type: For messages table - type of message
content_preview: Truncated preview of content (first 500 chars)
correlation_id: For linking to LLM INPUT/OUTPUT
"""
if not self._is_enabled():
return
data = {
"correlation_id": correlation_id or "unknown",
"operation": operation,
"table": table,
}
if record_id:
data["record_id"] = record_id
if thread_id:
data["thread_id"] = thread_id
if message_type:
data["message_type"] = message_type
if content_preview:
# Truncate content preview
preview = str(content_preview)[:500]
if len(str(content_preview)) > 500:
preview += "... [truncated]"
data["content_preview"] = preview
# Add any extra kwargs
data.update(kwargs)
self._write_log("DB_WRITE", data)
# Singleton instance
llm_debug = LLMDebugLogger()
|