Flask JSON 로그 구조화와 요청 ID 상관관계 가이드, 파이썬 에러처리와 관찰성 최적화

🔗 Flask에서 JSON 로그 구조화의 핵심 개념과 장점

로그를 단순한 텍스트 문자열로 남기면 사람이 읽기에는 직관적일 수 있지만, 기계가 분석하기에는 한계가 많습니다.
이 때문에 최근 운영 환경에서는 로그를 JSON 형태로 구조화하는 것이 표준처럼 자리 잡고 있습니다.
JSON 로그는 각 로그 항목이 키와 값으로 나뉘어 있어, 파싱 없이도 검색과 필터링이 쉬워지고 대시보드 구성이나 알림 조건 정의가 단순해집니다.

Flask 같은 파이썬 웹 프레임워크에서도 이러한 JSON 로그 구조화가 점점 필수로 여겨집니다.
단순히 “에러 발생” 같은 메시지를 남기는 대신, 요청 URL, HTTP 메서드, 응답 시간, 사용자 ID, 상태 코드 같은 메타데이터를 함께 기록할 수 있습니다.
이를 통해 문제 상황을 더 빠르고 구체적으로 재현할 수 있고, 마이크로서비스 간 호출 상관관계를 쉽게 추적할 수 있습니다.

📌 JSON 로그가 제공하는 주요 이점

• 📊로그 검색과 집계가 빠르고 효율적입니다.
• 🔎문제 원인 추적 시 필요한 맥락 정보를 자동으로 담을 수 있습니다.
• ⚡모니터링 툴과 자동 연동이 가능해 알림 설정이 간단해집니다.
• 📂다양한 서비스의 로그를 표준 포맷으로 통합할 수 있습니다.

예를 들어 같은 API 요청이라도 단순 텍스트 로그라면 “500 에러 발생”이라는 정보밖에 얻을 수 없습니다.
반면 JSON 로그라면 {“status”:500,”path”:”/api/order”,”latency_ms”:245,”request_id”:”abc123″} 같은 구조화된 데이터를 남길 수 있습니다.
이렇게 하면 오류가 어느 엔드포인트에서, 어떤 요청 흐름에서, 얼마나 오래 걸리다가 발생했는지 한눈에 알 수 있습니다.

🛠️ 표준 로거 설정과 구조화 포맷터 적용 방법

Flask는 기본적으로 파이썬의 logging 모듈을 활용하여 로그를 남깁니다.
따라서 JSON 기반 구조화 로그를 사용하려면 포맷터를 교체해주면 됩니다.
대표적으로 python-json-logger 라이브러리를 사용하면 표준 로거를 JSON 형태로 쉽게 변환할 수 있습니다.

실제 환경에서는 서비스 전역에 동일한 로깅 포맷을 유지하는 것이 중요합니다.
API 요청, 백그라운드 작업, 스케줄러 로그까지 같은 구조를 적용해야 검색과 모니터링이 일관되게 동작합니다.

📌 기본 설정 예제

from flask import Flask
import logging
from pythonjsonlogger import jsonlogger

app = Flask(__name__)

logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter('%(asctime)s %(levelname)s %(name)s %(message)s')
logHandler.setFormatter(formatter)

app.logger.addHandler(logHandler)
app.logger.setLevel(logging.INFO)

@app.route("/")
def index():
    app.logger.info("hello structured log", extra={"path": "/", "method": "GET"})
    return "OK"

위 코드에서는 Flask 기본 로거에 JSON 포맷터를 적용하여, 단순한 텍스트 대신 구조화된 JSON 로그가 출력되도록 설정했습니다.
또한 extra 파라미터를 활용하면 요청에 따른 추가 메타데이터를 손쉽게 포함할 수 있습니다.

📌 운영 환경에서의 고려 사항

⚙️ 요청 ID 생성과 전파, 컨텍스트 상관관계 패턴

서비스가 복잡해질수록 같은 사용자의 요청이 여러 마이크로서비스를 거쳐가며 흐릅니다.
이때 각 로그에 동일한 요청 ID(Request ID)를 붙여주면, 하나의 요청이 어떤 과정을 거쳐 어떤 지점에서 실패했는지를 손쉽게 추적할 수 있습니다.
Flask에서는 미들웨어 또는 before_request 훅을 이용해 요청이 들어올 때 고유 ID를 생성하고, 이를 컨텍스트에 저장해 로깅 시 활용할 수 있습니다.

