웹 개발

헬스체크 엔드포인트가 막힐 때 보는 체크리스트

헬스체크 응답이 느려지거나 실패할 때, 화면만 보면 원인을 놓치기 쉽다. 로그와 응답을 함께 보며 단계별로 원인을 좁혀가는 방법을 정리했다.

2026년 6월 24일·2분 읽기

헬스체크는 간단할수록 좋지만 실제로는 DB 연결, 캐시 상태, 외부 API 호출 등이 섞여 있어서 한 곳이 느려지면 전체가 먹통이 된다. 이럴 때는 큰 그림부터 나누는 게 중요하다.

먼저 브라우저에서 직접 봐야 할 것

APP이 응답하는 기본 동작을 먼저 확인한다. curl이나 Postman으로 헬스체크 엔드포인트를 요청해보고 응답 시간과 상태 코드를 기록한다. 응답이 완전히 없으면 프로세스가 제대로 떠 있는지 확인해야 한다.

curl -i -w '\n%{time_total}\n' https://example.com/health

응답이 2초 이상 걸리면 뭔가 블로킹되고 있다는 뜻이다. 100ms 이내가 정상인데 10배 이상 차이 나면 DB나 캐시 쪽을 의심해본다.

애플리케이션 로그를 보면 헬스체크 함수 진입부터 리턴까지 어디가 오래 걸리는지 나온다. 시간 기록을 남겨두면 다음에 비교할 기준이 생긴다.

# 마지막 100줄의 로그 확인
tail -100 /var/log/app.log | grep -i health

만약 로그에 health 관련 메시지가 안 나온다면 헬스체크 요청 자체가 실행 코드에 도달하지 못하고 있다는 뜻이다. 이건 보통 로드밸런서나 프록시 단에서 타임아웃되는 경우다.

헬스체크가 DB 쿼리를 하는 경우가 많다. 간단한 SELECT 1 정도가 정상이지만, 만약 데이터를 정렬하거나 조인한다면 인덱스가 없을 때 급속도로 느려진다.

# DB에서 직접 같은 쿼리 실행해보기
psql -d dbname -c "EXPLAIN ANALYZE SELECT 1;"

health check의 목적은 "이 서버가 살아있는가"를 빠르게 확인하는 것이다. 복잡한 쿼리를 넣었다면 실제 트래픽 상황에서 다른 쿼리들이 밀려 막힌다.

헬스체크에서 외부 API를 호출하면 그 서버의 응답이 느릴 때 전체가 영향받는다. 멀티테넌시 환경이면 더 복잡하다. 일단 외부 의존성을 제거한 최소한의 체크만 남기고 테스트해본다.

# 요청 타임아웃을 짧게 설정
curl --max-time 1 https://example.com/health

헬스체크가 1초 이상 걸리면 실제 운영에서 문제가 될 때가 있다. 쿠버네티스처럼 컨테이너 오케스트레이션을 쓸 때는 특히 그렇다.

처음 요청할 때는 캐시가 없어서 느리고, 두 번째부터는 빠른 경우가 있다. 헬스체크는 매번 일정한 속도로 응답해야 한다. 캐시를 의존하는 로직을 헬스체크 안에서 제거하는 게 낫다.

이렇게 기록해두면 다음에 비슷한 증상이 나올 때 같은 부분부터 확인하면 된다. 한번에 해결 못 했다면 최소한 다음 단계가 명확하다.