golang

Go httptrace 入门：看清一次 HTTP 请求慢在哪里

写 Go 服务时，调用外部接口慢是很常见的问题。日志里只看到“请求花了 2 秒”，但这 2 秒到底花在哪里？是 DNS 慢、建立连接慢、TLS 握手慢、服务端处理慢，还是响应体下载慢？如果只能靠猜，排查会很痛苦。

PlumePHP 2024-01-25 11 分钟阅读 5381 字

Go 标准库的 net/http/httptrace 可以把一次 HTTP 客户端请求拆成多个阶段观察。它不是线上监控系统，但在本地调试、预发排查和定位某个外部依赖时非常有用。本文用一个小函数讲清楚基本用法。

普通请求只能看到总耗时

很多代码会这样记录：

func Fetch(ctx context.Context, url string) error {
	start := time.Now()
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return err
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	_, _ = io.Copy(io.Discard, resp.Body)
	log.Printf("fetch url=%s cost=%s", url, time.Since(start))
	return nil
}

这能知道总耗时，但不知道阶段。外部接口慢的时候，总耗时只是入口信息，不足以指导优化。如果 DNS 解析慢，应该看 DNS 和网络；如果首字节慢，更多是对方服务端处理或排队；如果响应体慢，可能是数据太大或带宽问题。

加入 httptrace

httptrace.ClientTrace 可以挂到请求 context 上：

