コンテンツにスキップ

基本的な使い方

コマンドラインインターフェース

httptap のコマンドラインインターフェースは、HTTP リクエストと出力をカスタマイズするためのさまざまなオプションを提供します。

構文

httptap [OPTIONS] URL

オプション

curl 互換性: 一般的な curl のフラグはエイリアスとして受け付けられます。curl を httptap に置き換えて、-X/--request、-L/--location、-m/--max-time、-k/--insecure、-x、--http1.1 のような馴染みのあるオプションをそのまま使い続けられます。-f/--fail、-4/--ipv4、-6/--ipv6、--resolve も curl と同じ名前です。これは完全な curl のクローンではありません。ここに挙げた重複するフラグにとどめてください。

リクエストオプション

-X, --request, --method METHOD

使用する HTTP メソッドを指定します。サポートされるメソッド: GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。

メソッドの値は大文字・小文字を区別しません。

curl 互換エイリアス: -X、--request。

httptap --method POST https://httpbin.io/post

デフォルトの挙動: - --data なし: GET がデフォルトになります - --data はあるが --method がない場合: 自動的に POST に切り替わります（curl と同様） - --method を明示した場合: 指定したメソッドを尊重します

-d, --data DATA

リクエストボディのデータを送信します。インライン文字列でも、@filename 構文を使ったファイル参照でも指定できます。

インライン JSON データ: 

httptap --data '{"name": "John", "email": "john@example.com"}' https://httpbin.io/post

ファイルから読み込む: 

httptap --data @payload.json https://httpbin.io/post

インラインデータは curl と同様に、引数のバイト列そのままで送信されます。POSIX システムでは、有効な UTF-8 ではない引数もそのまま送信されます。

自動検出: - Content-Type は自動的に検出されます（JSON、XML、プレーンテキスト） - 最初にファイル拡張子がチェックされます（.json、.xml、.txt） - 検出できない場合は JSON 検証にフォールバックします

さまざまなメソッドの例: 

# POST (--data がある場合に自動検出される)
httptap --data '{"key": "value"}' https://httpbin.io/post

# PUT
httptap --method PUT --data '{"status": "updated"}' https://httpbin.io/put

# PATCH
httptap --method PATCH --data '{"field": "modified"}' https://httpbin.io/patch

# ボディ付きの明示的な GET (まれ、警告を発生させる)
httptap --method GET --data 'query-data' https://httpbin.io/get

-H, --header

リクエストにカスタム HTTP ヘッダーを追加します。複数回使用できます。

httptap -H "Accept: application/json" https://httpbin.io

httptap \
  -H "User-Agent: MyApp/1.0" \
  -H "Authorization: Bearer token123" \
  https://httpbin.io/bearer

ヘッダー名は HTTP トークン（英字、数字、および !#$%&'*+-.^_`|~）でなければならず、値に使用できるのは印字可能な ASCII 文字、スペース、タブのみです。名前にスペースを含む、値に CR、LF その他の制御文字を含む、値に非 ASCII 文字を含む（httpx はヘッダー値を ASCII として送信します）など、これらの規則に違反するヘッダーは、リクエストを送信する前に終了コード 64 で拒否されます。エラーにはヘッダー名が示されますが、値は表示されません。

-L, --location, --follow

HTTP リダイレクトを追跡し、チェーン内の各ステップのタイミングを表示します（リダイレクトは最大 10 回）。

curl 互換エイリアス: -L、--location。

httptap --follow https://httpbin.io/redirect/3

デフォルトでは、httptap はリダイレクトを追跡せず、最初のリダイレクトレスポンス（3xx ステータスコード）で停止します。

10 回リダイレクトを追跡した後もレスポンスがまだリダイレクトである場合、httptap は停止して警告を表示し、JSON エクスポートでそのステップに redirect_limit_reached: true を付け、終了コード 47 で終了します。

リダイレクトを追跡する際、httptap は curl やブラウザと同じルールを適用します:

  • Authorization、Cookie、Proxy-Authorization ヘッダーは元のオリジン（スキーム、ホスト、ポート）にのみ送信されます。リダイレクト先が別のオリジンになると、それ以降のチェーンではこれらのヘッダーは送信されません。同じホストでデフォルトポートのまま http → https にアップグレードする場合（80 → 443）は保持されます。
  • 303 See Other、および POST 後の 301/302 では、次のリクエストはボディなしの GET に切り替わります。307 と 308 はメソッドとボディを保持します。

