구조화된 로깅이란?
개발을 하다 보면 콘솔이나 파일에 로그를 남기는 일이 매우 흔합니다. 그런데 대부분의 로그는 ‘2024-01-10 서버 에러 발생 user=123’ 같은 문자열 형태로 기록됩니다. 이런 방식은 사람이 눈으로 읽기엔 편하지만, 프로그램이 로그를 검색하거나 분석하기엔 매우 불편합니다. 구조화된 로깅(Structured Logging)은 로그를 하나의 ‘문장’이 아니라 ‘데이터’로 다루는 방식입니다. 즉, 로그를 JSON처럼 키와 값으로 구성된 형태로 남겨서, 마치 데이터베이스의 레코드처럼 다룰 수 있게 만드는 것이죠.
예를 들어 기존 로그가 ‘User 123 login failed’라는 문장이었다면, 구조화된 로깅에서는 다음과 같이 표현합니다.
{'event': 'login_failed', 'user_id': 123, 'ip': '192.168.0.1', 'timestamp': '2024-01-10T10:00:00'}
동작 원리와 예시
구조화된 로깅의 핵심은 로그 메시지를 사람이 읽는 문장이 아니라, 기계가 파싱하기 쉬운 ‘필드’들의 집합으로 남기는 것입니다. 비유하자면, 기존 로그가 편지에 손글씨로 상황을 설명하는 것이라면, 구조화된 로그는 엑셀 시트에 항목별로 값을 채워 넣는 것과 비슷합니다. 손글씨 편지는 읽는 사람이 이해하긴 쉽지만, 특정 조건으로 검색하거나 통계를 내기는 어렵습니다. 반면 엑셀 시트는 ‘컬럼:값’ 형태이기 때문에 특정 조건으로 필터링하거나 집계하기가 훨씬 쉽습니다.
실제 개발 환경에서는 Python의 ‘structlog’, Node.js의 ‘pino’, Java의 ‘Logback + Logstash Encoder’ 같은 라이브러리를 사용해 로그를 JSON 형식으로 남깁니다. 이렇게 남긴 로그는 아래와 같은 형태를 가집니다.
- event: 어떤 이벤트가 발생했는지
- level: 로그 심각도 (info, error 등)
- context: user_id, request_id 같은 부가 정보
- timestamp: 발생 시각
실무에서 왜 쓰는가
서비스가 커지고 서버가 여러 대로 늘어나면, 로그도 수백만 건씩 쌓이게 됩니다. 이때 텍스트 로그는 ‘grep’으로 문자열을 찾는 방식이라 한계가 명확합니다. 하지만 구조화된 로그는 Elasticsearch, Datadog, CloudWatch Logs Insights 같은 로그 분석 시스템에 그대로 적재해 SQL과 비슷한 쿼리로 검색할 수 있습니다. 예를 들어 ‘지난 1시간 동안 user_id=123인 사용자의 error 로그만 모아줘’ 같은 질의가 가능해지는 것이죠.
또한 여러 서버에서 발생한 로그를 request_id 같은 공통 필드로 묶으면, 하나의 요청이 여러 서비스를 거치는 과정을 추적하는 분산 트레이싱에도 활용할 수 있습니다. 결국 구조화된 로깅은 단순한 기록을 넘어, 장애 대응 속도와 운영 효율성을 크게 높여주는 실무 필수 기법이라 할 수 있습니다.