func FetchWithTrace(ctx context.Context, rawURL string) error {
	var start, dnsStart, connStart, tlsStart time.Time

	trace := &httptrace.ClientTrace{
		DNSStart: func(info httptrace.DNSStartInfo) {
			dnsStart = time.Now()
			log.Printf("dns start host=%s", info.Host)
		},
		DNSDone: func(info httptrace.DNSDoneInfo) {
			log.Printf("dns done cost=%s addrs=%v err=%v", time.Since(dnsStart), info.Addrs, info.Err)
		},
		ConnectStart: func(network, addr string) {
			connStart = time.Now()
			log.Printf("connect start network=%s addr=%s", network, addr)
		},
		ConnectDone: func(network, addr string, err error) {
			log.Printf("connect done cost=%s err=%v", time.Since(connStart), err)
		},
		TLSHandshakeStart: func() {
			tlsStart = time.Now()
			log.Println("tls start")
		},
		TLSHandshakeDone: func(state tls.ConnectionState, err error) {
			log.Printf("tls done cost=%s err=%v", time.Since(tlsStart), err)
		},
		GotFirstResponseByte: func() {
			log.Printf("first byte cost=%s", time.Since(start))
		},
	}

	start = time.Now()
	ctx = httptrace.WithClientTrace(ctx, trace)
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
	if err != nil {
		return err
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	_, _ = io.Copy(io.Discard, resp.Body)
	log.Printf("total cost=%s", time.Since(start))
	return nil
}

这段代码会输出 DNS、连接、TLS、首字节和总耗时。不是每次请求都会触发所有事件。比如连接复用时，可能不会重新 DNS 和 TLS。这本身也是重要信息：如果连接复用正常，慢点就更可能在服务端处理或响应体阶段。

看懂几个阶段

DNS 阶段慢，通常和域名解析、DNS 服务、网络环境有关。连接阶段慢，可能是网络不通、跨区域延迟、对方端口拥塞。TLS 阶段慢，可能是握手成本、证书链或网络抖动。首字节慢，表示请求已经发出，但迟迟没有收到响应头，常见原因是对方服务处理慢或排队。

如果总耗时很长，但首字节很快，问题可能在读取响应体。比如下载一个很大的 JSON，或者对方分块慢慢返回。此时优化方向可能是分页、压缩、减少字段，而不是盯着连接池。

配合超时使用

trace 只是观察，不能替代超时。客户端仍然应该设置超时：

client := &http.Client{
	Timeout: 5 * time.Second,
}

更细的服务可以使用自定义 Transport：

transport := &http.Transport{
	MaxIdleConns:        100,
	MaxIdleConnsPerHost: 10,
	IdleConnTimeout:     90 * time.Second,
	TLSHandshakeTimeout:  5 * time.Second,
}
client := &http.Client{Transport: transport, Timeout: 10 * time.Second}

如果 trace 发现每次都在重新建连接，就要检查是否复用了同一个 client，是否正确读取并关闭响应体。每次请求都新建 http.Client 通常不是好习惯。

不要长期打印过细日志

httptrace 输出很细，适合临时排查，不适合高频接口长期全量打印。你可以只在 debug 模式开启，或者只对某个请求 ID 开启。日志太多会影响性能，也会让真正重要的信息被淹没。

一种简单做法是：

if cfg.EnableHTTPTrace {
	ctx = httptrace.WithClientTrace(ctx, trace)
}

生产环境如果需要长期观测，更适合用指标系统记录阶段耗时，或者在网关、客户端库里做采样。入门阶段先会用 trace 定位问题，已经很有价值。

和连接池问题一起看

很多“偶发慢请求”最后会和连接池有关。比如响应体没有读完或没有关闭，连接无法复用，后续请求就不得不重新建连接。trace 里如果频繁看到 ConnectStart 和 TLSHandshakeStart，就要检查调用代码：

resp, err := client.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close()
_, _ = io.Copy(io.Discard, resp.Body)

如果业务只关心状态码，也仍然建议把 body 读完或明确关闭。对小响应来说，读到 io.Discard 成本很低，却能帮助连接复用。大响应则要看场景，不能为了复用把几 GB 数据都读完。

排查时可以把 trace 日志和请求 ID 放在一起。一次慢请求有唯一 ID，trace 里有阶段耗时，业务日志里有接口和参数范围，几类信息合在一起才容易形成判断。不要只截一行 total cost=2s 就开始改代码。

WroteHeaders 和 WroteRequest 事件

除了连接和 TLS，httptrace 还有更细的事件：WroteHeaders 和 WroteRequest。

trace := &httptrace.ClientTrace{
    WroteHeaders: func() {
        log.Println(“headers written”)
    },
    WroteRequest: func(info httptrace.WroteRequestInfo) {
        log.Printf(“request written err=%v”, info.Err)
    },
}

WroteHeaders 表示请求头已经发送到传输层，WroteRequest 表示整个请求（包括 body）已经写完。某些场景下请求 body 很大，写入本身也可能耗时。

对于 HEAD 或 GET 请求，body 为空，WroteHeaders 和 WroteRequest 几乎同时发生。对于 POST multipart 或上传大 JSON 的场景，body 写入可能占到不少时间。把这些事件也加上，可以区分”服务端响应慢”和”请求发出去的速度慢”。

使用指标系统替代日志

生产环境不要把 httptrace 打到普通日志里。更正式的做法是把它集成到 tracing 系统，比如 OpenTelemetry 或自研指标平台。每个阶段都作为 span，整体请求是 parent span：

func TracedRequest(ctx context.Context, method, url string, body io.Reader) (*http.Response, error) {
    start := time.Now()
    var dnsDur, connDur, tlsDur, ttfbDur time.Duration

    trace := &httptrace.ClientTrace{
        DNSStart: func(_ httptrace.DNSStartInfo) {
            // mark span start
        },
        DNSDone: func(_ httptrace.DNSDoneInfo) {
            dnsDur = time.Since(start)
        },
        TLSHandshakeDone: func(_ tls.ConnectionState, _ error) {
            tlsDur = time.Since(start)
        },
        GotFirstResponseByte: func() {
            ttfbDur = time.Since(start)
        },
    }

    ctx = httptrace.WithClientTrace(ctx, trace)
    req, _ := http.NewRequestWithContext(ctx, method, url, body)
    resp, err := http.DefaultClient.Do(req)

    // record metrics: dnsDur, connDur, tlsDur, ttfbDur
    return resp, err
}

这样所有请求的各阶段耗时可以聚合、报警、对比基线。微量日志分散在文件里看不到全貌，指标才能真正指导性能优化。

连接复用排查实战

线上偶发”有时快有时慢”的问题，90% 和连接复用有关。如果请求每次都要新建连接，延迟至少翻倍。快速排查方法是在 trace 里关注 ConnectStart 出现频率：

现象	可能原因	解决方法
每个请求都有 ConnectStart	连接没复用	检查 client 是否全局复用、Body 是否关闭
TLSHandshake 频繁	同上，但影响更大	开启连接池调优，确保 MaxIdleConns 够用
同域名偶尔有 ConnectStart	连接到了 idle timeout	适当延长 IdleConnTimeout
DNS 阶段性慢	解析服务不稳定	考虑本地 DNS 缓存或 systemd-resolved

一个真实案例：某服务调用第三方 API 大约在第 100 到 110 个请求时突然变慢。排查后发现 MaxIdleConnsPerHost 默认是 2，并发 worker 有 20 个，导致大部分请求竞争连接。把 MaxIdleConnsPerHost 提升到 worker 数后问题消失。

DNS 解析调优

Go 1.20 之前 net.Resolver 默认使用 Go 实现的解析器，不依赖系统 getaddrinfo。可以通过环境变量 GODEBUG=netdns=cgo 切换成 C 实现。某些企业内网 DNS 环境，C 实现的表现更好。

// 自定义 Resolver
dialer := &net.Dialer{
    Timeout:   3 * time.Second,
    KeepAlive: 30 * time.Second,
    Resolver: &net.Resolver{
        PreferGo: true,
        Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
            d := net.Dialer{Timeout: 3 * time.Second}
            return d.DialContext(ctx, “udp”, “8.8.8.8:53”)
        },
    },
}

