Go の標準ライブラリ

net/http/httptrace

で HTTP リクエストの詳細をトレースする

2026 年 5 月 26 日公開

Go 1.7 に導入された標準ライブラリ

net/http/httptrace

httptrace

が公開するフックポイント

このパッケージは、以下のようなネットワーク上の重要な瞬間におけるフックを提供します。

• DNS の名前解決 (

  DNSStart

  ,

  DNSDone

  )
• コネクションの取得 (

  ConnectStart

  ,

  ConnectDone

  )
• TLS ハンドシェイク (

  TLSHandshakeStart

  ,

  TLSHandshakeDone

  )
• ネットワーク上の転送開始 (

  GetConn

  )
• 最初の応答バイト受信 (

  GotFirstResponseByte

  )

これらは、従来のログやメトリクスだけでは捉えることが困難な「搬送層の外」とからの観測を可能にします。

設計思想：なぜ

context

を使っているのか？

インターフェースではなく

*ClientTrace

コンテキストを採用した理由

直感的な設計（

Tracer

• ミドルウェアとの互換性: 追跡情報は

  context.Context

  に格納されるため、コンテキストを中継するあらゆるミドルウェアで自動的に動作します。追加のコストなしで実装が広がります。
• 無状態設計: 共有可変状態が存在しないため、同じ

  http.Client

  で複数のリクエストを送信しても、それぞれ異なる追跡情報を安全に管理できます。
• ゼロコストのオプション: リクエストに追跡を付与しないとトランスポートは無視するため、「未使用時のオーバーヘッド」はほぼありません。

追跡対象とするのは任意のフィールド（関数）のみで構いません。設定されていないフィールドは

nil

// クライアント作成サンプル
trace := &httptrace.ClientTrace{
    DNSStart: func(info httptrace.DNSStartInfo) {
        fmt.Printf("DNS start: %s\n", info.Host)
    },
    GotFirstResponseByte: func() {
        fmt.Println("First byte received")
    },
}

ctx := httptrace.WithClientTrace(context.Background(), trace)
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.com", nil)

実装例：

curl --trace

に似た CLI ツール

URL を受け取り、各フックのタイミングを計測して出力するシンプルな CLI ツールを作成できます。これにより、DNS ルックアップや TLS ハンドシェイクなど、どこに時間がかかるかが一目でわかります。

タイミング計測構造体

type timings struct {
    start         time.Time
    dnsStart      time.Time
    dnsDone       time.Time
    connectStart  time.Time
    connectDone   time.Time
    tlsStart      time.Time
    tlsDone       time.Time
    gotConn       time.Time
    firstByte     time.Time
    done          time.Time
}

func (t *timings) elapsed(at time.Time) time.Duration {
    return at.Sub(t.start)
}

クライアントトレース作成

func newTrace(t *timings) *httptrace.ClientTrace {
    return &httptrace.ClientTrace{
        DNSStart: func(_ httptrace.DNSStartInfo) {
            t.dnsStart = time.Now()
        },
        DNSDone: func(_ httptrace.DNSDoneInfo) {
            t.dnsDone = time.Now()
        },
        ConnectStart: func(_, _ string) {
            t.connectStart = time.Now()
        },
        ConnectDone: func(_, _ string, _ error) {
            t.connectDone = time.Now()
        },
        TLSHandshakeStart: func() {
            t.tlsStart = time.Now()
        },
        TLSHandshakeDone: func(_ tls.ConnectionState, _ error) {
            t.tlsDone = time.Now()
        },
        GotConn: func(_ httptrace.GotConnInfo) {
            t.gotConn = time.Now()
        },
        GotFirstResponseByte: func() {
            t.firstByte = time.Now()
        },
    }
}

メイン処理と出力

