---
title: "FastAPI 로깅을 설정하고 트레이스백을 잃지 않고 오류 처리하기"
description: "로깅을 설정하기 전까지 FastAPI는 info 로그를 출력하지 않았고, 500 오류의 트레이스백은 uvicorn만 출력했어요. 설정, 오류 핸들러, LogBrew 연동을 FastAPI 0.165에서 직접 테스트해 정리했어요."
canonical: "https://logbrew.co/ko/guides/fastapi-logging"
last_updated: "2026-11-21"
---

# FastAPI 로깅을 설정하고 트레이스백을 잃지 않고 오류 처리하기

로깅을 설정하기 전까지 FastAPI는 `info` 로그를 출력하지 않았고, 500 오류의 트레이스백은 uvicorn만 출력했어요. 설정, 오류 핸들러, LogBrew 연동을 FastAPI 0.165에서 직접 테스트해 정리했어요.

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 환경에서 2026년 11월 21일에 테스트

글 [Furkan Erday](https://github.com/furkanerday). LogBrew 창업자 Furkan Erday. 매일 Claude Code와 Codex로 LogBrew를 만들어요.

Canonical: https://logbrew.co/ko/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가 `detail` 목록을 상태 코드 422로 반환했어요.

### Exception in ASGI application은 무슨 뜻인가요?

예외가 라우트 밖으로 나왔고 어떤 핸들러도 막지 않았다는 뜻이에요. uvicorn은 예외를 트레이스백과 함께 기록하고, 클라이언트는 상태 코드 500과 함께 `Internal Server Error`를 받아요.

## FastAPI 오류를 라우트와 함께 확인하세요

logbrew-fastapi는 처리되지 않은 오류를 각각 라우트 템플릿 이름이 붙은 이슈로 기록하고, 로그를 해당 요청의 트레이스와 함께 보내요. 넉넉한 무료 요금제로 시작하세요. 카드 등록은 필요 없어요.

[무료로 시작](https://logbrew.co/ko)

## 출처

- [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/ko/guides/mcp-server-claude-code-codex)
- [Claude Code와 Codex에서 AGENTS.md 쓰기](https://logbrew.co/ko/guides/agents-md)
- [Claude overloaded 529 오류와 rate limit 429 오류 해결하기](https://logbrew.co/ko/guides/claude-overloaded-rate-limit-error)
- [Python logging을 올바른 로그 레벨과 예외 기록까지 설정하기](https://logbrew.co/ko/guides/python-logging)
- [필드로 검색할 수 있는 로그 포맷과 로그 레벨로 구조화 로깅하기](https://logbrew.co/ko/guides/structured-logging)
- [Node.js 로깅을 Pino나 Winston으로 오류 하나 놓치지 않게 설정하기](https://logbrew.co/ko/guides/node-logging)
- [Django 로깅을 설정하고 모든 500 오류의 트레이스백 남기기](https://logbrew.co/ko/guides/django-logging)
- [React에 error boundary를 추가하고 놓치는 오류까지 기록하기](https://logbrew.co/ko/guides/react-error-boundary)
- [트레이스 ID와 스팬 ID 차이, 실제 traceparent 헤더로 해석하기](https://logbrew.co/ko/guides/trace-id)
- [오류, 로그, 트레이스, 메트릭, 릴리스 가이드](https://logbrew.co/ko/guides)
