---
title: "Configura el logging de FastAPI y maneja los errores sin perder la traza de pila"
description: "FastAPI no imprimió ningún log info hasta que configuramos el logging, y solo uvicorn imprimió la traza de pila de un error 500. Aquí tienes la configuración, los handlers de errores y LogBrew, probado en FastAPI 0.165."
canonical: "https://logbrew.co/es/guides/fastapi-logging"
last_updated: "2026-11-21"
---

# Configura el logging de FastAPI y maneja los errores sin perder la traza de pila

FastAPI no imprimió ningún log `info` hasta que configuramos el logging, y solo uvicorn imprimió la traza de pila de un error 500. Aquí tienes la configuración, los handlers de errores y LogBrew, probado en FastAPI 0.165.

Probado el 21 de noviembre de 2026 con Python 3.13.5, FastAPI 0.165.0, uvicorn 0.54.0, logbrew-sdk 0.1.29, logbrew-fastapi 0.1.14 y logbrew CLI 0.1.96

Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday es el fundador de LogBrew. Desarrolla LogBrew con Claude Code y Codex todos los días.

Canonical: https://logbrew.co/es/guides/fastapi-logging

## Qué imprime FastAPI sin configuración y qué recibe LogBrew

| Evento | Impreso sin configuración | Incidencia o log en LogBrew |
| --- | --- | --- |
| `logger.debug()` | Descartado | Descartado en `INFO` |
| `logger.info()` | Descartado | Log `info` |
| `logger.warning()` | Solo el mensaje | Log `warning` |
| `ValueError` en una ruta | Traza de pila de uvicorn | Incidencia |
| Valor de ruta que no es número, 422 | Solo la línea de acceso | Span, sin incidencia |
| `HTTPException`, 404 | Solo la línea de acceso | Span, sin incidencia |

6 eventos en FastAPI 0.165.0 con uvicorn 0.54.0, y luego los mismos con `basicConfig()` y logbrew-fastapi 0.1.14.

## Registra logs desde una app de FastAPI

### Mira qué imprime FastAPI sin configuración

Nuestra app tiene 1 logger llamado `taproom` y 3 rutas. La iniciamos con `uvicorn main:app`. uvicorn solo configura sus propios loggers, así que Python imprimió `warning` y los niveles superiores como texto plano, y descartó `debug` e `info`.

```bash
import logging

from fastapi import FastAPI, HTTPException

app = FastAPI()
logger = logging.getLogger("taproom")


@app.get("/taps/{tap}")
def pour(tap: str):
    logger.debug("keg pressure read")
    logger.info("tap %s opened", tap)
    logger.warning("keg below 10%")
    logger.error("keg empty")
    logger.critical("cooler offline")
    return {"tap": tap}


@app.get("/kegs/{keg_id}")
def keg(keg_id: int):
    raise ValueError(f"keg {keg_id} is empty")


@app.get("/missing")
def missing():
    raise HTTPException(status_code=404, detail="no such tap")
```

Salida

```text
keg below 10%
keg empty
cooler offline
INFO:     127.0.0.1:51421 - "GET /taps/ipa HTTP/1.1" 200 OK
```

### Llama a basicConfig() antes de crear la app

`logging.basicConfig()` le da al logger raíz un nivel y un formato. Las líneas de `taproom` ahora muestran su nivel, y aparece `info`. uvicorn mantiene su propio formato.

```bash
import logging
import os

from fastapi import FastAPI, HTTPException

logging.basicConfig(
    level=os.environ.get("LOG_LEVEL", "INFO"),
    format="%(levelname)s %(name)s %(message)s",
)

app = FastAPI()
logger = logging.getLogger("taproom")
```

Salida

```text
INFO taproom tap ipa opened
WARNING taproom keg below 10%
ERROR taproom keg empty
CRITICAL taproom cooler offline
INFO:     127.0.0.1:51428 - "GET /taps/ipa HTTP/1.1" 200 OK
```

### Lee el nivel del entorno

La llamada a `basicConfig()` de arriba lee `LOG_LEVEL`. Inicia uvicorn con `LOG_LEVEL=DEBUG` y aparece la línea `debug`, sin cambiar el código.

```bash
LOG_LEVEL=DEBUG uvicorn main:app
```

Salida

```text
DEBUG taproom keg pressure read
INFO taproom tap ipa opened
WARNING taproom keg below 10%
ERROR taproom keg empty
CRITICAL taproom cooler offline
INFO:     127.0.0.1:51442 - "GET /taps/ipa HTTP/1.1" 200 OK
```

## Maneja los errores en FastAPI

### Mira qué imprime una excepción no controlada

El cliente recibió `Internal Server Error` con estado 500. uvicorn imprimió `Exception in ASGI application` y la traza de pila. La ruta `/kegs/abc` devolvió 422 con una lista `detail`, y `HTTPException` devolvió su `detail` con 404. Ninguno de los dos imprimió traza de pila. Recortamos 27 frames de uvicorn, Starlette y FastAPI.

```bash
curl localhost:8000/kegs/7
curl localhost:8000/kegs/abc
curl localhost:8000/missing
```

