---
title: "Configura il logging di FastAPI e gestisci gli errori senza perdere lo stack trace"
description: "FastAPI non ha stampato nessun log info finché non abbiamo configurato il logging, e solo uvicorn ha stampato lo stack trace di un errore 500. Ecco la configurazione, gli handler degli errori e LogBrew, provati su FastAPI 0.165."
canonical: "https://logbrew.co/it/guides/fastapi-logging"
last_updated: "2026-11-21"
---

# Configura il logging di FastAPI e gestisci gli errori senza perdere lo stack trace

FastAPI non ha stampato nessun log `info` finché non abbiamo configurato il logging, e solo uvicorn ha stampato lo stack trace di un errore 500. Ecco la configurazione, gli handler degli errori e LogBrew, provati su FastAPI 0.165.

Testato il 21 novembre 2026 con 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

Di [Furkan Erday](https://github.com/furkanerday). Furkan Erday è il fondatore di LogBrew. Sviluppa LogBrew ogni giorno con Claude Code e Codex.

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

## Cosa stampa FastAPI senza configurazione e cosa riceve LogBrew

| Evento | Stampato senza configurazione | Problema o log registrato da LogBrew |
| --- | --- | --- |
| `logger.debug()` | Scartato | Scartato a `INFO` |
| `logger.info()` | Scartato | Log `info` |
| `logger.warning()` | Solo il messaggio | Log `warning` |
| `ValueError` in una route | Traceback di uvicorn | Problema |
| Valore del percorso non numerico, 422 | Solo la riga di accesso | Span, nessun problema |
| `HTTPException`, 404 | Solo la riga di accesso | Span, nessun problema |

6 eventi in FastAPI 0.165.0 con uvicorn 0.54.0, poi gli stessi con `basicConfig()` e logbrew-fastapi 0.1.14.

## Scrivi log da un’app FastAPI

### Guarda cosa stampa FastAPI senza configurazione

La nostra app ha 1 logger chiamato `taproom` e 3 route. L’abbiamo avviata con `uvicorn main:app`. uvicorn configura solo i propri logger, quindi Python ha stampato `warning` e i livelli superiori come testo semplice, e ha scartato `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")
```

Output

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

### Chiama basicConfig() prima di creare l’app

`logging.basicConfig()` dà al logger radice un livello e un formato. Le righe di `taproom` ora mostrano il loro livello, e compare `info`. uvicorn mantiene il proprio 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")
```

Output

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

### Leggi il livello dall’ambiente

La chiamata a `basicConfig()` qui sopra legge `LOG_LEVEL`. Avvia uvicorn con `LOG_LEVEL=DEBUG` e compare la riga `debug`, senza cambiare il codice.

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

Output

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

## Gestisci gli errori in FastAPI

### Guarda cosa stampa un’eccezione non gestita

Il client ha ricevuto `Internal Server Error` con stato 500. uvicorn ha stampato `Exception in ASGI application` e lo stack trace. Il percorso `/kegs/abc` ha restituito 422 con una lista `detail`, e `HTTPException` ha restituito il suo `detail` con 404. Nessuno dei due ha stampato uno stack trace. Abbiamo tagliato 27 frame di uvicorn, Starlette e FastAPI.

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

Output

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

### Aggiungi un handler delle eccezioni per `Exception`

L’handler registra l’errore e restituisce il tuo JSON, e il client ha ricevuto `{"error":"internal"}`. uvicorn ha stampato comunque lo stack trace, perché Starlette solleva di nuovo l’eccezione dopo aver inviato la tua risposta. Così lo stack trace è comparso 2 volte.

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

Output

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

## Invia log ed errori di FastAPI a LogBrew

### Installa il pacchetto

`logbrew-fastapi` installa anche `logbrew-sdk`. Usa una chiave server del tuo progetto LogBrew.

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

### Chiama init_logbrew() dopo aver creato l’app

`init_logbrew()` registra uno span per ogni richiesta e ogni errore non gestito come problema. `logbrew.logging_handler` invia i record del tuo logger. Abbiamo inviato a un server LogBrew locale, quindi la nostra copia ha passato anche 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)
```

### Rileggi il problema e i log

Abbiamo inviato di nuovo le stesse 4 richieste e letto il progetto con una chiave di lettura. L’errore 500 è diventato 1 problema con il nome del template della route. I 4 log di `/taps/ipa` condividono 1 ID di traccia. Il 422 e il 404 non hanno creato nessun problema.

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

Output

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

### Controlla cosa conserva il problema

Il problema conserva il tipo di eccezione, la route e 21 frame dello stack, ma non il messaggio. LogBrew scrive `Unhandled exception` al suo posto.

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

Output

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

### Conserva il messaggio con il tuo handler delle eccezioni

Con l’handler delle eccezioni visto sopra, LogBrew ha registrato comunque il problema, e il log `request failed` ha conservato il messaggio che il problema lascia fuori.

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

Output

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

## Cosa abbiamo visto nei test

Abbiamo eseguito 1 app FastAPI 0.165.0 con uvicorn 0.54.0 su Python 3.13.5, chiamato ogni route con curl e letto l’output del server. Poi abbiamo aggiunto logbrew-fastapi 0.1.14 e letto cosa ha salvato un server LogBrew locale.

uvicorn ha stampato lo stack trace di ogni eccezione non gestita, con o senza handler. Gli errori che FastAPI trasforma in risposta, come un 422 o una `HTTPException`, hanno lasciato solo la riga di accesso.

| Richiesta | `status_code` | Traceback stampato | Problema in LogBrew |
| --- | --- | --- | --- |
| `/kegs/7` | `500` | Sì | Sì |
| `/kegs/abc` | `422` | No | No |
| `/missing` | `404` | No | No |

## Livelli di log di FastAPI e l’output di uvicorn

Python ha 5 livelli, `DEBUG`, `INFO`, `WARNING`, `ERROR` e `CRITICAL`. Senza configurazione, il logger radice scarta ogni record sotto `WARNING`.

uvicorn stampa le sue righe di accesso e i suoi errori nel proprio formato, e `basicConfig()` non li ha cambiati. LogBrew conserva `warning`, `error` e `critical` così come sono, e salva `DEBUG` e `INFO` come `info`.

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

## Cosa registra LogBrew

`init_logbrew()` registra 1 span per richiesta, con il nome del template della route, per esempio `GET /kegs/{keg_id}`. Un’eccezione non gestita aggiunge un problema con il tipo di eccezione, il meccanismo `fastapi.middleware`, `handled: false` e i frame dello stack.

Un log scritto durante una richiesta porta l’ID della traccia di quella richiesta. Le richieste 422 e 404 hanno creato span senza errori.

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

## Domande frequenti

### Come configuro il logging in FastAPI?

Chiama `logging.basicConfig()` una volta in cima a `main.py`, poi usa `logging.getLogger()` in ogni modulo. Senza configurazione, Python scarta `info` e `debug`.

### Come gestisco tutte le eccezioni in FastAPI?

Aggiungi `@app.exception_handler(Exception)` e restituisci la tua risposta. Il client riceve la tua risposta, e uvicorn stampa comunque lo stack trace.

### Perché FastAPI restituisce 422?

Un valore del percorso, della query o del body non corrispondeva al suo tipo. `/kegs/abc` non ha superato il controllo `keg_id: int`, quindi FastAPI ha restituito la lista `detail` con stato 422.

### Cosa significa `Exception in ASGI application`?

Un’eccezione è uscita dalla tua route e nessun handler l’ha fermata. uvicorn la registra con lo stack trace, e il client riceve `Internal Server Error` con stato 500.

## Vedi ogni errore FastAPI con la sua route

logbrew-fastapi registra ogni errore non gestito come problema con il nome del template della sua route, e invia i tuoi log con la traccia della loro richiesta. Inizia con il generoso piano gratuito, senza carta.

[Inizia gratis](https://logbrew.co/it)

## Fonti

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

## Altre guide per gli agenti, Python, Node.js e React

- [Aggiungi un server MCP a Claude Code e Codex](https://logbrew.co/it/guides/mcp-server-claude-code-codex)
- [Usa AGENTS.md in Claude Code e Codex](https://logbrew.co/it/guides/agents-md)
- [Risolvi l’errore overloaded 529 e l’errore di rate limit 429 di Claude](https://logbrew.co/it/guides/claude-overloaded-rate-limit-error)
- [Configura il modulo Python logging con i livelli di log giusti e la cattura delle eccezioni](https://logbrew.co/it/guides/python-logging)
- [Structured logging con un formato dei log e livelli che puoi cercare per campo](https://logbrew.co/it/guides/structured-logging)
- [Configura il logging in Node.js con Pino o Winston senza perdere nessun errore](https://logbrew.co/it/guides/node-logging)
- [Configura il logging di Django e conserva lo stack trace di ogni errore 500](https://logbrew.co/it/guides/django-logging)
- [Aggiungi un boundary di errore React e registra gli errori che si lascia sfuggire](https://logbrew.co/it/guides/react-error-boundary)
- [ID traccia vs ID span, decodificati da un vero header traceparent](https://logbrew.co/it/guides/trace-id)
- [Guide su errori, log, tracce, metriche e release](https://logbrew.co/it/guides)
