FastAPI는 현대적인 Python 웹 애플리케이션 및 API 구축을 위한 강력하고 빠른 프레임워크입니다. 개발한 FastAPI 애플리케이션을 실제 서비스 환경에 배포하기 위해서는 ASGI (Asynchronous Server Gateway Interface) 서버가 필요하며, Uvicorn은 FastAPI 개발팀에서 공식적으로 추천하는 고성능 ASGI 서버입니다.
이번 글에서는 FastAPI 애플리케이션을 Uvicorn으로 서비스하는 기본적인 설정 방법부터, 서비스 운영에 필수적인 로깅 구성까지 자세하게 안내하여 여러분의 애플리케이션을 더욱 안정적이고 효율적으로 관리할 수 있도록 돕겠습니다.
가장 먼저 Uvicorn을 프로젝트 환경에 설치해야 합니다. 터미널을 열고 다음 명령어를 실행하세요.
Bash
pip install uvicorn
설치가 완료되면 간단한 FastAPI 애플리케이션을 작성해 보겠습니다. main.py 파일을 만들고 다음과 같이 코드를 작성하세요.
Python
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello FastAPI with Uvicorn!"}
이제 Uvicorn을 사용하여 이 애플리케이션을 실행해 보겠습니다. 터미널에서 main.py 파일이 있는 디렉토리로 이동한 후 다음 명령어를 실행하세요.
Bash
uvicorn main:app --reload
각 옵션의 의미는 다음과 같습니다.
main: FastAPI 애플리케이션이 정의된 Python 파일 (main.py).app: FastAPI 인스턴스 이름 (app = FastAPI()).--reload: 개발 모드에서 파일 변경 시 서버를 자동으로 재시작하는 옵션입니다. 프로덕션 환경에서는 사용하지 않는 것이 좋습니다.정상적으로 실행되면 터미널에 다음과 유사한 로그가 출력될 것입니다.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [PID] using StatReload
INFO: Started server process [PID]
INFO: Waiting for application startup.
INFO: Application startup complete.
이제 웹 브라우저에서 http://127.0.0.1:8000 주소로 접속하면 {"message": "Hello FastAPI with Uvicorn!"} 라는 JSON 응답을 확인할 수 있습니다.
Uvicorn은 다양한 실행 옵션을 제공하여 서비스 환경에 맞게 세밀하게 설정할 수 있습니다. 몇 가지 중요한 옵션을 살펴보겠습니다.
--host: 서버가 바인딩할 IP 주소를 지정합니다. 기본값은 127.0.0.1 (localhost)이며, 외부 접근을 허용하려면 0.0.0.0으로 설정해야 합니다.--port: 서버가 리스닝할 포트 번호를 지정합니다. 기본값은 8000입니다.--workers: 실행할 워커 프로세스 수를 지정합니다. CPU 코어 수에 맞춰 설정하는 것이 일반적이며, 높은 동시성 처리에 유리합니다.--uds: Unix Domain Socket 경로를 지정하여 네트워크 오버헤드를 줄일 수 있습니다.--ssl-keyfile, --ssl-certfile: HTTPS를 사용하기 위한 SSL 키 파일 및 인증서 파일 경로를 지정합니다.--log-level: 로깅 레벨을 설정합니다 (debug, info, warning, error, critical). 기본값은 info입니다.--access-log: 엑세스 로그 활성화 여부를 설정합니다 (True/False).--no-access-log: 엑세스 로그를 비활성화합니다.프로덕션 환경 실행 예시:
Bash
uvicorn main:app --host 0.0.0.0 --port 80 --workers 4
이 명령어는 IP 주소 0.0.0.0, 포트 80에서 4개의 워커 프로세스로 FastAPI 애플리케이션을 실행합니다.
애플리케이션의 동작을 모니터링하고 문제를 진단하기 위해 로깅은 매우 중요합니다. Uvicorn은 기본적인 로깅 기능을 내장하고 있지만, 필요에 따라 더 세밀한 로깅 구성을 적용할 수 있습니다.
앞서 살펴본 --log-level 옵션을 사용하여 로깅 레벨을 조절할 수 있습니다. 예를 들어, 디버깅 정보를 확인하고 싶다면 --log-level debug 옵션을 추가하여 실행하면 됩니다.
또한, --access-log 옵션을 활성화하면 HTTP 요청에 대한 엑세스 로그를 확인할 수 있습니다.
logging 모듈 활용더욱 강력하고 유연한 로깅 구성을 위해서는 파이썬의 내장 logging 모듈을 활용하는 것이 좋습니다. FastAPI 애플리케이션 코드 내에서 logging 모듈을 설정하여 Uvicorn의 로깅 동작을 제어하고, 애플리케이션 자체의 로그를 통합적으로 관리할 수 있습니다.
main.py 파일을 다음과 같이 수정해 보세요.
Python
import logging
from fastapi import FastAPI
# 로거 인스턴스 생성
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
# 콘솔 핸들러 생성 및 포맷터 설정
ch = logging.StreamHandler()
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
ch.setFormatter(formatter)
# 로거에 핸들러 추가
logger.addHandler(ch)
app = FastAPI()
@app.get("/")
async def root():
logger.info("Root endpoint accessed")
return {"message": "Hello FastAPI with Uvicorn!"}
@app.get("/error")
async def error():
logger.error("Simulated error occurred")
raise HTTPException(status_code=500, detail="Internal Server Error")
from fastapi import HTTPException
이제 Uvicorn을 실행하면 logger.info() 및 logger.error()로 기록한 로그 메시지가 터미널에 출력되는 것을 확인할 수 있습니다.
복잡한 로깅 설정을 애플리케이션 코드에 직접 포함시키는 것보다, 별도의 설정 파일 (logging.config)을 사용하여 관리하는 것이 더 효율적입니다.
logging.ini 파일을 만들고 다음과 같이 로깅 설정을 정의합니다.
Ini, TOML
[loggers]
keys=root,uvicorn,uvicorn.access,uvicorn.error,app
[handlers]
keys=console
[formatters]
keys=simpleFormatter
[logger_root]
level=INFO
handlers=console
[logger_uvicorn]
level=INFO
handlers=console
qualname=uvicorn
propagate=0
[logger_uvicorn.access]
level=INFO
handlers=console
qualname=uvicorn.access
propagate=0
[logger_uvicorn.error]
level=ERROR
handlers=console
qualname=uvicorn.error
propagate=0
[logger_app]
level=INFO
handlers=console
qualname=__main__
propagate=0
[handler_console]
class=StreamHandler
formatter=simpleFormatter
args=(sys.stdout,)
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=
그리고 main.py 파일을 다음과 같이 수정하여 설정 파일을 로드합니다.
Python
import logging.config
import sys
from fastapi import FastAPI, HTTPException
# 로깅 설정 파일 로드
logging.config.fileConfig('logging.ini', disable_existing_loggers=False)
logger = logging.getLogger(__name__)
app = FastAPI()
@app.get("/")
async def root():
logger.info("Root endpoint accessed")
return {"message": "Hello FastAPI with Uvicorn!"}
@app.get("/error")
async def error():
logger.error("Simulated error occurred")
raise HTTPException(status_code=500, detail="Internal Server Error")
이제 Uvicorn을 실행하면 logging.ini 파일에 정의된 설정에 따라 로깅이 이루어집니다. 로깅 레벨, 포맷, 핸들러 등을 설정 파일에서 손쉽게 관리할 수 있습니다.
이번 글에서는 FastAPI 애플리케이션을 Uvicorn으로 서비스하는 기본적인 방법과 다양한 실행 옵션, 그리고 효과적인 로깅 구성 방법에 대해 알아보았습니다. Uvicorn의 강력한 성능과 파이썬 logging 모듈의 유연성을 활용하여 여러분의 FastAPI 애플리케이션을 더욱 안정적이고 효율적으로 운영하시길 바랍니다.
로깅 설정을 통해 애플리케이션의 동작을 꼼꼼하게 기록하고 분석하는 것은 서비스의 안정성을 높이고 문제 발생 시 신속하게 대응하는 데 필수적인 과정입니다. 다양한 로깅 핸들러 (파일, 데이터베이스 등)를 활용하여 더욱 체계적인 로깅 시스템을 구축해 보세요.
댓글목록
등록된 댓글이 없습니다.