Salida

```text
INFO:     127.0.0.1:51422 - "GET /kegs/7 HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  …
  File "main.py", line 21, in keg
    raise ValueError(f"keg {keg_id} is empty")
ValueError: keg 7 is empty
INFO:     127.0.0.1:51423 - "GET /kegs/abc HTTP/1.1" 422 Unprocessable Content
INFO:     127.0.0.1:51424 - "GET /missing HTTP/1.1" 404 Not Found
```

### Añade un handler de excepciones para `Exception`

El handler registra el error y devuelve tu propio JSON, y el cliente recibió `{"error":"internal"}`. uvicorn imprimió la traza de pila de todos modos, porque Starlette vuelve a lanzar la excepción después de enviar tu respuesta. Así que la traza de pila apareció 2 veces.

```bash
from fastapi import Request
from fastapi.responses import JSONResponse


@app.exception_handler(Exception)
async def on_error(request: Request, exc: Exception):
    logger.exception("request failed")
    return JSONResponse({"error": "internal"}, status_code=500)
```

Salida

```text
ERROR taproom request failed
Traceback (most recent call last):
  …
  File "main.py", line 34, in keg
    raise ValueError(f"keg {keg_id} is empty")
ValueError: keg 7 is empty
INFO:     127.0.0.1:51436 - "GET /kegs/7 HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  …
  File "main.py", line 34, in keg
    raise ValueError(f"keg {keg_id} is empty")
ValueError: keg 7 is empty
```

## Envía los logs y errores de FastAPI a LogBrew

### Instala el paquete

`logbrew-fastapi` también instala `logbrew-sdk`. Usa una clave de servidor de tu proyecto de LogBrew.

```bash
python3 -m pip install logbrew-sdk logbrew-fastapi
```

### Llama a init_logbrew() después de crear la app

`init_logbrew()` registra un span por cada solicitud y cada error no controlado como incidencia. `logbrew.logging_handler` envía las entradas de tu logger. Enviamos a un servidor local de LogBrew, así que nuestra copia también pasó un `transport`.

```bash
import logging
import os

from fastapi import FastAPI, HTTPException
from logbrew_fastapi import init_logbrew

logging.basicConfig(
    level=os.environ.get("LOG_LEVEL", "INFO"),
    format="%(levelname)s %(name)s %(message)s",
)

app = FastAPI()
logbrew = init_logbrew(
    app, api_key=os.environ["LOGBREW_API_KEY"], service_name="taproom"
)
logger = logging.getLogger("taproom")
logger.addHandler(logbrew.logging_handler)
```

### Lee la incidencia y los logs

Volvimos a enviar las mismas 4 solicitudes y leímos el proyecto con una clave de lectura. El error 500 se convirtió en 1 incidencia con el nombre de la plantilla de ruta. Los 4 logs de `/taps/ipa` comparten 1 ID de traza. El 422 y el 404 no crearon ninguna incidencia.

```bash
logbrew issues --since 1h
logbrew read logs --since 1h
```

Salida

```text
Issues (1)
- b100cd3d-f932-57c7-8f23-38067f1c87d7 unresolved error priority=medium GET /kegs/{keg_id} failed occurrences=1 users=unknown last_seen=2026-11-21T06:44:18.663Z service=taproom trace=6b642297fc5d4259b1f17f2bf83b1abb assignee=unassigned [unversioned / production]
Logs (4)
- error keg empty service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
- warning keg below 10% service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
- critical cooler offline service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
- info tap ipa opened service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
```

### Comprueba qué conserva la incidencia

La incidencia conserva el tipo de excepción, la ruta y 21 frames de la pila, pero no el mensaje. LogBrew escribe `Unhandled exception` en su lugar.

```bash
logbrew issues --since 1h --json | jq '.[0].attributes | {
  message, exception,
  route: .metadata.routeTemplate,
  frames: (.stackFrames | length)
}'
```

Salida

```text
{
  "message": "Unhandled exception",
  "exception": {
    "mechanism": {
      "handled": false,
      "type": "fastapi.middleware"
    },
    "type": "ValueError"
  },
  "route": "/kegs/{keg_id}",
  "frames": 21
}
```

### Conserva el mensaje con tu handler de excepciones

Con el handler de excepciones de arriba, LogBrew siguió registrando la incidencia, y el log `request failed` conservó el mensaje que la incidencia deja fuera.

```bash
logbrew read logs --since 1h --severity error \
  --search "request failed" --json | jq '.[0] | {
  message,
  exceptionName: .attributes.metadata.exceptionName,
  exceptionMessage: .attributes.metadata.exceptionMessage
}'
```

Salida

```text
{
  "message": "request failed",
  "exceptionName": "ValueError",
  "exceptionMessage": "keg 7 is empty"
}
```

## Lo que vimos al probarlo

Ejecutamos 1 app de FastAPI 0.165.0 con uvicorn 0.54.0 en Python 3.13.5, llamamos a cada ruta con curl y leímos la salida del servidor. Después añadimos logbrew-fastapi 0.1.14 y leímos lo que guardó un servidor local de LogBrew.

