05. 실제 502 사례와 장애 보고 상세

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

• 502 Bad Gateway를 보고 cloud provider 장애로 단정하지 않으려면 어떤 증거를 모아야 하는가?
• 클라이언트가 확인할 수 있는 영역과 인프라 운영자가 확인해야 하는 영역은 어디서 갈리는가?
• 좋은 502 장애 보고 문장은 어떤 구조를 가져야 하는가?

개요

502 Bad Gateway는 “gateway가 upstream에서 유효한 응답을 받지 못했다”는 계열의 신호다. 하지만 원인은 backend process down, port/protocol mismatch, backend TLS 실패, health probe 실패, Host header 문제, firewall, proxy rewrite, upstream reset 등 다양하다.

이 문서는 실제 502 사례를 일반화해, 백엔드 개발자가 외부에서 확인할 수 있는 증거를 모으고 인프라 담당자에게 내부 확인 항목을 정확히 요청하는 방법을 정리한다.

왜 백엔드 개발자가 알아야 하는가

502는 사용자에게 크게 보이고, 원인 후보는 넓다. “Azure가 문제 같다”, “NGINX가 문제 같다”, “백엔드가 죽었다”처럼 바로 단정하면 확인 순서가 흐려진다.

• 응답 헤더의 Server는 응답 주체의 단서일 뿐 root cause가 아니다.
• public TLS가 정상이어도 gateway to backend TLS는 실패할 수 있다.
• app log가 없으면 앱 문제가 아니라는 뜻이 아니라 app에 도달하지 않았다는 단서일 수 있다.
• backend가 살아 있어도 health probe path나 Host header가 틀리면 unhealthy가 될 수 있다.
• 배포 직후라면 readiness, target draining, backend port 변경을 함께 봐야 한다.

502 대응은 “외부에서 확인 가능한 사실”과 “내부 권한이 필요한 확인”을 나누는 능력이다.

요청 흐름에서의 위치

502는 주로 gateway/proxy와 upstream 사이에서 발생한다.

Client
→ DNS
→ TCP / TLS
→ Gateway / Load Balancer
→ Backend target / Reverse Proxy / Application

Client에서 gateway까지는 정상인데 gateway가 backend로부터 유효한 응답을 얻지 못하면 502가 나타날 수 있다.

원리

502의 대표 원인은 다음처럼 나눈다.

후보	증상	확인 위치
backend process down	target connection refused, no response	target health, process, port
backend port/protocol mismatch	즉시 502, app log 없음	listener rule, target port/protocol
backend TLS 실패	public TLS 정상, backend TLS 실패	backend cert, SNI, trusted root
Host header mismatch	backend가 잘못된 virtual host로 처리	gateway Host header, app server config
health probe 실패	no healthy target, 502/503	probe path, status, timeout
upstream reset	간헐 502, reset log	proxy error log, stale connection
body/header limit	특정 요청만 502/4xx	proxy/app header/body limit

따라서 502는 “어느 upstream 단계에서 유효한 응답이 깨졌는가”를 찾는 문제다.

클라이언트가 확인할 수 있는 것

클라이언트 또는 백엔드 개발자가 외부에서 확인할 수 있는 범위는 꽤 넓다.

dig +short example.com
nc -vz example.com 443
openssl s_client -connect example.com:443 -servername example.com </dev/null
curl -vI https://example.com
curl -sS -o /dev/null \
  -w "code=%{http_code}\nremote_ip=%{remote_ip}\ndns=%{time_namelookup}\nconnect=%{time_connect}\ntls=%{time_appconnect}\nfirst_byte=%{time_starttransfer}\ntotal=%{time_total}\n" \
  https://example.com/api/health

이 명령으로 알 수 있는 것은 다음이다.

• DNS가 어떤 IP나 CNAME으로 해석되는가?
• 443 TCP 연결은 가능한가?
• public TLS 인증서, SNI, chain은 정상인가?
• 응답 status와 Server, Via, Location, request id는 무엇인가?
• 502가 즉시 반환되는가, 특정 timeout 뒤 반환되는가?
• 특정 path만 실패하는가, 전체 domain이 실패하는가?

클라이언트가 알 수 없는 것

아래 항목은 보통 운영 권한이나 인프라 로그가 필요하다.

