---
title: "Configure o logging do FastAPI e trate os erros sem perder o stack trace"
description: "O FastAPI não imprimiu nenhum log info até configurarmos o logging, e só o uvicorn imprimiu o stack trace de um erro 500. Veja a configuração, os handlers de erro e o LogBrew, testados no FastAPI 0.165."
canonical: "https://logbrew.co/pt-BR/guides/fastapi-logging"
last_updated: "2026-11-21"
---

# Configure o logging do FastAPI e trate os erros sem perder o stack trace

O FastAPI não imprimiu nenhum log `info` até configurarmos o logging, e só o uvicorn imprimiu o stack trace de um erro 500. Veja a configuração, os handlers de erro e o LogBrew, testados no FastAPI 0.165.

Testado em 21 de novembro de 2026 com Python 3.13.5, FastAPI 0.165.0, uvicorn 0.54.0, logbrew-sdk 0.1.29, logbrew-fastapi 0.1.14 e logbrew CLI 0.1.96

Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday é o fundador do LogBrew. Ele desenvolve o LogBrew com Claude Code e Codex todos os dias.

Canonical: https://logbrew.co/pt-BR/guides/fastapi-logging

## O que o FastAPI imprime sem configuração e o que o LogBrew recebe

| Evento | Impresso sem configuração | Problema ou log no LogBrew |
| --- | --- | --- |
| `logger.debug()` | Descartado | Descartado em `INFO` |
| `logger.info()` | Descartado | Log `info` |
| `logger.warning()` | Só a mensagem | Log `warning` |
| `ValueError` numa rota | Stack trace do uvicorn | Problema |
| Valor do caminho que não é número, 422 | Só a linha de acesso | Span, sem problema |
| `HTTPException`, 404 | Só a linha de acesso | Span, sem problema |

6 eventos no FastAPI 0.165.0 com uvicorn 0.54.0, depois os mesmos com `basicConfig()` e o logbrew-fastapi 0.1.14.

## Gere logs num app FastAPI

### Veja o que o FastAPI imprime sem configuração

Nosso app tem 1 logger chamado `taproom` e 3 rotas. Iniciamos com `uvicorn main:app`. O uvicorn configura só os próprios loggers, então o Python imprimiu `warning` e os níveis acima como texto puro, e descartou `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")
```

Saída

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

### Chame basicConfig() antes de criar o app

