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

Last updated on 

언제 쓰는가

서버는 살아 있는데 API만 이상하다는 제보가 들어올 때 가장 먼저 curl로 확인한다.
브라우저 대신 터미널에서 상태코드, 응답시간, 헤더를 한 번에 확인하면 원인 범위를 빠르게 줄일 수 있다.

바로 쓰는 명령어

# 1) 상태코드와 총 응답시간만 빠르게 확인
curl -sS -o /dev/null -w 'code=%{http_code} time=%{time_total}s\n' https://api.example.com/health

# 2) 헤더까지 확인(리다이렉트 포함)
curl -sS -D - -o /dev/null -L https://api.example.com/login

# 3) JSON API 호출 + 타임아웃 지정
curl -sS --max-time 5 \
  -H 'Accept: application/json' \
  'https://api.example.com/v1/orders?limit=3'

# 4) POST 요청 점검
curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name":"demo","enabled":true}' \
  https://api.example.com/v1/jobs

# 운영에서 자주 쓰는 실패 재현 패턴
curl -sS --connect-timeout 2 --max-time 5 --retry 2 --retry-delay 1 \
  -o /tmp/api.out -w 'code=%{http_code} dns=%{time_namelookup} conn=%{time_connect} start=%{time_starttransfer} total=%{time_total}\n' \
  https://api.example.com/v1/ping

cat /tmp/api.out

핵심 옵션/패턴

  • -sS: 진행바는 숨기고 에러는 보여준다. 자동화 로그가 깔끔해진다.
  • -o /dev/null -w ...: 본문은 버리고 상태코드/지연시간만 뽑아 모니터링에 쓰기 좋다.
  • -D -: 응답 헤더를 표준출력으로 확인한다. 캐시, 쿠키, 리다이렉트 진단에 유용하다.
  • -L: 301/302 리다이렉트를 따라간다. 로그인 경로나 HTTPS 강제 전환 확인에 필요하다.
  • --connect-timeout, --max-time: 연결 지연과 전체 지연을 분리해 제한할 수 있다.
  • --retry: 일시적 네트워크 흔들림에서 재시도한다. 단, POST 같은 비멱등 요청은 신중히 사용한다.

명령 출력 예시

$ curl -sS -o /dev/null -w 'code=%{http_code} time=%{time_total}s\n' https://api.example.com/health
code=200 time=0.083s

$ curl -sS --connect-timeout 2 --max-time 5 -o /dev/null -w 'code=%{http_code} dns=%{time_namelookup} conn=%{time_connect} start=%{time_starttransfer} total=%{time_total}\n' https://api.example.com/v1/ping
code=502 dns=0.003 conn=0.019 start=1.244 total=1.247

위 예시처럼 conn은 빠른데 start가 느리면 네트워크보다 애플리케이션 처리 지연을 먼저 의심하는 식으로 본다.

자주 하는 실수

  • -I만 보고 정상이라고 판단하는 실수
    • -I는 보통 HEAD 요청이라 실제 GET/POST 경로 문제를 놓칠 수 있다.
  • 인증 헤더 없이 호출해서 401을 장애로 오해하는 실수
    • 운영 점검 명령에는 필요한 토큰 헤더를 항상 포함해야 한다.
  • -k를 습관적으로 쓰는 실수
    • TLS 검증을 꺼서 인증서 문제를 가린다. 디버깅 외에는 피하는 게 맞다.
  • 타임아웃 없이 실행하는 실수
    • 장애 상황에서 커맨드가 오래 걸려 배치 파이프라인 전체를 막을 수 있다.

검증 방법

# 1) 상태코드 확인
curl -sS -o /dev/null -w '%{http_code}\n' https://api.example.com/health

# 2) 지연시간 분해 확인
curl -sS -o /dev/null -w 'dns=%{time_namelookup} conn=%{time_connect} start=%{time_starttransfer} total=%{time_total}\n' https://api.example.com/v1/ping

# 3) 동일 요청을 5회 반복해 편차 확인
for i in {1..5}; do
  curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' https://api.example.com/health
  sleep 1
done

반복 결과에서 상태코드가 흔들리거나 응답시간 편차가 크면 로드밸런서 뒤 인스턴스 편차, 백엔드 의존성 지연을 추가로 확인한다.

운영 팁

장애 대응 때는 팀 공용 점검 명령을 문서화해 두면 사람마다 다른 옵션으로 측정해 생기는 혼선을 줄일 수 있다.
최소한 상태코드, 총시간, 요청 URL, 실행 시각을 같은 형식으로 남기면 회고와 재현이 쉬워진다.

출처

  • curl 공식 문서
  • Ubuntu Manpages
  • MDN Web Docs