운영 가이드에 함정 3개를 추가하다
목차
어느 정도 규모 있는 시스템을 운영하다 보면, 팀원들이 반복해서 같은 곳에서 헤매는 지점들이 생긴다. 사소해 보이지만 진단 과정을 몇 배로 길게 만드는 함정들 말이다. 이번엔 그런 함정 3개를 공식 운영 문서(hedvion-CLAUDE.md)에 정리했다. 각 항목이 왜 함정이 되는지, 어떻게 구분하고 진단하는지를 중심으로 남겼다.
함정 1: 동적 카운터 0 ≠ 수집 실패
제일 먼저 문제를 삼은 것은 동적 카운터가 0이라는 값 자체였다. 어떤 배치 작업이나 수집 파이프라인을 모니터링하다 보면, "이번 수집에서 가져온 항목이 0개네?" 라는 상황이 잦다. 여기서 팀원들이 자주 하는 실수가 "0 = 수집 실패"로 곧바로 결론짓는 것이다.
하지만 현실은 더 복잡하다. 우리 시스템에서 동적 카운터가 0이 되는 이유는 여러 가지다:
- 실제로 그 주기에 새로운 항목이 없었다 (정상)
- API 응답은 성공했으나 필터 조건에 의해 항목이 제외됐다
- 네트워크 재시도 로직이 작동 중이고 아직 완료되지 않았다
- 실제 수집 실패 (에러 로그 있음)
0이라는 숫자만 봐서는 이 중 어느 경우인지 알 수 없다. 그래서 이제는 카운터 + 로그 상태 + 마지막 성공 시점 + 에러 메시지 이 네 가지를 함께 봐야 한다고 문서에 명시했다. 동적 카운터가 0이어도 모든 헬스 체크가 녹색이고 마지막 실행이 분 단위로 최신이면, 그건 정상이다.
함정 2: Holodex urllib User-Agent 403
두 번째 함정은 외부 API 통신에서 비롯됐다. Holodex라는 외부 데이터 소스와 연동할 때, User-Agent 헤더 없이 urllib로 요청하면 403 에러가 떨어진다는 것이다.
얼핏 보면 "API 인증 실패" 같은 권한 문제처럼 느껴진다. 그래서 API 키를 다시 확인하거나 엔드포인트가 잘못됐나 의심하게 된다. 하지만 실제로는 HTTP 클라이언트가 User-Agent를 전송하지 않았을 때, 서버가 의도적으로 거부하는 것이다. 많은 공개 API가 봇 트래픽이나 스크래핑을 막기 위해 User-Agent 필드를 강제하는 정책이 있다.
이 문제를 피하려면:
- 기본 urllib 호출 시 헤더에 User-Agent를 명시적으로 추가
- requests 라이브러리 같은 상위 레이어는 보통 기본 User-Agent를 탑재하지만, 커스텀 헤더를 추가할 땐 그것도 확인
- API 문서에 User-Agent 요구사항이 명시되어 있지 않아도 생각 없이 요청하지 말 것
이 함정은 "403이 모두 권한 문제는 아니다"는 일반론으로 확장된다. HTTP 상태 코드만 봐서 원인을 단정하면 안 된다는 뜻이다.
함정 3: 라이브 폴링 ≠ 모든 항목
세 번째는 라이브 폴링 결과의 해석이다. 우리 시스템에서 라이브 피드를 수집할 때, Holodex 소스로부터의 폴링 결과가 "0 업데이트"로 집계되는 경우가 자주 생긴다. 여기서 팀이 자주 하는 착각은 "라이브 폴링이 실패했나?" 라는 의심이다.
하지만 라이브 데이터 특성상, 특정 폴링 주기에는 정말 새로운 항목이 없을 수 있다. 예를 들어:
- 라이브 이벤트가 드물거나 시간대가 맞지 않는다
- Holodex가 집계하는 소스 자체가 그 시점에 업데이트되지 않았다
- 폴링 간격이 너무 짧아서 중복 제거 후 0개가 되는 경우
"라이브 폴링 = Holodex(0 업데이트)"는 정상 상태일 수 있다는 점을 문서에 명확히 했다. 다만 시간대별 폴링 성공률, 평균 업데이트 수, 마지막 성공 시점을 대시보드에서 함께 확인해야 실제 문제인지 판단할 수 있다.
운영 문서화의 의도
이 세 함정을 문서화한 이유는, 팀이 다음에 비슷한 상황을 마주쳤을 때 "어디를 먼저 의심할지", "뭘 체크해야 할지"를 빠르게 판단하도록 돕기 위함이다. 모니터링 alert가 울렸을 때마다 처음부터 진단하는 수고를 줄이는 것이 운영 문서의 본질이다.
또한 이런 함정들은 대개 한 번의 실패, 한 명의 삽질에서 비롯된다. 그 경험을 문서화하는 것이 조직의 학습 속도를 높인다. 다음번 누군가 같은 함정에 빠졌을 때 "어? 이 부분 CLAUDE에 있었네"라고 빠르게 참고할 수 있으니까.
실제로 운영 규모가 커질수록, "설마 이 정도는 다들 알겠지"라는 가정이 위험해진다. 팀이 자라고, 신입이 들어오고, 야간 당직자가 바뀌면, 같은 함정을 반복적으로 밟는다. 그래서 이런 사소해 보이는 "함정 정리"가 결국 팀 전체의 운영 신뢰성을 높이는 핵심 투자가 된다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.