func main() {
    url := os.Args[1]
    t := &timings{start: time.Now()}
    trace := newTrace(t)

    ctx := httptrace.WithClientTrace(context.Background(), trace)
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    res.Body.Close()
    t.done = time.Now()

    // 分解表示出力
    fmt.Printf("DNS lookup:       %v\n", t.dnsDone.Sub(t.dnsStart))
    fmt.Printf("TCP connect:      %v\n", t.connectDone.Sub(t.connectStart))
    fmt.Printf("TLS handshake:    %v\n", t.tlsDone.Sub(t.tlsStart))
    fmt.Printf("Server processing: %v\n", t.firstByte.Sub(t.gotConn))
    fmt.Printf("Content transfer: %v\n", t.done.Sub(t.firstByte))
    fmt.Printf("Total:            %v\n", t.done.Sub(t.start))
}

特徴: 依存グラフ内の計測ライブラリも不要で、プロキシや APM エージェントなしでも動作します。

注意点:

• DNSStart

  /

  DNSDone

  : ドメインが既にキャッシュされている場合はフックが発火しないことがあります。

• TLSHandshake

  : HTTPS の場合のみ発火します。

• GotConn

  : コネクションの再利用の有無は

  info.Reused

  フラグで確認可能。

実装例：すべてのリクエストを追跡する

RoundTripper

特定のクライアントを通じて自動追跡を行いたい場合は、

http.RoundTripper

トレース付きトランスポートの定義

type TracingTransport struct {
    Base http.RoundTripper
    Log  func(req *http.Request, t *timings)
}

func (tt *TracingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    base := tt.Base
    if base == nil {
        base = http.DefaultTransport
    }

    t := &timings{start: time.Now()}
    trace := newTrace(t)
    
    // コンテキストに追跡情報を追加（既存があれば上書きされます）
    req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))

    res, err := base.RoundTrip(req)
    t.done = time.Now()

    if tt.Log != nil {
        tt.Log(req, t)
    }

    return res, err
}

使用例

client := &http.Client{
    Transport: &TracingTransport{
        Log: func(req *http.Request, t *timings) {
            log.Printf("%s %s dns=%v tls=%v ttfb=%v total=%v",
                req.Method, req.URL,
                t.dnsDone.Sub(t.dnsStart),
                t.tlsDone.Sub(t.tlsStart),
                t.firstByte.Sub(t.gotConn),
                t.done.Sub(t.start),
            )
        },
    },
}

client.Get("https://example.com")

コンポジションの注意点: 呼び出し元がすでに

ClientTrace

を設定した場合、単純な置換ではなく統合されます。最後の追跡情報が優先されますが、両方のフックが発火する可能性があります。

ボディ転送時間の正確な計測

重要なのは、

t.done

RoundTrip

type timedBody struct {
    io.ReadCloser
    onClose func()
}

func (tb *timedBody) Close() error {
    tb.onClose()
    return tb.ReadCloser.Close()
}

// RoundTrip 内での使用例：
res.Body = &timedBody{
    ReadCloser: res.Body,
    onClose:    func() { t.done = time.Now() },
}

コネクションの再利用（プール）の確認

httptrace

GotConnInfo

• Reused bool

  : コネクションが再利用されたかどうか

• WasIdle bool

  : 無負荷状態にあったか

• IdleTime time.Duration

  : 無負荷時間の長さ（再利用時のみ）

GotConn: func(info httptrace.GotConnInfo) {
    t.gotConn = time.Now()
    if info.Reused {
        log.Printf("connection reused (idle for %v)", info.IdleTime)
    } else {
        log.Printf("new connection to %s", info.Conn.RemoteAddr())
    },
},

トラブルシューティング:

• 同一ホストへの反復呼び出しで常に

  Reused: false

  が出る場合、コードが意図せずコネクションプールを妨げている可能性があります（例：リクエストごとのクライアント作成、未クローズのボディなど）。

まとめ

net/http/httptrace

• 低いオーバーヘッド: 無効化可能なオプション設計であり、利用しない場合のコストはほぼゼロです。
• コンテキストベースの設計:

  context.Context

  を介して動作するため、標準ライブラリの他のコンポーネントやミドルウェアとシームレスに連携します。
• 手軽なデバッグツール: 外部エージェントを使わず、単一ファイルで HTTP 呼び出しのボトルネックを特定できます。

詳細な追跡情報が必要な場合、Limeleaf のような Web サイトや API 監視ツールを検討することをお勧めします。