Classical compilation has a built-in contradiction. The compiler must turn source code into fast machine instructions at build time—when the program has never run under live traffic and nobody knows which if branch will fire a million times a second versus once a month for a rare error. Meanwhile, a running production server knows its bottlenecks every second, yet it can no longer rewrite its own machine code on the fly.
Profile-Guided Optimization—PGO in Go (also known as Feedback-Directed Optimization)—resolves this paradox. We capture a load profile from a running service and feed it to the compiler when building the next release. As noted by the authors of the «Библиотека Go-разработчика» channel, this loop speeds up a program without touching business logic, on one condition: the compiler must learn from real traffic, not synthetic tests. I dug into the docs and build mechanics to show how to squeeze extra speed out of a Go service with PGO without hurting edge cases.
What the Compiler Learns from Runtime: Inlining and Call Handling
Imagine packing a suitcase for a trip blind: without knowing the itinerary, you pack everything evenly, and at the train station you always end up digging to the bottom for your charger. A static compiler is in the same spot and relies on conservative guesses to avoid bloating the executable.
Experimental PGO support arrived in Go 1.20, and since Go 1.21 it has been enabled by default. The compiler gained "eyes" in the form of a standard pprof CPU profile. According to Go team benchmarks (starting with Go 1.22), building with a profile speeds up representative programs by 2–14% through three mechanisms:
- Targeted function inlining. Calling a function burns CPU cycles saving context and jumping in memory. The compiler can inline a small function's body directly at the call site, but it can't inline everything: the binary would bloat, and the CPU's fast instruction cache (L1i) would clog up with cold code. Using a CPU profile, the compiler sees real load and aggressively inlines the genuinely hot functions.
- Interface devirtualization and branch optimization. Calling a method through an interface looks up the address in a method table at runtime. If the profile shows that one concrete type almost always sits behind an interface, the compiler replaces the indirect call with a direct jump guarded by a fast type check and arranges branches to avoid CPU pipeline flushes.
- Rebuilding dependencies and the standard library. The profile applies across the entire program. This is similar to how the low-level memory allocator architecture in Go 1.27 speeds up small-object allocations without code changes—except with PGO, the compiler reshapes library packages specifically around your service's patterns.
Let's look at an end-to-end example: a high-load API microservice receives a stream of requests during the daytime peak and serializes large responses into JSON. Without a profile, parsing and buffer-handling methods are called down a chain of standard wrappers. Once given a daytime peak profile, the compiler sees that most CPU time goes into internal JSON serialization functions and inlines them straight into the handler's hot path.
Capturing a Representative pprof Profile: The Synthetic Benchmark Trap
Here it is easy to give in to the temptation to save time: why collect metrics from production servers when you can run a local go test -bench in a minute and hand that profile to the compiler?
In my view, that is the sneakiest trap when getting started with PGO. A synthetic microbenchmark loops an isolated slice of code—for example, serializing a single small struct into an empty buffer a thousand times, detached from the network and HTTP headers. If you build our API microservice with that profile, the compiler will spend its inlining budget on an artificial loop, leaving the real hot paths of the network stack and complex JSON responses unoptimized.
Even in production, a single sample can be misleading: a random pod might be idle, running a five-minute background job, or receiving a skewed slice of requests. That is why the Go documentation recommends capturing CPU profiles via net/http/pprof from multiple instances and merging them.
Let's collect two 30-second profiles from nodes of our API microservice during the daytime peak and merge them with pprof into default.pgo:
# Capture 30-second CPU profiles from two nodes at peak traffic
curl -o cpu-node1.pprof "http://10.0.1.15:6060/debug/pprof/profile?seconds=30"
curl -o cpu-node2.pprof "http://10.0.1.16:6060/debug/pprof/profile?seconds=30"
# Merge samples into a single profile for the compiler
go tool pprof -proto cpu-node1.pprof cpu-node2.pprof > default.pgo
The seconds=30 parameter in both requests must match. The go tool pprof -proto command simply sums samples from the input files without adjusting for wall duration: if one profile ran for 30 seconds and the other for 5 minutes, the longer capture will pull the optimization weight toward itself. And remember security: /debug/pprof/* routes must never be exposed publicly—port 6060 should only be reachable inside an isolated cluster network.
Auto-Detecting default.pgo and Verifying the Binary with go version -m
The workflow follows a closed AutoFDO loop: ship an initial binary without PGO, capture a profile in production, and use it when building the next release. Just place default.pgo in the main package directory and commit it to the repository for reproducible builds. By default, go build runs in -pgo=auto mode and picks up default.pgo automatically.
Let's drop the profile into the microservice directory, build both the production and control binaries, and inspect the build metadata (verified on Go 1.27.3):
# Put the profile in the main package directory and build both variants
mv default.pgo ./cmd/api-service/default.pgo
cd ./cmd/api-service
go build -o service .
go build -pgo=off -o service-no-pgo .
# Verify the profile is embedded in the compiled binary
go version -m service | grep pgo
The output of the last command will show -pgo=.../default.pgo, confirming the compiler found and applied the profile. If your repository has multiple services and you pass a path manually via go build -pgo=/tmp/api.pprof ./cmd/api ./cmd/worker, keep in mind that the explicit flag applies one profile to all main packages at once. Also, as «Библиотека Go-разработчика» stresses, the -pgo line in go version -m only proves the file was wired in at build time—not that it actually sped up production.
The -pgo=off Control Build, Optimization Costs, and Boundaries
To prove the gain in practice, we built the service-no-pgo control binary with -pgo=off. Both binaries are rolled out under identical load to compare CPU usage and response latency. In our API microservice, that comparison shows that inlining hot JSON serialization methods genuinely lowers response latency at peak traffic.
Still, that 2–14% speedup comes with trade-offs:
- First-build time and binary size. The profile rebuilds the dependency graph and standard library, so the first compile with a new
default.pgotakes longer (subsequent builds pull from cache), and the binary grows slightly due to inlining. - Profile staleness during refactoring (
source stability). I was pleased to find that the compiler matches samples to code byline offsetsfrom the start of a function, ignoring file names. Edits outside a hot function or moving it to another file in the same package won't break PGO. However, renaming methods, moving them to another package, or editing their bodies breaks the match—and optimization gradually degrades until the profile is refreshed. - One binary for different workloads. If a single binary handles both read-heavy and write-heavy modes with different hot paths, you'll need to either build separate versions, profile the primary mode, or merge profiles across the entire fleet.
At the same time, Go PGO is protected against speed ping-ponging between releases (iterative stability): the compiler's conservative heuristic prevents an already-sped-up function from dropping out of the hot list on the next build, so you can capture a fresh profile directly from an already-optimized binary. And for how the runtime schedules work across CPU cores, I walked through the anatomy of the Go scheduler and the GMP model.
The key with PGO is keeping a sense of proportion and not turning default.pgo rebuilds into a cult. A compiler flag won't replace a missing database index or fix contention on synchronous locks. Set up a steady capture of 30-second pprof slices at peak load, drop default.pgo into your main package, verify builds with go version -m and a -pgo=off baseline—and refresh the profile whenever hot paths change in code.

