거짓 timeout으로 헷갈리던 slot 체크, 근본 수정

slot-checkup에서 거짓 timeout 판정이 계속 나타나곤 했다. 사용자 입장에선 "뭐가 문제지?" 싶은 상황이 반복되고, 개발팀도 그 원인을 추적하기 쉽지 않았다. 결국 근본 원인을 파악해 수정했고, 그 과정과 교훈을 문서에 남기는 작업을 했다.

타이밍 버그의 특성

timeout 판정 오류는 특별히 까다로운 종류의 버그다. 코드상으로는 문법적 오류가 없는데도 런타임에 특정 타이밍에만 발동한다. 일반적으로 이런 버그는 다음 같은 상황에서 발생한다:

• 상태 동기화 지연 — slot 상태가 변했다고 예상하지만 실제 반영이 늦음
• 경계 조건 누락 — timeout 임계값 설정은 맞는데, 그 값으로 판단하는 순간의 상황을 놓침
• 비동기 작업의 경쟁 — 여러 비동기 흐름이 엮이면서 불확정적 순서로 실행

slot-checkup처럼 상태 체크 로직은 이 세 가지가 얽힐 수 있는 대표적 영역이다. 특히 timeout은 "지나치게 오래 기다렸나"를 판단하는 것이므로, 시간 경과와 상태 변화가 정확히 짜맞아야 한다.

근본 원인의 흔적

거짓 timeout이 발생하는 상황을 모니터링해보니 패턴이 보였다. 특정 조건(예: 높은 부하 상황, 네트워크 지연, 상태 업데이트 지연)에서만 나타났다는 것은 시스템 타이밍의 문제임을 시사했다.

정상적으로는:
1. slot 상태 요청
2. timeout 경과 시간 체크
3. 충분히 대기했다면 → timeout 판정 (의도된 동작)
4. 아직이면 → 계속 대기

하지만 거짓 timeout은 3번 단계에서 실제로는 아직 대기할 여유가 있었는데도 timeout으로 판정된 경우였다. 원인은 상태 동기화 타이밍과 timeout 계산 사이의 미묘한 괴리였다.

문서화로 팀 신뢰도 높이기

이번 수정을 단순히 코드에만 반영할 수도 있었지만, docs/hedvion-CLAUDE.md에 명시적으로 기록했다. 이유는 세 가지다:

첫째, 재발 방지. 새 팀원이 비슷한 로직을 건드릴 때 "아, 여기는 이런 타이밍 이슈가 있구나"라고 알 수 있다. 커밋 메시지만으로는 한계가 있다.

둘째, 디버깅 효율. 나중에 비슷한 timeout 오류가 다른 시스템에서 나타났을 때, 이 문서를 참고하면 "상태 동기화 지연" 같은 핵심 키워드로 빠르게 진단할 수 있다.

셋째, 팀의 축적된 지식. 혼자만 아는 노하우는 개인의 부담이 된다. 문서화하면 그게 팀의 자산이 된다.

타이밍 버그를 다루는 방식

이런 류의 버그를 다룰 땐 몇 가지 원칙이 있다:

결국 이런 버그가 은근히 많은 이유는 "시간"이라는 변수를 테스트할 때 완전히 통제하기 어렵기 때문이다. 그래서 문서화와 함께 비슷한 패턴을 조기에 잡아내는 코드 리뷰 관점도 중요하다.

다음에 timeout 관련 로직을 건드릴 팀원들이 이 문서를 읽고 한 번 더 신경 쓸 수 있다면, 이번 수정과 문서화 작업의 가치가 있다고 본다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.