リダイレクトの Location がリクエストできない URL（無効または範囲外のポート、ホストの欠落、http/https 以外のスキーム、不正な IPv6 リテラル）の場合、3xx ステップはそのまま残り、チェーンはそのターゲットに対する失敗ステップ（エラー Invalid redirect target: …）で終わり、httptap は終了コード 75 で終了します。--follow を指定しない場合、3xx レスポンスは Location の内容にかかわらず受信したとおりに表示されます。

Location URL に含まれる認証情報（https://user:password@host/）は出力と JSON エクスポートではマスクされます（https://user:****@host/）が、リダイレクトは実際の URL に対して行われます。

-m, --max-time, --timeout SECONDS

経過時間の合計が指定した秒数を超えた場合、リクエストチェーンを中止します。

この制限は、リダイレクトを含むチェーン全体に対する厳密な期限です。名前解決、接続、レスポンスの待機、ボディの読み取りはすべてこの期限を共有し、応答が止まったサーバーや少しずつバイトを送り続けるサーバーも期限の時点で打ち切られます。その場合、ステップは Request timeout: total deadline exceeded で失敗し、httptap は終了コード 75 で終了します。

curl 互換エイリアス: -m、--max-time。

httptap --timeout 10 https://httpbin.io/delay/2

デフォルトのタイムアウトは 20 秒です。

--no-http2 / --http1.1

HTTP/2 のネゴシエーションを無効にし、HTTP/1.1 接続を強制します。

httptap --no-http2 https://httpbin.io

デフォルトでは、サーバーが対応していれば HTTP/2 が有効になります。

curl 互換エイリアス: --http1.1。

-4, --ipv4 と -6, --ipv6

名前解決と接続を IPv4 または IPv6 に制限します。これらのオプションは相互排他です。

httptap -4 https://example.com
httptap --ipv6 https://example.com

HTTP、HTTPS、SOCKS5H プロキシはターゲットのホスト名を自身で名前解決するため、これらのプロキシとは併用できません。

--resolve HOST:PORT:ADDR

元の Host ヘッダーと TLS SNI を維持したまま、ホスト名とポートを特定の IPv4 または IPv6 アドレスに接続します。DNS 切り替え前に特定のバックエンドをテストする場合や、ラウンドロビン DNS レコードをバイパスする場合に便利です。異なるホストとポートの組み合わせに対して、このオプションを複数回指定できます。

httptap --resolve api.example.com:443:203.0.113.10 https://api.example.com/health
httptap --resolve api.example.com:443:[2001:db8::10] https://api.example.com/health

国際化ホスト名はどちらの形式でも一致します。bücher.example のエントリは https://xn--bcher-kva.example/ にも適用され、その逆も同様です。httptap はこのような名前を IDNA 2008 形式（xn--…）で名前解決します。これは Host ヘッダーと TLS SNI で送信される名前と同じです。

--resolve は直接接続とローカル DNS の SOCKS5 プロキシに適用されます。HTTP、HTTPS、SOCKS5H プロキシはターゲットをリモートで名前解決するため、-4/-6 と同様に、これらと --resolve の組み合わせは拒否されます。

-k, --insecure, --ignore-ssl

TLS 証明書の検証を無効にします。自己署名ホストや期限切れの証明書のデバッグに便利です。

httptap --ignore-ssl https://self-signed.badssl.com

Warning

このオプションは信頼できるネットワークでのみ使用してください。証明書の検証を無効にし、ハンドシェイクの制約を緩和します。

curl 互換エイリアス: -k、--insecure。

-x, --proxy URL

指定したプロキシ経由でリクエストをルーティングします。HTTP、HTTPS、SOCKS5、SOCKS5H の各プロトコルに対応しています。

curl 互換エイリアス: -x。

# HTTP プロキシ
httptap --proxy http://proxy.local:8080 https://httpbin.io/get

# SOCKS5 プロキシ (DNS はプロキシで解決)
httptap --proxy socks5h://proxy.local:1080 https://httpbin.io/get

# SOCKS5 プロキシ (DNS はローカルで解決)
httptap --proxy socks5://proxy.local:1080 https://httpbin.io/get

# プロキシの環境変数を無視して直接接続する
httptap --proxy "" https://httpbin.io/get

--proxy フラグは環境変数（HTTP_PROXY、HTTPS_PROXY、NO_PROXY）よりも優先されます。すべてのプロキシ環境変数を無視して直接接続するには --proxy "" を使用してください。プロキシプロトコル、名前解決、環境変数の設定の詳細については 高度な機能 を参照してください。

プロキシ URL に含まれる認証情報（http://user:password@proxy:3128、環境変数から取得したものを含む）は接続に使用されますが、出力と JSON エクスポートではマスクされます（http://user:****@proxy:3128）。

