Go httptrace.ConnectStart 怎样记录每次 TCP 连接尝试

如果你想知道 Go HTTP 客户端到底尝试连接了哪个地址，应该观察 httptrace.ClientTrace.ConnectStart，而不是只记录最终的请求错误。ConnectStart 在一次新连接的 Dial 开始时调用，回调参数里的 network 和 addr 就是这次尝试的连接类型与目标地址；再用 ConnectDone 补上结束时间和错误，就能保留每一次 TCP 连接尝试。

官方地址：https://pkg.go.dev/net/http/httptrace

先分清 ConnectStart、ConnectDone 与 GotConn

这三个观测点处在不同边界。ConnectStart 表示新连接的 Dial 开始；ConnectDone 表示这次 Dial 完成，并通过 err 报告成功或失败；GotConn 表示 Transport 已经拿到可用连接。连接可能来自空闲池，此时不一定会发生新的 Dial，因此不能用 GotConn 代替 ConnectStart。

还要注意回调的调用范围：只有真正开始建立新连接时才会触发 ConnectStart。如果请求复用了已有连接，重点应该转向 GotConnInfo；如果连接建立失败，GotConn 不会替你提供失败回调，最终错误仍由 RoundTrip 或 Client.Do 返回。

把 ClientTrace 绑定到请求上下文

最小实现是为每个请求建立一份 ClientTrace，在 ConnectStart 中保存开始时间，在 ConnectDone 中计算耗时。下面的示例按顺序记录每次尝试，不会覆盖前一次地址；回调可能由不同 goroutine 调用，所以共享切片需要加锁。

package main

import (
    "context"
    "fmt"
    "net/http"
    "net/http/httptrace"
    "sync"
    "time"
)

type dialAttempt struct {
    Network string
    Addr    string
    Started time.Time
    Ended   time.Time
    Err     error
}

func requestWithDialTrace(ctx context.Context, client *http.Client, url string) error {
    var mu sync.Mutex
    attempts := make([]dialAttempt, 0, 2)

    trace := &httptrace.ClientTrace{
        ConnectStart: func(network, addr string) {
            // 每次开始 Dial 都追加一条，不能把 IPv6 和 IPv4 尝试合并。
            mu.Lock()
            attempts = append(attempts, dialAttempt{
                Network: network,
                Addr:    addr,
                Started: time.Now(),
            })
            mu.Unlock()
        },
        ConnectDone: func(network, addr string, err error) {
            // 反向查找同一 network/addr 的未完成记录，补齐结束时间和错误。
            mu.Lock()
            defer mu.Unlock()
            for i := len(attempts) - 1; i >= 0; i-- {
                if attempts[i].Network == network && attempts[i].Addr == addr && attempts[i].Ended.IsZero() {
                    attempts[i].Ended = time.Now()
                    attempts[i].Err = err
                    break
                }
            }
        },
    }

    req, err := http.NewRequestWithContext(
        httptrace.WithClientTrace(ctx, trace),
        http.MethodGet,
        url,
        nil,
    )
    if err != nil {
        // URL 或请求参数无效时，不要把它误判成 TCP 拨号失败。
        return err
    }

    resp, err := client.Do(req)
    if err != nil {
        // 没有可用连接时，以 Do 返回的错误作为请求级结论。
        return err
    }
    defer resp.Body.Close()

    mu.Lock()
    defer mu.Unlock()
    for _, attempt := range attempts {
        duration := time.Duration(0)
        if !attempt.Ended.IsZero() {
            duration = attempt.Ended.Sub(attempt.Started)
        }
        fmt.Printf("dial network=%s addr=%s duration=%s err=%v\\n", attempt.Network, attempt.Addr, duration, attempt.Err)
    }
    return nil
}

示例中没有读取、关闭或改写 GotConnInfo.Conn。连接归 http.Transport 管理，追踪回调只读取状态即可。生产代码还可以把 fmt.Printf 换成结构化日志，并给每条尝试附上请求 ID。

把每次尝试和最终结果配对

ConnectStart 与 ConnectDone 是一对“拨号级”事件，但它们不等于一次完整 HTTP 请求。拨号成功后，TLS 握手、写请求、读取响应仍可能失败；因此排查时需要同时保留拨号记录和 client.Do 的请求级错误。

DualStack 下为什么会出现多次 ConnectStart

当网络栈启用了 net.Dialer 的 DualStack，也就是常说的 Happy Eyeballs 行为时，客户端可能先尝试 IPv6，随后再尝试 IPv4。官方文档明确提示，ConnectStart 和 ConnectDone 可能被调用多次；这不是重复发送了 HTTP 请求，而是同一次连接获取过程中的多个地址竞争。

因此不要用一个全局布尔值表示“是否连接过”，也不要只按 host 覆盖日志。推荐把下面几个字段作为一条独立尝试的最小信息集：

• network：例如 tcp 或具体网络类型。
• addr：本次 Dial 使用的地址。
• started_at 与 ended_at：计算拨号耗时。
• err：这一次拨号的错误；为空只表示拨号阶段没有返回错误。

如果只想统计“最终使用了哪个连接”，应把 ConnectStart 的尝试列表与 GotConn 的成功取得连接分开。前者回答“试过哪些地址”，后者回答“Transport 最终交给请求的是哪条连接”。

检查 Transport 与日志生命周期

排查 ConnectStart 时，下面几个误区很常见：

如果需要观察连接复用，使用长期复用的同一个 http.Client 和 Transport，再在 GotConn 中记录 Reused、WasIdle 和 IdleTime。如果每次请求都创建新的 Transport，连接池状态会被切断，ConnectStart 的数量也会失去比较意义。

相关问题

ConnectStart 的 addr 是服务器地址还是代理地址？

它表示当前 Dial 尝试使用的目标地址；如果配置了代理，应结合 Transport 的代理配置与实际网络阶段理解，不要只按 URL 中的主机名推断。

ConnectDone 的 err 为空就一定能复用连接吗？

不一定。它只说明这一次连接 Dial 没有返回错误，后续请求流程和连接回收到空闲池仍有自己的条件。

为什么请求复用连接时没有 ConnectStart？

因为 ConnectStart 针对新连接的 Dial。复用已有连接时，应通过 GotConn 观察连接是否来自空闲池。