• Gateway backend pool health reason
• health probe path, Host header, protocol, backend port
• backend subnet firewall, security group, NSG
• private DNS와 service discovery
• gateway to backend TLS trust 설정
• backend application process와 access/error log
• target draining, readiness, rolling deploy 상태
• WAF rule, listener rule, route rule 변경 이력

좋은 보고는 이 경계를 인정한다. 모르는 영역을 추측으로 채우지 않고 “이 항목 확인이 필요합니다”라고 요청한다.

실제 502 보고 문장

나쁜 보고는 이렇게 끝난다.

채팅이 안 됩니다. Azure 502 같아요.

좋은 보고는 확인한 계층과 내부 확인 항목을 나눈다.

현재 chat.example.com 접속 시 502 Bad Gateway가 반환됩니다.
발생 시각은 2026-06-30 14:05 KST 전후이고, 사내망과 모바일 핫스팟에서 모두 재현됩니다.
DNS는 기대한 CNAME을 거쳐 Gateway IP로 해석됩니다.
443 TCP 연결과 public TLS 인증서 검증은 성공합니다.
curl -vI 결과 Server는 Microsoft-Azure-Application-Gateway/v2입니다.
curl timing상 first_byte가 0.07s로 매우 짧아 Gateway가 즉시 502를 반환하는 것으로 보입니다.
App access log에는 같은 시간대 request id가 아직 확인되지 않았습니다.
Gateway backend health, probe path, backend port/protocol, Host Header, backend TLS, 최근 listener/rule 변경 확인을 부탁드립니다.

이 문장은 원인을 단정하지 않지만, 운영자가 바로 확인할 수 있는 항목을 준다.

확인 순서 예시

순서	확인	의미
DNS	dig +short example.com	기대한 gateway로 가는가
TCP	nc -vz example.com 443	공개 listener까지 도달하는가
TLS	openssl s_client ...	public TLS와 SNI가 정상인가
HTTP	curl -vI	status, 응답 주체, redirect를 본다
API path	health와 실제 API path 비교	route/path 문제인지 전체 문제인지 나눈다
Timing	curl -w	즉시 실패인지 timeout 실패인지 구분한다
Network	사내망, VPN, 모바일, 외부 region	특정 네트워크 문제인지 확인한다
Internal	gateway/LB/proxy/app log	request가 어디까지 갔는지 본다

실무에서 자주 만나는 문제

• Server 헤더만 보고 원인을 확정한다.
  • 응답 주체는 단서지만 root cause는 backend health, route, TLS, app 상태에 있을 수 있다.
  • 내부 로그와 설정을 확인해야 한다.
• DNS/TCP/TLS가 정상이라는 사실로 backend도 정상이라고 본다.
  • Client to gateway 구간만 정상일 수 있다.
  • gateway to backend 구간을 별도로 봐야 한다.
• 스크린샷만 전달한다.
  • 운영자가 시간, URL, request id, header, 재현 범위를 다시 물어야 한다.
  • 장애 보고 템플릿을 사용한다.
• 502와 504를 섞어 처리한다.
  • 즉시 502와 timeout 뒤 504는 확인 순서가 다르다.
  • timing을 반드시 본다.

디버깅 방법

502 분석에서 가장 중요한 분기는 “즉시 실패인가, 기다리다 실패인가”다.

curl -sS -o /dev/null \
  -w "code=%{http_code}\nfirst_byte=%{time_starttransfer}\ntotal=%{time_total}\n" \
  https://example.com/api/health

• first byte가 매우 짧은 502면 target health, route, protocol, TLS, port를 먼저 본다.
• timeout 값 근처에서 실패하면 upstream response 지연, proxy read timeout, app/DB/API 지연을 본다.
• 일부 path만 502면 rewrite, route, upstream service mapping을 본다.
• 특정 method/body만 502면 body size, header size, WAF rule, app parser를 본다.

코드로 확인하기

운영자가 보기 좋은 502 report payload를 구조화하면 재사용하기 쉽다.

