트러블슈팅 방법론

개발자가 가장 자주 듣는 말 중 하나입니다.

하지만 접속이 안 되는 이유는 수십 가지입니다.

DNS가 안 풀리는 건지, TCP 연결이 안 되는 건지, 연결은 되지만 응답이 안 오는 건지, 응답은 오지만 에러인 건지.

계층별로 체계적으로 진단하는 방법을 알아야 원인을 빠르게 찾을 수 있습니다.

계층별 진단 접근법

범위가 불분명하면 아래 계층부터 위로 좁히는 접근이 유용합니다. 이미 확보한 증거가 있으면 해당 경계부터 시작할 수 있습니다. 아래 흐름의 체크 표시는 조사 순서이지 ping 하나로 하위 계층 전체가 정상임을 증명한다는 뜻은 아닙니다.

[L1 물리] 케이블? Wi-Fi? NIC?
    │ ✓
    ▼
[L2 링크] 인터페이스 활성? ARP?
    │ ✓
    ▼
[L3 네트워크] IP 할당? 게이트웨이 ping? 라우팅?
    │ ✓          도구: ping, traceroute, ip route
    ▼
[L4 전송] 포트 열림? 방화벽? TCP 연결?
    │ ✓      도구: telnet, nc, ss
    ▼
[L7 애플리케이션] HTTP 응답? 상태 코드? 내용?
                  도구: curl, wget

1계층 — 물리적 연결: 케이블이 빠져 있거나, 무선 신호가 약하거나, NIC가 비활성화되어 있지 않은지 확인합니다.

2계층 — 링크: 네트워크 인터페이스가 활성화되어 있는지, ARP 테이블에 게이트웨이의 MAC 주소가 있는지 확인합니다.

arp -a로 확인할 수 있습니다.

3계층 — 네트워크: IP 주소가 올바르게 할당되었는지, 게이트웨이에 핑이 되는지, 목적지까지 라우팅이 가능한지 확인합니다.

4계층 — 전송: 목적지의 특정 포트에 TCP 연결이 되는지 확인합니다.

포트가 열려 있는지, 방화벽이 차단하고 있지 않은지 검사합니다.

7계층 — 애플리케이션: HTTP 요청을 보내고 응답을 확인합니다.

상태 코드, 헤더, 바디를 검사합니다.

HTTPS에서는 TCP 연결 뒤 TLS 협상·서버 인증도 따로 확인합니다. 주소·포트 연결이 성공했어도 인증서 검증에서 멈추면 아직 그 연결로 HTTP 응답을 읽은 것은 아닙니다. 프록시가 있다면 클라이언트→프록시와 프록시→원본의 연결도 구분합니다.

확보한 증거로 실패 경계 고르기 A는 새 직접 HTTPS/TCP 연결에서 DNS 주소를 받고 대상 443 포트 연결도 성공했지만 인증서 검증 오류가 나며 HTTP 응답은 없습니다. B는 프록시가 HTTP 503을 반환했고 해당 요청 ID의 프록시 로그에는 정상 백엔드 대상 0개라고 남았습니다. 두 경우 어느 경계까지 확인했으며, 아직 단정할 수 없는 것은 무엇인가요?

통신이 안 될 때의 체크리스트

#!/bin/bash
# Linux 계열 도구를 사용하는 관측 체크리스트 (대상은 HTTPS 서비스)
TARGET=${1:-"example.com"}
PORT=${2:-443}

echo "=== 1. 외부 ICMP 응답 확인 ==="
ping -c 2 8.8.8.8 && echo "[OK] 해당 대상의 ICMP 응답" || echo "[WARN] ICMP 응답 미확인"

echo ""
echo "=== 2. DNS 확인 ==="
nslookup "$TARGET" && echo "[OK] 조회 명령 성공" || echo "[FAIL] 조회 명령 실패"

echo ""
echo "=== 3. 대상 서버 PING ==="
ping -c 2 "$TARGET" && echo "[OK] PING 응답" || echo "[WARN] 응답 미확인(차단/손실/경로/호스트 상태 확인)"

echo ""
echo "=== 4. 포트 연결 확인 ==="
nc -z -w 3 "$TARGET" "$PORT" && echo "[OK] 포트 $PORT 연결 가능" || echo "[FAIL] 포트 $PORT 연결 실패(닫힘/차단/경로 문제 가능)"

echo ""
echo "=== 5. HTTP 응답 확인 ==="
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://$TARGET:$PORT" 2>/dev/null)
echo "HTTP 상태 코드: $STATUS"

echo ""
echo "=== 6. 경로 추적 ==="
traceroute -m 10 "$TARGET" 2>/dev/null || tracert "$TARGET" 2>/dev/null

이 스크립트는 관측을 모으는 예제이며 자동 원인 판정기가 아닙니다. ICMP 응답 여부는 HTTPS 가용성과 다르고, nslookup 실패도 응답 코드·서버·경로를 추가로 확인해야 합니다. PORT에는 HTTPS 서비스 포트를 넣습니다. curl의 000은 유효한 HTTP 응답 코드가 아니며, 예시는 curl 종료 코드와 오류 출력을 보존하지 않고 전체 시간 제한도 두지 않습니다.

에러별 원인 진단표

네트워크 문제 vs 애플리케이션 문제

장애 상황에서는 먼저 네트워크 문제인지 애플리케이션 문제인지 구분해야 합니다.

다음 절에서는 이 진단 과정에서 사용하는 핵심 도구들의 실제 사용법을 다루겠습니다.