---
title: "配置 FastAPI 日志处理错误不丢失回溯"
description: "在我们配置日志之前，FastAPI 没有打印任何 info 日志，500 错误的回溯也只有 uvicorn 打印。这里有日志配置、错误处理器和 LogBrew 的用法，全部在 FastAPI 0.165 上实测。"
canonical: "https://logbrew.co/zh-Hans/guides/fastapi-logging"
last_updated: "2026-11-21"
---

# 配置 FastAPI 日志处理错误不丢失回溯

在我们配置日志之前，FastAPI 没有打印任何 `info` 日志，500 错误的回溯也只有 uvicorn 打印。这里有日志配置、错误处理器和 LogBrew 的用法，全部在 FastAPI 0.165 上实测。

2026年11月21日 用 Python 3.13.5、FastAPI 0.165.0、uvicorn 0.54.0、logbrew-sdk 0.1.29、logbrew-fastapi 0.1.14和logbrew CLI 0.1.96 实测

作者 [Furkan Erday](https://github.com/furkanerday). Furkan Erday 是 LogBrew 的创始人，每天用 Claude Code 和 Codex 开发 LogBrew。

Canonical: https://logbrew.co/zh-Hans/guides/fastapi-logging

## 不做配置时 FastAPI 打印什么，LogBrew 又收到什么

| 事件 | 不做配置时的打印 | LogBrew 中的问题或日志 |
| --- | --- | --- |
| `logger.debug()` | 被丢弃 | 在 `INFO` 级别被丢弃 |
| `logger.info()` | 被丢弃 | `info` 日志 |
| `logger.warning()` | 只有消息 | `warning` 日志 |
| 路由里的 `ValueError` | uvicorn 打印的回溯 | 问题 |
| 路径值不是数字，422 | 只有访问日志行 | Span，没有问题 |
| `HTTPException`，404 | 只有访问日志行 | Span，没有问题 |

在 uvicorn 0.54.0 上的 FastAPI 0.165.0 里触发 6 个事件，再用 `basicConfig()` 和 logbrew-fastapi 0.1.14 触发同样的事件。

## 在 FastAPI 应用里记录日志

### 看看不做配置时 FastAPI 打印什么

我们的应用有 1 个名为 `taproom` 的记录器和 3 个路由。我们用 `uvicorn main:app` 启动它。uvicorn 只配置它自己的记录器，所以 Python 把 `warning` 及以上级别打印成纯文本，丢弃了 `debug` 和 `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")
```

输出

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

### 在创建应用之前调用 basicConfig()

`logging.basicConfig()` 给根记录器设置级别和格式。现在 `taproom` 的日志行会显示级别，`info` 也出现了。uvicorn 保持自己的格式。

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

输出

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

### 从环境变量读取级别

上面的 `basicConfig()` 调用会读取 `LOG_LEVEL`。用 `LOG_LEVEL=DEBUG` 启动 uvicorn，不改代码就能看到 `debug` 那一行。

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

输出

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

## 在 FastAPI 里处理错误

### 看看未处理的异常会打印什么

客户端收到了状态码 500 和 `Internal Server Error`。uvicorn 打印了 `Exception in ASGI application` 和回溯。路径 `/kegs/abc` 返回 422 和一个 `detail` 列表，`HTTPException` 用 404 返回了它的 `detail`。这两者都没有打印回溯。我们删掉了 uvicorn、Starlette 和 FastAPI 的 27 个栈帧。

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

输出

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

### 为 Exception 添加异常处理器

处理器记录错误并返回你自己的 JSON，客户端收到了 `{"error":"internal"}`。uvicorn 仍然打印了回溯，因为 Starlette 在发出你的响应之后会再次抛出异常。所以回溯出现了 2 次。

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

输出

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

## 把 FastAPI 日志和错误发到 LogBrew

### 安装依赖包

`logbrew-fastapi` 会一并安装 `logbrew-sdk`。使用你的 LogBrew 项目里的服务端密钥。

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

### 在创建应用之后调用 init_logbrew()

`init_logbrew()` 为每个请求记录一个 Span，并把每个未处理的错误记录为问题。`logbrew.logging_handler` 会发送你的记录器的记录。我们发到的是本地 LogBrew 服务器，所以我们的代码还传了一个 `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)
```

### 读回问题和日志

我们再次发送同样的 4 个请求，并用读取密钥读取项目。500 错误变成了 1 个以路由模板命名的问题。`/taps/ipa` 的 4 条日志共用 1 个链路 ID。422 和 404 没有产生问题。

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

输出

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

### 看看问题保存了什么

问题保存了异常类型、路由和 21 个栈帧，但不保存消息。LogBrew 会在消息的位置写上 `Unhandled exception`。

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

输出

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

### 用你的异常处理器保留消息

加上前面的异常处理器后，LogBrew 依然记录了问题，而 `request failed` 日志保留了问题里缺少的消息。

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

输出

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

## 我们实测看到的结果

我们在 Python 3.13.5 上用 uvicorn 0.54.0 运行了 1 个 FastAPI 0.165.0 应用，用 curl 调用每个路由，并读取服务器输出。然后我们加入 logbrew-fastapi 0.1.14，读取本地 LogBrew 服务器保存的内容。

不管有没有处理器，uvicorn 都打印了每个未处理异常的回溯。FastAPI 转换成响应的错误，比如 422 或 `HTTPException`，只打印了访问日志行。

| 请求 | `status_code` | 打印出的回溯 | LogBrew 中的问题 |
| --- | --- | --- | --- |
| `/kegs/7` | `500` | 是 | 是 |
| `/kegs/abc` | `422` | 否 | 否 |
| `/missing` | `404` | 否 | 否 |

## FastAPI 日志级别与 uvicorn 输出

Python 有 5 个级别，`DEBUG`、`INFO`、`WARNING`、`ERROR` 和 `CRITICAL`。不做配置时，根记录器会丢弃低于 `WARNING` 的每条记录。

uvicorn 用自己的格式打印访问日志行和错误，`basicConfig()` 没有改变它们。LogBrew 原样保留 `warning`、`error` 和 `critical`，并把 `DEBUG` 和 `INFO` 存为 `info`。

|  | 不做配置 | `basicConfig()` | LogBrew |
| --- | --- | --- | --- |
| `logger.debug()` | 否 | 使用 `LOG_LEVEL=DEBUG` | 否 |
| `logger.info()` | 否 | 是 | `info` |
| `logger.warning()` | 是 | 是 | `warning` |
| `logger.error()` | 是 | 是 | `error` |
| `logger.critical()` | 是 | 是 | `critical` |

## LogBrew 记录了什么

`init_logbrew()` 为每个请求记录 1 个 Span，以路由模板命名，例如 `GET /kegs/{keg_id}`。未处理的异常会新增一个问题，带有异常类型、机制 `fastapi.middleware`、`handled: false` 和栈帧。

请求期间写下的日志会带上该请求的链路 ID。422 和 404 请求生成的 Span 都没有错误。

- `init_logbrew()`
  - 问题: `GET /kegs/{keg_id} failed`
  - `exception.type`: `ValueError`
  - `mechanism`: `fastapi.middleware`
  - `handled`: `false`
  - 堆栈帧: 21
- `logbrew.logging_handler`
  - 消息: `request failed`
  - `exceptionName`: `ValueError`
  - `exceptionMessage`: `keg 7 is empty`

## 常见问题

### 怎么在 FastAPI 里配置日志？

在 `main.py` 顶部调用 1 次 `logging.basicConfig()`，然后在每个模块里用 `logging.getLogger()`。不做配置时，Python 会丢弃 `info` 和 `debug`。

### 怎么在 FastAPI 里处理所有异常？

添加 `@app.exception_handler(Exception)` 并返回你自己的响应。客户端会收到你的响应，uvicorn 仍然会打印回溯。

### FastAPI 为什么返回 422？

路径、查询参数或请求体里的某个值和类型不匹配。`/kegs/abc` 没通过 `keg_id: int` 的检查，所以 FastAPI 用状态码 422 返回了 `detail` 列表。

### Exception in ASGI application 是什么意思？

有个异常离开了你的路由，没有任何处理器拦下它。uvicorn 会连同回溯一起记录它，客户端收到状态码 500 和 `Internal Server Error`。

## 查看每个 FastAPI 错误及其路由

logbrew-fastapi 把每个未处理的错误记录为以路由模板命名的问题，并把你的日志和对应请求的链路一起发送。免费额度充足，无需绑卡。

[免费开始](https://logbrew.co/zh-Hans)

## 参考来源

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

## 更多智能体、Python、Node.js 与 React 指南

- [在 Claude Code 和 Codex 中添加 MCP 服务器](https://logbrew.co/zh-Hans/guides/mcp-server-claude-code-codex)
- [在 Claude Code 和 Codex 中使用 AGENTS.md](https://logbrew.co/zh-Hans/guides/agents-md)
- [解决 Claude overloaded 529 错误和 rate limit 429 错误](https://logbrew.co/zh-Hans/guides/claude-overloaded-rate-limit-error)
- [配置 Python 日志用对日志级别并捕获异常和回溯](https://logbrew.co/zh-Hans/guides/python-logging)
- [结构化日志用能按字段搜索的日志格式和日志级别](https://logbrew.co/zh-Hans/guides/structured-logging)
- [用 Pino 或 Winston 配置 Node.js 日志一个错误都不丢](https://logbrew.co/zh-Hans/guides/node-logging)
- [配置 Django 日志保留每个 500 错误的回溯信息](https://logbrew.co/zh-Hans/guides/django-logging)
- [给 React 加上错误边界并记录它漏掉的错误](https://logbrew.co/zh-Hans/guides/react-error-boundary)
- [Trace ID 和 Span ID 的区别，用真实的 traceparent 请求头解读](https://logbrew.co/zh-Hans/guides/trace-id)
- [错误、日志、链路、指标和版本指南](https://logbrew.co/zh-Hans/guides)