{
  "incidentType": "502_BAD_GATEWAY",
  "startedAt": "2026-06-30T14:05:00+09:00",
  "url": "https://chat.example.com/api/v4/system/ping",
  "method": "GET",
  "status": 502,
  "serverHeader": "Microsoft-Azure-Application-Gateway/v2",
  "reproducedFrom": ["office", "mobile-hotspot"],
  "curlTiming": {
    "dns": 0.01,
    "connect": 0.03,
    "tls": 0.05,
    "firstByte": 0.07,
    "total": 0.07
  },
  "needsInfraCheck": [
    "backend health reason",
    "health probe path",
    "backend port/protocol",
    "Host header",
    "backend TLS"
  ]
}

이 구조는 장애 보고, 회고, runbook 업데이트에 그대로 재사용할 수 있다.

주니어가 자주 하는 오해

• 502면 클라우드 제공자 장애라고 생각한다.
  • 대부분은 gateway와 backend 사이의 설정, health, protocol, app 상태 문제다.
• app log가 없으면 앱 팀은 할 일이 없다고 생각한다.
  • backend port, health endpoint, readiness, Host header는 앱 팀과 인프라 팀의 접점이다.
• public TLS가 정상이라면 TLS 문제는 없다고 본다.
  • gateway to backend TLS가 별도로 실패할 수 있다.
• 외부에서 확인한 한 번의 성공으로 장애가 끝났다고 본다.
  • target 일부 장애나 stale connection은 간헐적일 수 있다.

시니어의 설계 판단 기준

• 502 runbook에는 client 확인 명령과 내부 확인 항목을 분리한다.
• health endpoint는 실제 readiness와 backend dependency 상태를 적절히 반영한다.
• 배포 시 readiness, graceful shutdown, target draining, connection draining을 함께 검증한다.
• gateway와 backend 사이의 Host header, protocol, TLS trust를 변경 관리 대상으로 둔다.
• 502 알림은 gateway status와 app error rate를 함께 보여야 한다.

인프라 협업 포인트

• Gateway/LB backend health reason을 요청할 때 target group, listener, rule, time range를 함께 준다.
• backend TLS 문제는 certificate chain, SNI, trusted root, backend hostname을 같이 확인한다.
• app 팀은 health path, expected Host header, backend port, readiness 의미를 명확히 제공해야 한다.
• 인프라 팀은 gateway가 만든 502와 app이 만든 500을 구분할 수 있는 로그 필드를 제공해야 한다.

실전 팁

• 502 보고에는 항상 Server header, request id, curl timing, app log 도달 여부를 넣는다.
• 즉시 502는 routing/health/protocol/TLS 계열을 먼저 보고, timeout성 5xx는 latency/pool/downstream을 먼저 본다.
• 개인 프로젝트에서도 NGINX upstream_status와 upstream_response_time을 남기면 502 분석이 가능해진다.
• 회고에는 “외부에서 알 수 있었던 것”과 “내부 권한이 필요했던 것”을 나누어 남긴다.

위험 신호!

• 502 보고가 “gateway 오류” 한 줄로 끝난다.
• backend health check가 실제 service readiness와 다르다.
• 배포 직후 502가 나는데 connection draining과 readiness 로그를 볼 수 없다.
• Gateway log에는 request가 있는데 app access log에는 없고, 그 이유를 확인할 필드가 없다.
• backend TLS 설정 변경이 앱 팀과 공유되지 않는다.

확인 질문

확인 질문

• 502에서 응답 헤더의 Server가 알려 주는 것은 무엇인가?
  • 응답을 만든 계층의 단서다. root cause를 확정하려면 backend health, protocol, TLS, port, app log를 추가로 확인해야 한다.
• first byte가 매우 짧은 502라면 무엇을 먼저 의심하는가?
  • gateway가 backend로 요청을 넘기기 전후에 즉시 실패했을 가능성이 있어 target health, route, port, protocol, backend TLS를 먼저 본다.
• 좋은 502 보고에는 어떤 내부 확인 요청이 들어가야 하는가?
  • backend health reason, probe path, backend port/protocol, Host header, backend TLS, 최근 listener/rule 변경 확인 요청이 들어가야 한다.

참고 문서

• AWS, Troubleshoot your Application Load Balancers
• AWS, Health checks for target groups
• Azure, Application Gateway backend health
• NGINX, ngx_http_upstream_module variables
• Google SRE Book, Managing Incidents