우분투 실전 명령어 | curl로 API 상태 점검하기

Last updated on 

우분투 실전 명령어 | curl로 API 상태 점검하기

서비스 장애가 났을 때 브라우저부터 열기보다 서버에서 curl 한 번으로 응답 코드와 지연 시간을 바로 확인하는 게 훨씬 빠릅니다. 특히 헬스체크 엔드포인트가 있는 API라면 배포 직후 점검, 장애 1차 분류, 외부 연동 확인까지 대부분 이 단계에서 정리됩니다.

언제 쓰는가

  • 배포 직후 API가 정상으로 뜨는지 즉시 확인할 때
  • 5xx 에러가 앱 문제인지 게이트웨이 문제인지 1차 분류할 때
  • 외부 연동 API가 타임아웃인지 인증 실패인지 확인할 때

바로 쓰는 명령어

# 1) 상태 코드만 빠르게 확인
curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/health

# 2) 응답 시간 포함 확인
curl -s -o /dev/null -w "code=%{http_code} total=%{time_total}s\n" \
  https://api.example.com/health

# 3) 헤더까지 같이 확인
curl -i https://api.example.com/health

# 4) Bearer 토큰이 필요한 API 점검
TOKEN="eyJ..."
curl -sS -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://api.example.com/v1/users/me | jq .

# 5) 3초 타임아웃으로 장애 분류
curl -sS --connect-timeout 3 --max-time 3 \
  -o /dev/null -w "code=%{http_code} connect=%{time_connect}s total=%{time_total}s\n" \
  https://api.example.com/health

핵심 옵션/패턴

  • -s: 진행 표시 숨김
  • -S: 에러는 출력 유지 (-sS 조합 많이 사용)
  • -o /dev/null: 본문 버리고 메트릭만 확인
  • -w: 상태 코드/응답 시간 포맷 출력
  • -i: 응답 헤더 포함 출력
  • --connect-timeout: TCP 연결 제한 시간
  • --max-time: 전체 요청 제한 시간

명령 출력 예시

$ curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/health
200

$ curl -s -o /dev/null -w "code=%{http_code} total=%{time_total}s\n" https://api.example.com/health
code=503 total=0.842s

자주 하는 실수

  • -k를 습관적으로 붙여 TLS 인증서를 검증하지 않음
    • 운영 점검에서는 인증서 오류도 중요한 장애 신호라서 기본 검증을 유지하는 게 맞습니다.
  • 상태 코드만 보고 본문 에러 메시지를 놓침
    • 4xx/5xx가 나오면 -i 또는 본문 출력으로 에러 원인을 같이 확인해야 다음 조치가 빨라집니다.
  • 타임아웃 없이 호출해 점검 스크립트가 길게 멈춤
    • 자동 점검은 --connect-timeout, --max-time을 항상 지정하세요.

검증 방법

# 1) 정상/비정상 코드를 분기해 알림용 종료코드 만들기
code=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health)
[ "$code" = "200" ] && echo "OK" || { echo "FAIL code=$code"; exit 1; }

# 2) 지연 시간이 임계치(1초) 넘는지 확인
total=$(curl -s -o /dev/null -w "%{time_total}" https://api.example.com/health)
awk -v t="$total" 'BEGIN { if (t > 1.0) { print "SLOW", t; exit 1 } else { print "FAST", t } }'

# 3) DNS/네트워크 문제 분리를 위한 원격 IP 확인
curl -s -o /dev/null -w "remote_ip=%{remote_ip} code=%{http_code}\n" \
  https://api.example.com/health

운영 팁

  • 헬스체크는 응답 본문을 짧고 고정된 JSON으로 유지하면 점검 자동화가 쉬워집니다.
  • 운영 서버에는 jq를 같이 설치해 JSON 필드 검사까지 붙이면 장애 분류 시간이 확 줄어듭니다.
  • 크론 점검은 단순 성공/실패만 저장하지 말고 응답 시간 추이를 같이 남겨야 성능 저하를 미리 잡을 수 있습니다.

출처

  • curl 공식 문서
  • MDN HTTP 상태 코드 문서
  • Ubuntu Server Guide