로그 포맷 파싱 버그로 일부 사이트 적재 실패 문제 수정
목차
여러 사이트의 로그를 한데 모아 집계하는 시스템에서, 특정 로그 포맷이 제대로 파싱되지 않아 일부 사이트(kpopdex, vtuberprofile)의 페이지뷰 데이터가 0으로 기록되는 버그를 마주했다. 요청이 들어올 때마다 데이터가 적재되지 않는 상황이 반복되다 보니 원인을 추적해서 파싱 로직과 문서화를 함께 정리했다.
배경: 로그 수집 시스템의 포맷 다양성
회사에서 운영하는 여러 사이트들은 각자 로그를 남기는 방식이 조금씩 다르다. 어떤 사이트는 Apache의 표준 로그 포맷을 쓰고, 어떤 사이트는 Nginx의 커스텀 포맷을 쓰고, 또 어떤 사이트는 자체 로깅 미들웨어로 별도의 형식을 사용한다. 처음에 site-pv.py 는 가장 흔한 1-2개 포맷만 지원하도록 짜여 있었는데, 사이트 개수가 늘어나면서 "우리는 왜 우리 로그가 못 들어오나?" 같은 질문이 점점 빈번해진 거다.
내가 팀을 이끌면서 배운 것 중 하나는, 초기에 멀티사이트 대응을 염두에 두지 않은 채 짠 코드는 나중에 포맷 하나 추가할 때마다 주변 코드를 자꾸만 건드리게 된다는 것이다. 파싱 로직이 여기저기에 산재되면, 수정할 때마다 "혹시 다른 데도 영향을 미치지 않을까" 하는 생각에 항상 조심스러워져야 한다.
vhost 포맷 파싱 누락의 원인
kpopdex와 vtuberprofile 은 전용 로그 디렉터리에 vhost 포맷이라고 부르는 방식으로 로그를 남기고 있었다. 이 포맷은 다른 사이트들보다 약간 더 이른 구조였기 때문에, 사실 처음에 시스템을 설계할 때는 대다수 사이트가 표준 포맷을 쓸 거라는 가정 하에 두 가지 포맷만 처리하도록 했다. 그런데 두 사이트가 이 vhost 포맷을 고집하다 보니, 적재 스크립트가 그들의 로그를 "모르는 포맷"으로 분류해 버리고, 결국 데이터 행 자체가 건너뛰어지는 일이 발생한 것이다.
결과적으로 kpopdex와 vtuberprofile의 일일 집계 통계는 항상 0으로 나왔다. 모니터링 대시보드에서 그 두 사이트만 유독 평탄했다. 처음에는 "로그가 안 들어오나 봐요" 하고 넘어갔다가, 로그 파일 자체는 잘 쌓이는데 왜 수집이 안 되는지 확인해야 한다는 요청이 들어온 거다.
수정 방향: 포맷 추가와 문서화
이 문제를 해결하면서 나는 두 가지 일을 동시에 진행했다.
첫째, site-pv.py 에 vhost 포맷 파싱 로직을 추가했다. 포맷의 구조를 먼저 정확히 파악하고, 기존 포맷 파서들과 동일한 인터페이스를 쓰도록 구현했다. 이렇게 하면 새로운 포맷이 추가될 때마다 나머지 파이프라인은 건드릴 필요가 없다. 메인 로직은 "어떤 포맷인지 감지 → 맞는 파서 선택 → 공통 구조로 변환" 이런 식으로 추상화되어 있으니까.
둘째, CLAUDE.md 에 각 사이트의 로그 포맷과 그에 맞는 파싱 규칙을 명시했다. 다음번에 새로운 사이트나 새로운 로그 포맷을 추가할 때, 팀원들이 "아, 이 사이트는 vhost 포맷이구나. 그럼 site-pv.py 의 vhost_parser 섹션을 보면 되겠네" 하고 빠르게 판단할 수 있도록 한 거다. 문서를 먼저 정리하는 것은 팀 온보딩 비용을 줄이고, 실수로 인한 재작업을 방지하는 데 매우 효과적이다.
학습과 확장성 재점검
이번 경험으로 내가 배운 점은, 시스템 초기 설계 단계에서 확장성 경로를 명확히 해 두는 것의 중요성이다. 멀티사이트 시스템을 짤 때는:
- 포맷이 하드코딩되지 않도록, 파서를 플러그인 형태로 설계하는 것
- 각 포맷마다 테스트 케이스를 준비해 두는 것
- 새로운 포맷 추가 시 체크리스트를 문서화해 두는 것
이런 작은 결정들이 나중에 "이 기능도 여기 적용되나요?" 하는 질문과 "우리 로그 왜 안 들어가요?" 같은 버그를 크게 줄여준다.
또한 이번에 CLAUDE.md를 함께 수정한 이유는, 코드 리뷰나 운영 매뉴얼은 코드만큼이나 중요하다는 생각에서다. 팀원이 나중에 비슷한 문제를 마주쳤을 때 문서를 먼저 보고 "아, 이미 해결된 케이스구나" 하고 빠르게 대응할 수 있도록 하는 게 팀 리딩 입장에서 가장 효율적이다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.