uvicorn imprimió la traza de pila de cada excepción no controlada, con handler o sin él. Los errores que FastAPI convierte en respuesta, como un 422 o una `HTTPException`, solo dejaron la línea de acceso.

| Solicitud | `status_code` | Traza de pila impresa | Incidencia en LogBrew |
| --- | --- | --- | --- |
| `/kegs/7` | `500` | Sí | Sí |
| `/kegs/abc` | `422` | No | No |
| `/missing` | `404` | No | No |

## Niveles de log de FastAPI y la salida de uvicorn

Python tiene 5 niveles, `DEBUG`, `INFO`, `WARNING`, `ERROR` y `CRITICAL`. Sin configuración, el logger raíz descarta cada registro por debajo de `WARNING`.

uvicorn imprime sus líneas de acceso y sus errores con su propio formato, y `basicConfig()` no los cambió. LogBrew conserva `warning`, `error` y `critical` tal cual, y guarda `DEBUG` e `INFO` como `info`.

|  | Sin configuración | `basicConfig()` | LogBrew |
| --- | --- | --- | --- |
| `logger.debug()` | No | Con `LOG_LEVEL=DEBUG` | No |
| `logger.info()` | No | Sí | `info` |
| `logger.warning()` | Sí | Sí | `warning` |
| `logger.error()` | Sí | Sí | `error` |
| `logger.critical()` | Sí | Sí | `critical` |

## Qué registra LogBrew

`init_logbrew()` registra 1 span por solicitud, con el nombre de la plantilla de ruta, como `GET /kegs/{keg_id}`. Una excepción no controlada añade una incidencia con el tipo de excepción, el mecanismo `fastapi.middleware`, `handled: false` y los frames de la pila.

Un log escrito durante una solicitud lleva el ID de traza de esa solicitud. Las solicitudes 422 y 404 crearon spans sin error.

- `init_logbrew()`
  - Incidencia: `GET /kegs/{keg_id} failed`
  - `exception.type`: `ValueError`
  - `mechanism`: `fastapi.middleware`
  - `handled`: `false`
  - Frames de pila: 21
- `logbrew.logging_handler`
  - Mensaje: `request failed`
  - `exceptionName`: `ValueError`
  - `exceptionMessage`: `keg 7 is empty`

## Preguntas frecuentes

### ¿Cómo configuro el logging en FastAPI?

Llama a `logging.basicConfig()` una vez al principio de `main.py` y luego usa `logging.getLogger()` en cada módulo. Sin configuración, Python descarta `info` y `debug`.

### ¿Cómo manejo todas las excepciones en FastAPI?

Añade `@app.exception_handler(Exception)` y devuelve tu propia respuesta. El cliente recibe tu respuesta, y uvicorn imprime la traza de pila de todos modos.

### ¿Por qué FastAPI devuelve 422?

Un valor de la ruta, de la query o del body no coincidía con su tipo. `/kegs/abc` no pasó la validación `keg_id: int`, así que FastAPI devolvió la lista `detail` con estado 422.

### ¿Qué significa `Exception in ASGI application`?

Una excepción salió de tu ruta y ningún handler la detuvo. uvicorn la registra con la traza de pila, y el cliente recibe `Internal Server Error` con estado 500.

## Ve cada error de FastAPI con su ruta

logbrew-fastapi registra cada error no controlado como una incidencia con el nombre de su plantilla de ruta, y envía tus logs con la traza de su solicitud. Empieza con el generoso plan gratuito, sin tarjeta.

[Empezar gratis](https://logbrew.co/es)

## Fuentes

- [FastAPI docs, Install custom exception handlers](https://fastapi.tiangolo.com/tutorial/handling-errors/#install-custom-exception-handlers)
- [FastAPI docs, Use HTTPException](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)
- [fastapi/fastapi#14071](https://github.com/fastapi/fastapi/discussions/14071)

## Más guías para agentes, Python, Node.js y React

- [Añade un servidor MCP a Claude Code y Codex](https://logbrew.co/es/guides/mcp-server-claude-code-codex)
- [Usa AGENTS.md en Claude Code y Codex](https://logbrew.co/es/guides/agents-md)
- [Soluciona el error 529 overloaded y el error 429 de rate limit en Claude](https://logbrew.co/es/guides/claude-overloaded-rate-limit-error)
- [Configura el módulo Python logging con los niveles de log correctos y captura de excepciones](https://logbrew.co/es/guides/python-logging)
- [Structured logging con un formato de log y niveles que puedes buscar por campo](https://logbrew.co/es/guides/structured-logging)
- [Configura el logging en Node.js con Pino o Winston sin perder ningún error](https://logbrew.co/es/guides/node-logging)
- [Configura el logging de Django y conserva la traza de pila de cada error 500](https://logbrew.co/es/guides/django-logging)
- [Añade un error boundary de React y registra los errores que se le escapan](https://logbrew.co/es/guides/react-error-boundary)
- [Trace ID vs span ID, decodificados de una cabecera traceparent real](https://logbrew.co/es/guides/trace-id)
- [Guías de errores, logs, trazas, métricas y versiones](https://logbrew.co/es/guides)