transport := &http.Transport{
    DialContext: dialer.DialContext,
}

如果 DNS 持续慢，也可以考虑在应用层做缓存。把域名解析结果缓存在内存中几分钟，能大幅减少 DNS 耗时。但缓存要注意 TTL，不要和权威记录脱节。

httptrace 与 pprof 结合

httptrace 分阶段观察单次请求，pprof 看整体 CPU 和 goroutine 分布。两者结合效果更好：

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10

如果 pprof 显示大量时间花在 net.Dial 或 tls.Handshake，而 trace 显示正常的业务接口偶尔慢，说明连接创建是瓶颈。此时优化方向是复用连接、加连接池、或者改成 HTTP/2 多路复用。

常见坑与避坑指南

不要每次请求新建 http.Client：client 内部的连接池是复用的基础，每次新建都会丢失已有连接。
body 没读完就关闭：defer resp.Body.Close() 只是关闭 body，不代表读完。为了复用连接，最好 io.Copy(io.Discard, resp.Body)。
忽略 tls.Config 配置：跳过证书校验 (InsecureSkipVerify) 应该只在测试环境使用，生产环境要走正常 TLS 链。
trace 回调里做阻塞操作：回调在请求 goroutine 里执行，如果在里面做持久化、网络调用，会阻塞真正发请求的 goroutine。
只看总耗时就改代码：总耗时不能指导优化方向，有了分阶段数据再动手。

小结

httptrace 能帮你看清一次 Go HTTP 客户端请求的 DNS、连接、TLS、首字节等阶段。它适合定位”外部接口为什么慢”，尤其是在总耗时日志无法说明原因时。配合指标系统，可以把单次排查变成长期观测能力。

排查时先加总超时，再用 trace 分阶段观察。看到数据后再决定优化方向：连接复用、DNS、TLS、服务端处理、响应体大小，分别对应不同解法。性能问题不要靠猜，先把请求过程照亮。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

函数是否处理了所有 error 返回值
并发代码是否有明确的退出路径和 WaitGroup
用户输入是否经过校验和清洗
敏感配置是否通过环境变量或加密存储注入
测试是否覆盖了正常路径和至少一个错误路径
日志是否包含足够的上下文信息但不泄露敏感数据
接口设计是否符合最小接口原则

CI/CD 集成建议

每次提交前运行 go fmt ./...
CI 中运行 go vet ./... 和 golangci-lint run
单元测试使用 go test -race ./... 检测数据竞争
关键路径的 benchmark 加入回归测试
使用 go mod verify 确保依赖完整性

性能调优检查点

使用 pprof 分析 CPU 和内存使用
关注 benchmark 的 allocs/op，减少高频路径的堆分配
检查数据库查询是否使用索引
确认外部 HTTP 调用有合理的超时设置
缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

goroutine 和线程的区别
channel 的缓冲和非缓冲用法
defer 的执行顺序和与返回值的关系
map 的并发不安全性和解决方案
interface 的隐式实现和类型断言
slice 的底层数组和 append 机制
GC 的基本原理和调优参数
context 的使用场景和超时控制
error 的包装和 errors.Is/errors.As
sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

把文中所有示例代码在自己的机器上跑一遍
给示例代码补充错误分支的测试用例
尝试基于本文内容构建一个小型完整项目
在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

Go 官方网站：https://go.dev/
Go 标准库文档：https://pkg.go.dev/std
Go by Example：https://gobyexample.com/
Effective Go：https://go.dev/doc/effective_go
Go 常见问题：https://go.dev/doc/faq
Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

把 trace 数据结构化输出

直接打印日志适合临时调试，如果要持久化分析，建议把 trace 数据结构化：

type TraceMetrics struct {
	DNSLookup      time.Duration `json:"dns_lookup"`
	TCPConnection  time.Duration `json:"tcp_connection"`
	TLSHandshake   time.Duration `json:"tls_handshake"`
	ServerProcess  time.Duration `json:"server_process"`
	Total          time.Duration `json:"total"`
}