📌 요청 ID 생성 및 Flask g 객체 활용

import uuid
from flask import Flask, g, request

app = Flask(__name__)

@app.before_request
def assign_request_id():
    g.request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))

@app.after_request
def add_request_id_header(response):
    response.headers["X-Request-ID"] = g.request_id
    return response

위 코드에서는 요청이 들어올 때 X-Request-ID 헤더가 있으면 그대로 사용하고, 없으면 새로 UUID를 생성합니다.
또한 응답 헤더에도 같은 ID를 추가해 호출 체인 전반에서 추적이 가능합니다.

📌 로깅 컨텍스트에 요청 ID 포함하기

JSON 로그 포맷터에서 요청 ID를 자동으로 포함시키면, 모든 로그에 동일한 상관관계 키가 들어가게 됩니다.
이렇게 하면 Kibana, Grafana Loki, Cloud Logging 등에서 request_id로 검색해 호출 전체 흐름을 추적할 수 있습니다.

import logging
from flask import g
from pythonjsonlogger import jsonlogger

class RequestIdFilter(logging.Filter):
    def filter(self, record):
        record.request_id = getattr(g, "request_id", None)
        return True

handler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter('%(asctime)s %(levelname)s %(message)s %(request_id)s')
handler.setFormatter(formatter)
handler.addFilter(RequestIdFilter())

이렇게 구성하면 모든 로그가 {“message”:”error”,”request_id”:”abc123″} 형태로 출력되어, 서비스 전반에서 요청 단위 상관관계가 확보됩니다.

🔌 에러 처리, 예외 로깅, 트레이스 샘플링 전략

애플리케이션이 커질수록 예외 상황은 더 자주 발생하며, 이를 체계적으로 기록하지 않으면 근본 원인 분석이 어렵습니다.
Flask에서는 에러 핸들러와 구조화된 로깅을 결합해 효율적으로 문제를 추적할 수 있습니다.
또한 대규모 트래픽 환경에서는 모든 요청을 추적하기보다 샘플링 전략을 병행해 성능과 비용을 균형 있게 유지해야 합니다.

📌 Flask 에러 핸들러 적용

from flask import jsonify

@app.errorhandler(Exception)
def handle_exception(e):
    app.logger.error("Unhandled exception",
                     exc_info=True,
                     extra={"request_id": getattr(g, "request_id", None)})
    return jsonify({"error": "internal server error"}), 500

이렇게 하면 모든 예외가 로깅되며, stack trace와 request_id가 함께 기록됩니다.
따라서 장애 분석 시 단순한 에러 메시지가 아닌, 발생 맥락과 호출 흐름을 한눈에 파악할 수 있습니다.

📌 트레이스와 샘플링 전략

마이크로서비스 구조에서는 모든 요청을 100% 추적하면 저장 비용과 성능 부담이 커집니다.
이 때문에 샘플링을 적용해 일부 요청만 상세 로깅하는 것이 일반적입니다.
예를 들어 정상 응답은 1%만 기록하고, 오류 응답은 반드시 100% 기록하는 식으로 규칙을 정할 수 있습니다.

💡 운영 환경에서의 수집, 조회, 대시보드 모범사례

구조화된 JSON 로그와 요청 ID를 적용했다면, 이제 중요한 것은 이를 운영 환경에서 어떻게 수집하고 분석하느냐입니다.
대부분의 기업은 ElasticSearch + Kibana, Grafana Loki, AWS CloudWatch 같은 로그 플랫폼을 활용합니다.
이러한 도구는 로그를 단순히 모으는 데 그치지 않고, 검색 쿼리, 시각화 대시보드, 알람 설정까지 지원하여 운영 효율을 극대화합니다.

📌 로그 수집 파이프라인 구성

• 📝애플리케이션 로그를 STDOUT으로 출력
• 📦컨테이너 런타임이나 에이전트(Fluent Bit, Filebeat 등)로 수집
• 🔗로그 저장소(ElasticSearch, Loki 등)에 전송
• 📊분석 및 모니터링 대시보드 구성

📌 대시보드 활용 예시

대시보드는 단순히 로그를 나열하는 공간이 아니라, 운영 지표를 시각적으로 파악하는 핵심 도구입니다.
예를 들어 아래와 같은 패널을 구성하면 장애 탐지와 분석 속도가 크게 단축됩니다.

❓ 자주 묻는 질문 (FAQ)