Saltar al contenido principal
LogBrew es una plataforma de observabilidad para desarrolladores y agentes de programación, con un plan gratuito generoso y sin tarjeta. Esta guía cubre el logging en Python con el módulo estándar logging, los 5 niveles de log de Python, el manejo de errores en Python y los tipos de errores más comunes de Python. Las últimas secciones envían los mismos logs y fallos a LogBrew con logbrew-sdk 0.1.29. Cada ejemplo se ejecutó con Python 3.13, y cada bloque de salida muestra su salida real. Para una app de Flask, usa Logging en Flask. Esa guía añade trazas de solicitudes a la misma configuración de logging.

Escribe tu primer log de Python

Guarda este archivo como app.py. Llama a logging.basicConfig() una sola vez, en el punto de entrada del programa. Obtén un logger con nombre en cada módulo.
Ejecuta python3 app.py. La salida va a la salida de error estándar.
El registro debug no aparece, porque el nivel es INFO. logger.exception() registra en ERROR y añade el traceback. Llámalo solo dentro de un bloque except. Pasa los valores como argumentos, como en "payment retry %d of %d", 2, 3. Python construye el mensaje solo cuando un handler acepta el registro. La plantilla del mensaje es la misma en cada reintento, así que puedes buscarla.

Niveles de log en Python

Un logger envía un registro solo cuando el nivel del registro es igual o mayor que el nivel del logger. Un handler puede fijar un segundo nivel, más alto. El logger raíz empieza en WARNING. Un logger nuevo tiene el nivel NOTSET (0) y usa el nivel de su padre. Usa INFO en producción y DEBUG solo en desarrollo o para un diagnóstico breve.
La primera línea muestra los registros de debug de un módulo. La segunda línea elimina el ruido de una biblioteca.

Loggers, handlers y formatters

  • Un logger recibe la llamada. Usa logging.getLogger(__name__) para que el nombre del logger siga la ruta del módulo.
  • Un handler envía los registros a un destino, como la consola, un archivo o LogBrew.
  • Un formatter convierte un registro en texto.
Una biblioteca no debe configurar el logging. Solo añade un logging.NullHandler() a su propio logger. La aplicación configura los handlers y los niveles una sola vez. Para una configuración grande, usa logging.config.dictConfig().

Manejo de errores en Python

Captura la excepción más específica que puedas manejar. Usa else para el código que solo se ejecuta si todo sale bien. Usa finally para el código que siempre se ejecuta. Usa raise ... from error para conservar la causa original. Guarda este archivo como orders.py.
La salida muestra las dos excepciones de la cadena de excepciones.
Sigue estas reglas para cada excepción.
  • Registra una excepción una sola vez, donde la manejas. No la registres y la vuelvas a lanzar en cada capa, porque cada capa añade un registro duplicado.
  • No escribas except Exception: pass. Si ignoras un error, regístralo en WARNING o superior con el motivo.
  • Captura Exception, no BaseException. BaseException también captura KeyboardInterrupt y SystemExit, que detienen el programa a propósito.
  • Define tus propias clases de excepción para los errores que debe manejar el código que llama, como hace OrderError.

Informa de más de un error

Python 3.11 y posteriores pueden lanzar un ExceptionGroup. Úsalo cuando una comprobación encuentra más de un problema. Maneja cada tipo con except*.

Tipos de errores comunes en Python

Todos los errores integrados que un programa puede manejar heredan de Exception. Esta tabla muestra los errores de Python más frecuentes y la primera comprobación para cada uno. KeyboardInterrupt y SystemExit heredan de BaseException, no de Exception. No son errores de tu código.

Envía logs de Python a LogBrew

LogBrewLoggingHandler es un handler de logging estándar. Envía a LogBrew cada registro que acepta. El handler de consola no cambia.
1

Crea una clave de proyecto

Inicia sesión con la CLI. Crea un proyecto y guarda su clave de ingesta en un archivo al que solo accede su propietario.
La CLI no muestra la clave. En producción, usa el gestor de secretos de tu plataforma.
2

Instala el SDK

Activa el entorno virtual de la aplicación. Después, instala el paquete. Requiere Python 3.10 o posterior.
3

Define la clave y la identidad del despliegue

El cliente añade el servicio, el entorno y el release a cada evento.
4

Añade el handler

Guarda este archivo como worker.py. Llama a logging.basicConfig() antes de crear el cliente. El cliente añade un handler al logger raíz, y basicConfig() no hace nada si el logger raíz ya tiene un handler.
HttpTransport() envía los eventos en segundo plano, 1 segundo después del primer evento o al llegar a 50 eventos. client.shutdown() envía los eventos pendientes y cierra el cliente.
5

Ejecuta el programa

La salida de la consola no cambia. LogBrew recibe 1 evento de log por cada registro. Este es el primer evento, sin el contexto de ejecución compartido.
Los valores primitivos de extra={...} pasan a ser metadatos. El segundo evento tiene exceptionName KeyError y exceptionMessage 'seats'. Para enviar el texto completo del traceback, crea el handler con include_exception_text=True.
6

Vuelve a leer los logs

Una lectura con resultados muestra que LogBrew guardó los logs. Para leer desde CI o desde un agente de programación, usa una clave de lectura del proyecto. Consulta Verifica tu configuración.

Elige qué registros van a LogBrew

Dale al handler su propio nivel para enviar menos registros. La consola sigue recibiendo INFO y superior.
Los niveles de Python se convierten en niveles de LogBrew. El nombre y el número originales del nivel se quedan en los metadatos.

Informa de los fallos de Python como incidencias

install_process_error_capture(client) informa de las excepciones no capturadas en scripts, workers, código de arranque e hilos. Cada fallo se convierte en 1 incidencia con el tipo de excepción, el mensaje, los marcos de pila y las causas encadenadas. Python sigue mostrando el traceback y termina como antes. Guarda este archivo como startup.py y ejecútalo.
LogBrew recibe una incidencia con el título FileNotFoundError, el nivel critical y el mecanismo python.excepthook. Sus marcos contienen el nombre del archivo, la línea y la función, pero no la ruta completa. Un fallo en un hilo tiene el nivel error. Antes de que Python termine, el SDK espera como máximo 2 segundos para la entrega.
La incidencia incluye el mensaje de la excepción. No pongas credenciales ni datos personales en los mensajes de excepción ni en los mensajes de log. Consulta Controlar los datos capturados.

Soluciona problemas

Para apps web, consulta Logging en Flask. Para elegir un formato de log, consulta Logging estructurado. Para otros entornos de ejecución, consulta Integración del SDK.