func FetchWithStructuredTrace(ctx context.Context, rawURL string) (*TraceMetrics, error) {
	var metrics TraceMetrics
	var dnsStart, connStart, tlsStart, serverStart time.Time
	traceStart := time.Now()

	trace := &httptrace.ClientTrace{
		DNSStart: func(_ httptrace.DNSStartInfo) {
			dnsStart = time.Now()
		},
		DNSDone: func(_ httptrace.DNSDoneInfo) {
			metrics.DNSLookup = time.Since(dnsStart)
		},
		ConnectStart: func(_, _ string) {
			connStart = time.Now()
		},
		ConnectDone: func(_, _ string, _ error) {
			metrics.TCPConnection = time.Since(connStart)
		},
		TLSHandshakeStart: func() {
			tlsStart = time.Now()
		},
		TLSHandshakeDone: func(_ tls.ConnectionState, _ error) {
			metrics.TLSHandshake = time.Since(tlsStart)
		},
		GotFirstResponseByte: func() {
			serverStart = time.Now()
			metrics.ServerProcess = time.Since(serverStart)
		},
	}

	ctx = httptrace.WithClientTrace(ctx, trace)
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
	if err != nil {
		return nil, err
	}

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	_, _ = io.Copy(io.Discard, resp.Body)

	metrics.Total = time.Since(traceStart)
	return &metrics, nil
}

结构化后可以直接上报到监控系统，或者存进日志供后续分析。

利用 trace 诊断连接池问题

偶发的慢请求经常和连接池耗尽有关。通过 trace 里的 GetConn 和 PutIdleConn 可以观察连接复用情况：

trace := &httptrace.ClientTrace{
	GetConn: func(hostPort string) {
		log.Printf("get conn for %s", hostPort)
	},
	GotConn: func(info httptrace.GotConnInfo) {
		log.Printf("got conn reused=%v idle=%v", info.Reused, info.WasIdle)
	},
	PutIdleConn: func(err error) {
		if err != nil {
			log.Printf("put idle conn err=%v", err)
		}
	},
}

如果 Reused=false 出现频率很高，说明连接池没有正常工作。常见原因包括：

响应体没有读完
连接数超过 MaxIdleConns 或 MaxIdleConnsPerHost
TLS 连接无法复用（如使用不同 SNI）

和 pprof 结合进行深度分析

httptrace 定位到某一阶段慢之后，可以用 pprof 进一步分析：

import _ "net/http/pprof"

func init() {
	go func() {
		log.Println(http.ListenAndServe("localhost:6060", nil))
	}()
}

运行时通过 go tool pprof http://localhost:6060/debug/pprof/profile 获取 CPU profile，结合 trace 的阶段信息定位具体的热点代码。

真实排查案例

一个典型的排查案例：服务调用第三方 API，偶发出现 3 秒延迟。加了 httptrace 后发现：

DNS 很快（10ms）
TCP 连接很快（50ms）
TLS 握手偶尔很慢（2-3s）

进一步排查发现是 TLS 证书链中有一个 OCSP stapling 检查超时。解决方案是升级客户端库的 TLS 配置，或者联系第三方修复证书链。没有 httptrace 的阶段拆分，这个问题很难快速定位。

常见坑与避坑指南

trace 日志不要长期全量开启：只用于排查期，排查完及时关闭。
不要只看总耗时：总耗时 2s 可能是 DNS 花了 1.9s，也可能是服务端处理慢，解法完全不同。
连接复用和 trace 事件有关：如果没看到 GotConn 的 Reused=true，先检查响应体是否正确关闭。
TLS 慢不一定是证书问题：也可能是网络抖动，要结合多次采样看是否持续。
httptrace 不能替代监控：它是排查工具，长期跟踪还是要靠 APM 或指标系统。

小结

httptrace 能帮你看清一次 Go HTTP 客户端请求的 DNS、连接、TLS、首字节等阶段。它适合定位"外部接口为什么慢"，尤其是在总耗时日志无法说明原因时。

排查时先加总超时，再用 trace 分阶段观察。把 trace 数据结构化后，可以更方便地上报和持久化。结合连接池诊断和 pprof，能形成完整的性能排查链路。看到数据后再决定优化方向：连接复用、DNS、TLS、服务端处理、响应体大小，分别对应不同解法。性能问题不要靠猜，先把请求过程照亮。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页

普通请求只能看到总耗时

加入 httptrace

看懂几个阶段

配合超时使用

不要长期打印过细日志

和连接池问题一起看

WroteHeaders 和 WroteRequest 事件

使用指标系统替代日志

连接复用排查实战

DNS 解析调优

httptrace 与 pprof 结合

常见坑与避坑指南

小结

真实项目用例

代码审查清单

CI/CD 集成建议

性能调优检查点

面试高频考点

常见问题（FAQ）

常见坑与避坑指南

延伸阅读与实践建议

参考资源

把 trace 数据结构化输出

利用 trace 诊断连接池问题

和 pprof 结合进行深度分析

真实排查案例

常见坑与避坑指南

小结

探索更多技术文章

「golang」更多文章