curlのVerboseモードとデバッグ

curlでHTTPリクエストをデバッグする

curlはHTTPの問題をデバッグするための最良のツールのひとつです。verboseモードとtraceモードにより、DNS解決からTLSネゴシエーションまで、リクエスト・レスポンスライフサイクルのあらゆる詳細を確認できます。

Verboseモード

-v フラグでリクエストとレスポンスの全体の通信を表示します:

curl -v https://api.example.com/data

出力のプレフィックス:

• * — curlの情報メッセージ（DNS、TLS、接続）
• > — サーバーに送信されたリクエストヘッダー
• < — サーバーから受信したレスポンスヘッダー

Traceモード

さらに詳細な情報が必要な場合、--trace ですべてのデータの16進ダンプを出力します:

curl --trace trace.log https://api.example.com/data

または --trace-ascii で読みやすいASCIIダンプを出力します:

curl --trace-ascii - https://api.example.com/data

タイミング情報

-w（write-out）でタイミングメトリクスを表示します:

curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nFirst byte: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  https://api.example.com/data

レスポンスコードのみ

HTTPステータスコードだけを確認します:

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

TLS詳細の調査

curl -v --tlsv1.2 https://example.com 2>&1 | grep "SSL\|TLS\|certificate"

エラー付きサイレントモード

-sS でプログレス出力を抑制しつつ、エラーは表示します:

curl -sS https://api.example.com/data

デバッグチェックリスト

APIリクエストが失敗した場合、以下の体系的なアプローチを使います:

1. 接続性の確認: curl -v でDNSとTCP接続を検証する
2. ヘッダーの調査: Content-Type、Authorization、その他の必須ヘッダーを確認する
3. TLSの確認: 証明書エラーやバージョンの不一致を確認する
4. タイミングの検査: -w でレイテンシの発生箇所を特定する
5. 動作するリクエストとの比較: 成功するリクエストと失敗するリクエストのverbose出力を比較する

Write-Out変数

主な -w 変数: %{http_code}、%{content_type}、%{size_download}、%{speed_download}、%{url_effective}、%{num_redirects}、%{ssl_verify_result}。