Logging

Saptiva-Agents utiliza el módulo de registro (logging) incorporado en Python.

Hay dos tipos de registro (logging):

• Registro de seguimiento (trace logging): Se utiliza para depuración y son mensajes legibles por humanos que indican lo que está sucediendo. Está destinado a que un desarrollador entienda lo que ocurre en el código. El contenido y formato de estos logs no deben ser usados por otros sistemas.

  • Nombre: TRACE_LOGGER_NAME

• Registro estructurado (structured logging): Este logger emite eventos estructurados que pueden ser consumidos por otros sistemas. El contenido y formato de estos logs sí deben ser considerados por otros sistemas.

  • Nombre: EVENT_LOGGER_NAME

ROOT_LOGGER_NAME puede utilizarse para habilitar o deshabilitar todos los logs.

---

Habilitar Salida de Logs

Para habilitar el registro de seguimiento, puedes utilizar el siguiente código:

import logging
from saptiva_agents.core import TRACE_LOGGER_NAME

# Configura el nivel de logging general
logging.basicConfig(level=logging.WARNING)

# Obtiene el logger de trazas
logger = logging.getLogger(TRACE_LOGGER_NAME)

# Agrega un manejador para imprimir en consola
logger.addHandler(logging.StreamHandler())

# Establece el nivel de trazas en DEBUG
logger.setLevel(logging.DEBUG)

Para habilitar el logging estructurado, puedes usar el siguiente código:

import logging
from saptiva_agents.core import EVENT_LOGGER_NAME

# Configura el nivel de logging general
logging.basicConfig(level=logging.WARNING)

# Obtiene el logger de eventos estructurados
logger = logging.getLogger(EVENT_LOGGER_NAME)

# Agrega un manejador para imprimir en consola
logger.addHandler(logging.StreamHandler())

# Establece el nivel de eventos estructurados en INFO
logger.setLevel(logging.INFO)

---

Logging Estructurado

El logging estructurado permite escribir lógica que maneje los eventos reales con todos sus campos, en lugar de solo una cadena de texto formateada.

Por ejemplo, si definimos un evento personalizado y lo emitimos, podemos escribir el siguiente manejador:

import logging
from dataclasses import dataclass

@dataclass
class MyEvent:
    timestamp: str
    message: str

class MyHandler(logging.Handler):
    def __init__(self) -> None:
        super().__init__()

    def emit(self, record: logging.LogRecord) -> None:
        try:
            # Usa StructuredMessage si el mensaje es una instancia del evento personalizado
            if isinstance(record.msg, MyEvent):
                print(f"Timestamp: {record.msg.timestamp}, Message: {record.msg.message}")
        except Exception:
            self.handleError(record)

Y así es como puedes usarlo:

logger = logging.getLogger(EVENT_LOGGER_NAME)
logger.setLevel(logging.INFO)
my_handler = MyHandler()
logger.handlers = [my_handler]

---

Emitir Logs

Los nombres anteriores (TRACE_LOGGER_NAME y EVENT_LOGGER_NAME) son los loggers raíz para cada tipo. El código que emite logs debe usar un logger hijo de estos. Por ejemplo, si estás escribiendo un módulo my_module y quieres emitir logs de trazas, puedes hacer lo siguiente:

import logging
from saptiva_agents.core import TRACE_LOGGER_NAME

# Logger para trazas dentro del módulo my_module
logger = logging.getLogger(f"{TRACE_LOGGER_NAME}.my_module")

---

Emitir Logs Estructurados

Si tu evento es un dataclass, puedes emitirlo así:

import logging
from dataclasses import dataclass
from saptiva_agents.core import EVENT_LOGGER_NAME

@dataclass
class MyEvent:
    timestamp: str
    message: str

logger = logging.getLogger(EVENT_LOGGER_NAME + ".my_module")
logger.info(MyEvent("timestamp", "message"))