Create utils/debug_utils.py

api/utils/debug_utils.py

@@ -0,0 +1,70 @@
+# FILE: api/utils/debug_utils.py
+# DESCRIPTION: A utility for detailed function logging and debugging.
+
+import os
+import functools
+import logging
+import torch
+
+# Define o nível de log. Mude para "INFO" para desativar os logs detalhados.
+# Você pode controlar isso com uma variável de ambiente.
+LOG_LEVEL = os.environ.get("ADUC_LOG_LEVEL", "DEBUG").upper()
+logging.basicConfig(level=LOG_LEVEL, format='[%(levelname)s] [%(name)s] %(message)s')
+logger = logging.getLogger("AducDebug")
+
+
+def _format_value(value):
+    """Formata os valores dos argumentos para uma exibição concisa e informativa."""
+    if isinstance(value, torch.Tensor):
+        return f"Tensor(shape={list(value.shape)}, device='{value.device}', dtype={value.dtype})"
+    if isinstance(value, str) and len(value) > 70:
+        return f"'{value[:70]}...'"
+    if isinstance(value, list) and len(value) > 5:
+        return f"List(len={len(value)})"
+    if isinstance(value, dict) and len(value.keys()) > 5:
+        return f"Dict(keys={list(value.keys())[:5]}...)"
+    return repr(value)
+
+def log_function_io(func):
+    """
+    Um decorador que registra as entradas, saídas e exceções de uma função.
+    Ele é ativado apenas se o nível de log estiver definido como DEBUG.
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # Só executa a lógica de log se o nível for DEBUG
+        if logger.isEnabledFor(logging.DEBUG):
+            # Obtém o nome do módulo e da função
+            func_name = f"{func.__module__}.{func.__name__}"
+            
+            # Formata os argumentos de entrada
+            args_repr = [_format_value(a) for a in args]
+            kwargs_repr = {k: _format_value(v) for k, v in kwargs.items()}
+            signature = ", ".join(args_repr + [f"{k}={v}" for k, v in kwargs_repr.items()])
+
+            # Log de Entrada
+            logger.debug(f"================ INÍCIO: {func_name} ================")
+            logger.debug(f"  -> ENTRADA: ({signature})")
+
+            try:
+                # Executa a função original
+                result = func(*args, **kwargs)
+                
+                # Formata e registra o resultado
+                result_repr = _format_value(result)
+                logger.debug(f"  <- SAÍDA: {result_repr}")
+                
+            except Exception as e:
+                # Registra qualquer exceção que ocorra
+                logger.error(f"  <-- ERRO em {func_name}: {e}", exc_info=True)
+                raise  # Re-lança a exceção para não alterar o comportamento do programa
+            finally:
+                # Log de Fim
+                logger.debug(f"================ FIM: {func_name} ================\n")
+            
+            return result
+        else:
+            # Se o log não estiver em modo DEBUG, executa a função sem nenhum overhead.
+            return func(*args, **kwargs)
+            
+    return wrapper