スキームなしで指定したプロキシ（proxy.local:3128）は、curl と同様に http:// として扱われます。不正なプロキシ URL（サポートされていないスキーム、ホストの欠落、無効または範囲外のポート、閉じられていない IPv6 リテラル）は、リクエストを送信する前に終了コード 64 で拒否されます。エラーにはパスワードをマスクした URL が表示されます。

--cacert, --ca-bundle PATH

TLS 検証にカスタム CA 証明書バンドル（PEM 形式）を使用します。プライベート CA によって署名された内部エンドポイントに便利です。

httptap --cacert ~/certs/company-ca.pem https://internal-api.example.com/health

--ignore-ssl とは相互排他です。

出力オプション

--compact

結果をコンパクトな 1 行形式で表示します。ロギングに適しています。

httptap --compact https://httpbin.io/get

出力:

Step 1: 200 GET https://httpbin.io/get | dns=8.9ms connect=97.0ms tls=194.6ms ttfb=446.0ms total=447.3ms | 389 B

--compact はステップごとに人間が読みやすい 1 行を出力し（ログやリダイレクトチェーンのトレースに適しています）、分析ヘッダーと Redirect Chain Summary テーブルも引き続きレンダリングします。レスポンスサイズは適切な単位（B、KB、MB）で表示されます。機械で解析可能な出力については --metrics-only を参照してください。

--metrics-only

書式なしの生のメトリクスを出力します。スクリプトや自動化に最適です。

httptap --metrics-only https://httpbin.io

出力:

Step 1: dns=30.1 connect=97.3 tls=199.0 ttfb=472.2 total=476.0 status=200 bytes=389 ip=44.211.11.205 family=IPv4 tls_version=TLSv1.2 proxy=direct

--json PATH

完全なリクエストデータを JSON ファイルにエクスポートします。代わりに JSON を標準出力に書き出すには - を使用します。その場合、出力をパイプできるように通常のレポートは抑制されます。

httptap --json report.json https://httpbin.io
httptap --json - https://httpbin.io | jq '.summary'

ファイルを書き込めない場合、httptap は終了コード 73 で終了します。

JSON ファイルには以下が含まれます:

  • 全フェーズのタイミングの内訳
  • ネットワーク情報（IP アドレス、TLS の詳細、証明書情報）
  • レスポンスのメタデータ（ステータス、ヘッダー、ボディサイズ）
  • 完全なリダイレクトチェーン（--follow を使用した場合）
  • SLO 評価（--slo を指定した場合）

--har PATH

リクエストチェーンを、ブラウザーの DevTools や HAR ビューアーで開ける HTTP Archive（HAR 1.2）ファイルとしてエクスポートします。標準出力に書き出すには - を使用します。その場合、通常のレポートは抑制されます。--har は --json と併用できますが、- を使えるのはどちらか一方だけです。

httptap --follow --har run.har https://httpbin.io/redirect/2
httptap --har - https://httpbin.io/get | jq '.log.entries[].timings'

ファイルを書き込めない場合、httptap は終了コード 73 で終了します。タイミングの対応関係と httptap が追加するフィールドについては、HAR エクスポートを参照してください。

--prometheus PATH

フェーズごとのタイミングを Prometheus の textfile collector 形式で書き出します。所要時間は host、step、phase ラベル付きの httptap_request_duration_seconds ゲージとしてエクスポートされ、httptap_request_success と httptap_last_run_timestamp_seconds も併せて出力されます。パスやクエリ文字列がラベルになることはありません。

httptap --prometheus /var/lib/node_exporter/httptap.prom https://httpbin.io/get

--otlp ENDPOINT

実行全体を 1 つの OpenTelemetry トレースとしてエクスポートします。トレースはルートスパン、リクエストステップごとに 1 つのスパン、そして DNS、接続、TLS、サーバー待機、転送の各フェーズの子スパンで構成されます。事前にオプションの依存関係をインストールしてください:

pip install 'httptap[otel]'
httptap --otlp http://localhost:4318/v1/traces https://httpbin.io/get

--slo KEY=MS[,KEY=MS...]、--slo-file PATH

最終的に成功したステップを、フェーズごとのレイテンシ予算と照合してチェックします。違反があった場合でも httptap は完全なレポートをレンダリングしますが、終了コード 4 で終了するため、その結果を CI ジョブ、cron プローブ、Kubernetes の readiness チェックのゲートに使用できます。

httptap --slo total=500,ttfb=200 https://httpbin.io/get

# 1 行に 1 つのしきい値。インラインの値はファイルの値を上書きします。
httptap --slo-file slo.txt --slo total=1000 https://httpbin.io/get