`logging.basicConfig()` dá ao logger raiz um nível e um formato. As linhas de `taproom` agora mostram o nível, e `info` aparece. O uvicorn mantém o próprio 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")
```

Saída

```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
```

### Leia o nível do ambiente

A chamada de `basicConfig()` acima lê `LOG_LEVEL`. Inicie o uvicorn com `LOG_LEVEL=DEBUG` e a linha `debug` aparece, sem mudar o código.

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

Saída

```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
```

## Trate erros no FastAPI

### Veja o que uma exceção não tratada imprime

O cliente recebeu `Internal Server Error` com status 500. O uvicorn imprimiu `Exception in ASGI application` e o stack trace. O caminho `/kegs/abc` devolveu 422 com uma lista `detail`, e `HTTPException` devolveu o seu `detail` com 404. Nenhum dos dois imprimiu stack trace. Cortamos 27 frames do uvicorn, do Starlette e do FastAPI.

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

Saída

```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
```

### Adicione um handler de exceções para `Exception`

O handler registra o erro e devolve o seu próprio JSON, e o cliente recebeu `{"error":"internal"}`. O uvicorn imprimiu o stack trace mesmo assim, porque o Starlette lança a exceção de novo depois de enviar a sua resposta. Por isso o stack trace apareceu 2 vezes.

```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)
```

Saída

```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
```

## Envie logs e erros do FastAPI ao LogBrew

### Instale o pacote

`logbrew-fastapi` também instala `logbrew-sdk`. Use uma chave de servidor do seu projeto LogBrew.

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

### Chame init_logbrew() depois de criar o app

`init_logbrew()` registra um span para cada requisição e cada erro não tratado como problema. `logbrew.logging_handler` envia os registros do seu logger. Enviamos para um servidor LogBrew local, então nossa cópia também passou um `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)
```

### Leia o problema e os logs de volta

Enviamos as mesmas 4 requisições de novo e lemos o projeto com uma chave de leitura. O erro 500 virou 1 problema com o nome do template da rota. Os 4 logs de `/taps/ipa` têm o mesmo ID de trace. O 422 e o 404 não criaram problema.

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

Saída

```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]
```

### Confira o que o problema guarda

O problema guarda o tipo da exceção, a rota e 21 frames da pilha, mas não a mensagem. O LogBrew escreve `Unhandled exception` no lugar dela.

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

Saída

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

### Guarde a mensagem com o seu handler de exceções

Com o handler de exceções acima, o LogBrew continuou registrando o problema, e o log `request failed` guardou a mensagem que o problema deixa de fora.

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

Saída

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

## O que vimos no teste

Rodamos 1 app FastAPI 0.165.0 com uvicorn 0.54.0 no Python 3.13.5, chamamos cada rota com curl e lemos a saída do servidor. Depois adicionamos o logbrew-fastapi 0.1.14 e lemos o que um servidor LogBrew local guardou.

O uvicorn imprimiu o stack trace de cada exceção não tratada, com ou sem handler. Erros que o FastAPI transforma em resposta, como um 422 ou uma `HTTPException`, geraram só a linha de acesso.

| Requisição | `status_code` | Stack trace impresso | Problema no LogBrew |
| --- | --- | --- | --- |
| `/kegs/7` | `500` | Sim | Sim |
| `/kegs/abc` | `422` | Não | Não |
| `/missing` | `404` | Não | Não |

## Níveis de log do FastAPI e a saída do uvicorn

O Python tem 5 níveis, `DEBUG`, `INFO`, `WARNING`, `ERROR` e `CRITICAL`. Sem configuração, o logger raiz descarta cada registro abaixo de `WARNING`.

O uvicorn imprime as linhas de acesso e os erros no próprio formato, e o `basicConfig()` não mudou isso. O LogBrew mantém `warning`, `error` e `critical` como estão, e guarda `DEBUG` e `INFO` como `info`.

|  | Sem configuração | `basicConfig()` | LogBrew |
| --- | --- | --- | --- |
| `logger.debug()` | Não | Com `LOG_LEVEL=DEBUG` | Não |
| `logger.info()` | Não | Sim | `info` |
| `logger.warning()` | Sim | Sim | `warning` |
| `logger.error()` | Sim | Sim | `error` |
| `logger.critical()` | Sim | Sim | `critical` |

## O que o LogBrew registra

`init_logbrew()` registra 1 span por requisição, com o nome do template da rota, como `GET /kegs/{keg_id}`. Uma exceção não tratada adiciona um problema com o tipo da exceção, o mecanismo `fastapi.middleware`, `handled: false` e os frames da pilha.

Um log gerado durante uma requisição leva o ID do trace dessa requisição. As requisições 422 e 404 criaram spans sem erro.

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

## Perguntas frequentes

### Como configuro o logging no FastAPI?

Chame `logging.basicConfig()` uma vez no topo de `main.py` e depois use `logging.getLogger()` em cada módulo. Sem configuração, o Python descarta `info` e `debug`.

### Como trato todas as exceções no FastAPI?

Adicione `@app.exception_handler(Exception)` e devolva a sua própria resposta. O cliente recebe a sua resposta, e o uvicorn imprime o stack trace mesmo assim.

### Por que o FastAPI devolve 422?

Um valor do caminho, da query ou do body não bateu com o tipo. `/kegs/abc` falhou na checagem `keg_id: int`, então o FastAPI devolveu a lista `detail` com status 422.

### O que significa `Exception in ASGI application`?

Uma exceção saiu da sua rota e nenhum handler a parou. O uvicorn registra a exceção com o stack trace, e o cliente recebe `Internal Server Error` com status 500.

## Veja cada erro do FastAPI com a sua rota

O logbrew-fastapi registra cada erro não tratado como um problema com o nome do template da rota, e envia seus logs com o trace da requisição deles. Comece no plano gratuito generoso, sem cartão.

[Comece grátis](https://logbrew.co/pt-BR)

## Fontes

- [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)

## Mais guias para agentes, Python, Node.js e React

- [Adicione um servidor MCP ao Claude Code e ao Codex](https://logbrew.co/pt-BR/guides/mcp-server-claude-code-codex)
- [Use AGENTS.md no Claude Code e no Codex](https://logbrew.co/pt-BR/guides/agents-md)
- [Corrija o erro 529 overloaded e o erro 429 de rate limit do Claude](https://logbrew.co/pt-BR/guides/claude-overloaded-rate-limit-error)
- [Configure o Python logging com os níveis de log certos e captura de exceções](https://logbrew.co/pt-BR/guides/python-logging)
- [Structured logging com formato de log e níveis que você busca por campo](https://logbrew.co/pt-BR/guides/structured-logging)
- [Configure o logging em Node.js com Pino ou Winston sem perder nenhum erro](https://logbrew.co/pt-BR/guides/node-logging)
- [Configure o logging do Django e guarde o stack trace de cada erro 500](https://logbrew.co/pt-BR/guides/django-logging)
- [Adicione um error boundary no React e registre os erros que ele deixa passar](https://logbrew.co/pt-BR/guides/react-error-boundary)
- [Trace ID vs span ID, decodificados de um header traceparent real](https://logbrew.co/pt-BR/guides/trace-id)
- [Guias de erros, logs, traces, métricas e versões](https://logbrew.co/pt-BR/guides)
