웹을 운영하면서 게시판 메인은 열리는데 검색 결과 화면만 한참 뒤 504로 반환되는 케이스를 간혹 볼 수 있습니다. 같은 서버가 두 화면을 제공해도 검색 요청은 DB 쿼리나 WAS 단계에서 더 오래 걸릴 수 있습니다. 어느 구간이 느렸는지 확인하려면 Nginx가 응답을 기다린 구간과 게시판 앱이 실제로 요청을 처리한 시간을 따로 봐야 합니다. 여기서는 Nginx가 proxy_pass로 HTTP 앱 서버에 검색 요청을 넘기는 구성을 다룹니다. Nginx가 요청을 넘기는 뒤쪽 서버를 업스트림이라고 부릅니다.
오류 로그에 찍힌 대기 단계
504는 게이트웨이나 프록시가 요청을 마치는 데 필요한 응답을 제때 받지 못했다는 뜻입니다. 브라우저 앞에 로드밸런서나 CDN이 있다면, 요청 시각과 경로를 기준으로 어느 계층이 504를 반환했는지부터 맞춰 봅니다. Nginx 접근 로그에 504가 찍혔다면 같은 요청의 오류 로그에서 시간 초과가 난 단계를 확인합니다. RFC 9110 §15.6.5 — 504 Gateway Timeout
예를 들어 upstream timed out … while reading response header from upstream이 남았다면, Nginx는 뒤쪽 서버에서 응답 헤더를 읽는 단계에서 시간 초과를 맞은 겁니다. 오류 문구가 연결 단계에 해당하면 앱 처리 시간에 앞서 대상 주소·포트와 proxy_connect_timeout을 살펴봅니다. 앱이 받은 요청을 언제 처리하기 시작했는지는 그다음에 앱 로그로 확인할 수 있습니다. NGINX 소스 — 업스트림 처리와 시간 기록 · NGINX 공식 문서 — HTTP 프록시 모듈
proxy_read_timeout은 뒤쪽 서버에서 데이터를 연속으로 읽는 두 동작 사이에 허용하는 시간입니다. 응답 헤더를 읽는 동안 데이터가 들어오지 않아 이 한도를 넘을 수 있고, 본문을 받는 도중에도 읽기 간격이 길어지면 같은 제한이 적용됩니다. 설정값은 게시판 검색 경로에 실제 적용된 location을 기준으로 확인합니다. NGINX 공식 문서 — HTTP 프록시 모듈
접근 로그의 시간 네 가지
접근 로그에서 $request_time은 Nginx가 클라이언트 요청의 첫 바이트를 읽은 시점부터 로그를 쓰기까지의 시간입니다. $upstream_connect_time은 앱 서버와 연결하는 데 걸린 시간이고, HTTPS라면 TLS 핸드셰이크도 포함합니다. $upstream_header_time은 해당 업스트림 시도에서 응답 헤더 수신을 마칠 때까지, $upstream_response_time은 그 시도가 끝날 때까지의 경과입니다. 이 값들은 초 단위이며 소수점 아래 세 자리까지 기록됩니다. NGINX 공식 문서 — HTTP 로그 모듈 · NGINX 공식 문서 — 업스트림 변수 · NGINX 소스 — 업스트림 처리와 시간 기록
아래는 검색 요청 한 건에 대한 가상 접근 로그입니다. 읽기 제한이 15초이고, 업스트림 재시도 없이 헤더를 읽는 중 시간 초과가 발생한 경우를 가정했습니다.
method=GET path=/board/search id=demo-032 status=504
request_time=15.009 upstream_connect_time=0.003
upstream_header_time=- upstream_response_time=15.006연결에는 3밀리초가 걸렸고, 약 15초가 지나도록 헤더 수신이 완료되지 않았습니다. 여기서 -는 헤더 시간이 기록되지 않았다는 표시입니다. 실패한 시도에도 upstream_response_time이 남을 수 있으므로 15.006초를 앱의 실행 시간으로 옮겨 적으면 판단이 틀어집니다. 업스트림 값이 여러 개라면 $upstream_addr와 $upstream_status를 함께 보고 시도 순서별로 맞춥니다. NGINX 공식 문서 — HTTP 로그 모듈 · NGINX 공식 문서 — 업스트림 변수 · NGINX 소스 — 업스트림 처리와 시간 기록
요청 ID로 맞춰 보는 앱 처리 시간
이제 Nginx와 앱 로그에서 같은 요청 ID를 찾습니다. 공통 ID가 없다면 재현 환경에서 Nginx의 $request_id를 접근 로그에 기록하고, 같은 값을 요청 헤더로 전달해 앱 로그에도 남기도록 구성합니다. 시간만으로 대조할 때는 두 서버의 시계와 시간대를 맞추고, 검색 요청이 몰린 구간에서는 서로 다른 요청을 짝지을 수 있다는 점을 고려합니다. NGINX 공식 문서 — HTTP 프록시 모듈
앱이 요청을 받은 시점과 핸들러가 실행을 시작한 시점이 모두 있다면 그 차이로 워커 대기를 가늠할 수 있습니다. 실행은 곧바로 시작됐는데 DB 연결을 빌리는 단계에서 시간이 길었다면 커넥션 풀 대기부터, 연결을 얻은 뒤 조회가 길었다면 쿼리 실행 구간부터 살핍니다. 앱 로그가 핸들러 시작부터만 찍힌다면 그 앞 구간의 대기는 별도로 계측해야 합니다.
앞의 가상 요청에서 앱이 접수 직후 실행을 시작했고 DB 연결도 곧바로 얻었지만, 쿼리가 17초 뒤에 끝났다고 가정해 보겠습니다. 이 경우 Nginx가 먼저 대기를 끝냈어도 앱의 DB 작업은 이어진 셈입니다. 앱에서도 쿼리 종료가 확인된 경우에만 이렇게 판단할 수 있습니다.
요약 같은 검색 요청이라도 워커 대기, DB 연결 대기, 쿼리 실행은 손봐야 할 곳이 다릅니다.
결론
검색에서 504가 반복되면 먼저 오류 로그에 찍힌 단계와 접근 로그의 업스트림 시도를 맞춰 보십시오. 연결은 빠르고 헤더를 기다리는 시간이 길다면, 앱에서 접수부터 처리 시작까지와 처리 시작부터 응답 준비까지를 나눠 확인할 차례입니다. 읽기 제한을 조정할지는 이 구간을 측정한 뒤 해당 검색 경로의 응답 목표와 앞단 프록시의 제한을 함께 놓고 판단합니다.