サポートされるキー: dns、connect、tls、ttfb、wait、xfer、total。完全な仕様、終了コードの優先順位、CI/cron のレシピについては、専用の SLO しきい値チェック ページを参照してください。

-f、--fail

完了したいずれかのリクエストが HTTP 4xx または 5xx を返した場合に終了コード 22 で終了します。その場合でも完全なタイミングレポートはレンダリングされ、--json の出力も書き込まれます。ネットワークおよび TLS の障害は、より優先度の高い既存の終了コードのままです。

httptap --fail https://httpbin.io/status/500

--version

httptap のバージョンを表示して終了します。

httptap --version

HTTP メソッド

httptap はすべての標準 HTTP メソッドをサポートしています:

  • GET - リソースの取得（--data が指定されない場合のデフォルト）
  • POST - リソースの作成／送信（--data が指定された場合に自動選択）
  • PUT - リソースの置換
  • PATCH - リソースの部分更新
  • DELETE - リソースの削除
  • HEAD - ヘッダーのみの取得
  • OPTIONS - 許可されたメソッドの照会

メソッド選択のロジック

  1. 明示的なメソッド: --method は常に優先されます
  2. 自動 POST: --method なしで --data がある場合、POST がデフォルトになります
  3. デフォルト GET: --data も --method もない場合、GET を使用します

ユースケース別の例

API テスト: 

# リソースの作成
httptap --data '{"title": "New Post"}' https://httpbin.io/post

# リソースの更新
httptap --method PUT --data '{"title": "Updated"}' https://httpbin.io/put

# 部分更新
httptap --method PATCH --data '{"status": "published"}' https://httpbin.io/patch

# リソースの削除
httptap --method DELETE https://httpbin.io/delete

ヘルスチェック: 

# クイックチェック (ヘッダーのみ)
httptap --method HEAD https://httpbin.io/status/200

# 完全なレスポンス
httptap https://httpbin.io/status/200

リクエストフロー

すべての httptap リクエストは次のフェーズをたどります:

  1. 名前解決 - ドメイン名のルックアップ
  2. TCP 接続 - TCP 接続の確立（HTTP CONNECT プロキシ経由の場合: プロキシへの接続とトンネルの確立）
  3. TLS ハンドシェイク - セキュアな接続のネゴシエーション（HTTPS のみ）
  4. サーバー待機 - リクエスト送信から最初のレスポンスバイトまでの時間
  5. ボディ転送 - レスポンスボディのダウンロード

出力の理解

リッチモード（デフォルト）

デフォルトのリッチな出力は、次の内容を含むウォーターフォールテーブルを表示します:

  • フェーズ名と所要時間
  • 視覚的なプログレスバー
  • ネットワークの詳細（IP、TLS バージョン、証明書情報）
  • レスポンスのメタデータ（ステータス、サイズ、Server ヘッダー、リダイレクト先）

タイミングの内訳

  • DNS (ms) - ドメインを IP アドレスに解決するまでの時間
  • Connect (ms) - TCP 接続を確立するまでの時間。HTTP CONNECT プロキシ経由の場合は CONNECT のラウンドトリップも含まれるため、トンネルの確立はサーバー待機としてカウントされません。ホストに複数のアドレスがあり、最初のアドレスへの接続が失敗した場合、それに費やした時間もここと Total に含まれます（curl の time_connect と同様）
  • TLS (ms) - TLS ハンドシェイクにかかる時間（HTTPS のみ）
  • TTFB (ms) - 最初のバイトまでの時間（サーバー処理を含む）
  • Transfer (ms) - レスポンスボディをダウンロードするまでの時間
  • Total (ms) - エンドツーエンドのリクエスト所要時間

ネットワーク情報

  • IP Address - 解決された IP アドレスとファミリ（IPv4/IPv6）
  • TLS Version - プロトコルバージョン（TLS 1.2、TLS 1.3）
  • Cipher Suite - ネゴシエートされた暗号スイート
  • Certificate CN - サーバー証明書の Common Name
  • Certificate Expiry - 証明書が期限切れになるまでの日数

例

基本的なヘルスチェック

httptap https://httpbin.io/status/200

認証付きの API リクエスト

httptap \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Accept: application/json" \
  https://httpbin.io/bearer

リダイレクトチェーンを追跡する

httptap --follow https://httpbin.io/redirect/3

分析用にエクスポートする

httptap --json analysis.json --follow https://httpbin.io/redirect/2

ファイルにログを出力する

httptap --metrics-only https://httpbin.io/delay/1 >> api-latency.log

次のステップ