A Go memory leak often starts as a silent performance killer. Your application runs smoothly for hours, but eventually, the resident set size (RSS) creeps up until the OS triggers an OOM (Out of Memory) kill. While Go features a robust garbage collector, it cannot reclaim memory that is still reachable through global variables, forgotten cache entries, or blocked goroutines. To fix these issues, you need to see exactly what is sitting in your heap.
This guide demonstrates how to use the standard pprof tool to inspect memory allocations in Go 1.22 and later. You will learn how to expose profiling endpoints, capture heap snapshots, and interpret the data to find the root cause of leaks. By the end, you will have a repeatable workflow for maintaining high-performance Golang services.
TL;DR — Expose net/http/pprof, use go tool pprof -http=:8080 [binary] [profile_url] to visualize allocations, and look for "inuse_space" to find objects the garbage collector cannot free.
Understanding the Go Heap and Stack
In Go, the runtime automatically decides whether a variable lives on the stack or the heap through escape analysis. Variables that stay within a function's scope usually remain on the stack, which is incredibly fast to clean up. However, if a variable is referenced outside the function or is too large, it "escapes" to the heap. The Garbage Collector (GC) is responsible for cleaning the heap, but it only removes items that have zero references.
A memory leak in Go isn't usually "lost" memory in the C sense. Instead, it is "unintended retention." This occurs when your code maintains a reference to an object that you no longer need. If a global slice keeps growing, or if a goroutine remains blocked forever while holding onto a large struct, that memory is considered "in use" by the GC and is never freed. Understanding this distinction is vital for effective Golang performance tuning.
When to Profile Your Application
You should profile your application whenever the memory usage does not stabilize after the initial startup phase. In a healthy Go service, memory usage should look like a "sawtooth" pattern: it climbs as objects are allocated and drops sharply after a GC cycle. If the baseline of that sawtooth is constantly trending upward, you have a leak. This is common in high-throughput APIs where request objects are accidentally persisted in a cache or global state.
Another critical scenario is the "Goroutine Leak." Because goroutines are cheap to create (initially ~2KB), developers often spawn them without a clear exit strategy. If a goroutine waits on a channel that never receives data, it stays in memory forever. Each leaked goroutine also keeps its entire stack and any referenced heap variables alive. If your service handles 1,000 requests per second and leaks one goroutine per request, your server will crash in minutes. Regular monitoring of goroutine counts is a prerequisite for production stability.
Step-by-Step: Profiling with pprof
Step 1: Expose the pprof Endpoint
The easiest way to profile a web server is to use the net/http/pprof package. Simply import it with a blank identifier. This automatically registers several handlers under /debug/pprof/.
package main
import (
"net/http"
_ "net/http/pprof" // Registers pprof handlers
"log"
)
func main() {
// Start your application logic here
go func() {
log.Println(http.ListenAndServe("localhost:6060", nil))
}()
// Your actual server code
select {}
}Step 2: Collect a Heap Profile
Once your application is running, use the go tool pprof command-line utility to capture the data. It is best to do this while the application is under load so you can see real-world allocation patterns.
# Download the heap profile and open the interactive web UI
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/heapStep 3: Analyze the Data
In the web UI, navigate to the Sample menu and select inuse_space. This shows memory currently held by the application. The Graph view provides a visual flow of which functions are responsible for the most memory retention. Look for "fat" boxes; these indicate the functions where the memory is being allocated. If you see unexpected functions at the top of the list, click on them to view the source code and identify the specific line causing the allocation.
Common Causes of Memory Leaks
http.Response.Body. When you perform an HTTP request, the response body must be closed, even if you don't read it. Failing to do so prevents the underlying TCP connection and buffer memory from being reused or freed.
One frequent source of leaks is the misuse of time.Ticker. Unlike time.After, a Ticker must be manually stopped using ticker.Stop(). If you create a ticker inside a function and let the function return without stopping it, the ticker will continue to run in the background, preventing the GC from reclaiming its resources. Always use a defer ticker.Stop() immediately after initialization.
Another subtle leak involves slicing large arrays. If you have a 1GB slice and you create a new slice of just the first 10 elements (small := large[:10]), the small slice still references the underlying 1GB array. The entire 1GB remains in memory as long as small is reachable. To fix this, allocate a new slice and use the copy() function to move only the data you need.
// Bad: Keeps the whole largeSlice in memory
subSlice := largeSlice[:10]
// Good: Allows largeSlice to be garbage collected
subSlice := make([]byte, 10)
copy(subSlice, largeSlice[:10])Optimization Tips and Best Practices
To keep your memory footprint low, favor sync.Pool for frequently allocated objects. For example, if your application processes JSON repeatedly, using a pool of bytes.Buffer objects can significantly reduce the pressure on the Garbage Collector. When I implemented sync.Pool for a high-traffic logging service, the time spent in GC dropped by 40%, and the overall memory usage became much more predictable.
Always instrument your code with metrics. Use the runtime.ReadMemStats function to export HeapAlloc, HeapSys, and NumGoroutine to your monitoring system (like Prometheus). Setting alerts on these metrics allows you to catch a Go memory leak in a staging environment before it ever reaches production. For more details, consult the official pprof documentation.
- Use
net/http/pprofto expose real-time profiling data. - Analyze
inuse_spaceto find memory that isn't being freed. - Check
/debug/pprof/goroutine?debug=1to find blocked goroutines. - Always close response bodies, stop tickers, and avoid slicing large arrays into long-lived variables.
Frequently Asked Questions
Q. How do I identify a goroutine leak?
A. Visit /debug/pprof/goroutine?debug=1 in your browser. If you see thousands of goroutines stuck on the same line (e.g., chan receive), you have a leak. Use the stack trace provided to find the function that isn't exiting.
Q. What is the difference between alloc_space and inuse_space?
A. alloc_space shows the total memory allocated since the program started, including what was already collected. inuse_space shows only what is currently in memory. For finding leaks, inuse_space is the most important metric.
Q. Does pprof slow down my production application?
A. CPU profiling has a small overhead (approx 1-5%), but heap profiling is extremely lightweight and safe to leave enabled in production. Just ensure the endpoint is not exposed to the public internet for security reasons.
Post a Comment