---
title: "FastAPI のログを設定してトレースバックを失わずにエラーを処理する"
description: "ログを設定するまで FastAPI は info のログを出力せず、500 エラーのトレースバックを出したのは uvicorn だけでした。設定、エラーハンドラー、LogBrew を FastAPI 0.165 で検証してまとめました。"
canonical: "https://logbrew.co/ja/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/ja/guides/fastapi-logging

## 設定なしで FastAPI が出力する内容と、LogBrew に届く内容

| イベント | 設定なしの出力 | LogBrew の問題またはログ |
| --- | --- | --- |
| `logger.debug()` | 破棄 | `INFO` で破棄 |
| `logger.info()` | 破棄 | `info` のログ |
| `logger.warning()` | メッセージのみ | `warning` のログ |
| ルートでの `ValueError` | uvicorn のトレースバック | 問題 |
| 数値でないパスの値、422 | アクセス行のみ | スパンのみ、問題なし |
| `HTTPException`、404 | アクセス行のみ | スパンのみ、問題なし |

uvicorn 0.54.0 上の FastAPI 0.165.0 で 6 つのイベントを起こし、次に同じものを `basicConfig()` と logbrew-fastapi 0.1.14 で起こしました。

## FastAPI アプリからログを出す

### 設定なしで FastAPI が出力する内容を見る

このアプリには `taproom` という 1 つのロガーと 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` は `detail` のリストつきで 422 を返し、`HTTPException` は自身の `detail` を 404 で返しました。どちらもトレースバックは出力しませんでした。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()` はリクエストごとにスパンを記録し、処理されなかった各エラーを問題として記録します。`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 件のログは同じトレース 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 を使って FastAPI 0.165.0 のアプリを 1 つ動かし、curl で各ルートを呼び出して、サーバーの出力を読みました。その後 logbrew-fastapi 0.1.14 を追加し、ローカルの LogBrew サーバーに保存された内容を読みました。

uvicorn は、ハンドラーの有無にかかわらず、処理されなかった例外のトレースバックをすべて出力しました。422 や `HTTPException` のように FastAPI がレスポンスに変えるエラーでは、アクセス行だけが出ました。

| リクエスト | `status_code` | 出力されたトレースバック | LogBrew の問題 |
| --- | --- | --- | --- |
| `/kegs/7` | `500` | はい | はい |
| `/kegs/abc` | `422` | いいえ | いいえ |
| `/missing` | `404` | いいえ | いいえ |

## FastAPI のログレベルと uvicorn の出力

Python には `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` の 5 つのレベルがあります。設定しないと、ルートロガーは `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 つのスパンを記録し、`GET /kegs/{keg_id}` のようにルートのテンプレート名をつけます。処理されなかった例外は、例外の型、メカニズム `fastapi.middleware`、`handled: false`、スタックフレームを持つ問題を追加します。

リクエスト中に書いたログには、そのリクエストのトレース ID がつきます。422 と 404 のリクエストは、エラーのないスパンになりました。

- `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` の先頭で `logging.basicConfig()` を 1 回呼び出し、各モジュールでは `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/ja)

## 出典

- [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/ja/guides/mcp-server-claude-code-codex)
- [Claude Code と Codex で AGENTS.md を使う](https://logbrew.co/ja/guides/agents-md)
- [Claude の overloaded エラー 529 とレート制限エラー 429 を解決する](https://logbrew.co/ja/guides/claude-overloaded-rate-limit-error)
- [Python logging を正しいログレベルと例外の記録つきで設定する](https://logbrew.co/ja/guides/python-logging)
- [構造化ログ（structured logging）でフィールドから検索できるログの書式とログレベルを整える](https://logbrew.co/ja/guides/structured-logging)
- [Node.js のログを Pino か Winston でエラーを失わずに設定する](https://logbrew.co/ja/guides/node-logging)
- [Django のログを設定してすべての 500 エラーのトレースバックを残す](https://logbrew.co/ja/guides/django-logging)
- [React にエラーバウンダリを追加してそれが見逃すエラーも記録する](https://logbrew.co/ja/guides/react-error-boundary)
- [トレース ID とスパン ID の違いを実際の traceparent ヘッダーで解読](https://logbrew.co/ja/guides/trace-id)
- [エラー、ログ、トレース、メトリクス、リリースのガイド](https://logbrew.co/ja/guides)
