Go Memory Profiling with pprof

WHY IT EXISTS Go is a garbage-collected language, but that doesn't prevent all memory issues. High memory usage can increase GC pressure and costs, while memory leaks (unreleased object references) can eventually crash a program. You need a tool to see exactly what part of your code is allocating memory and whether it's being retained.

THE MENTAL MODEL Think of pprof as taking a photograph of your application's heap at a specific moment. This 'memory profile' is a data file that lists all the functions in your program and how much memory they have allocated. By analyzing this snapshot, or comparing it to another one taken later, you can identify which parts of your code are consuming the most memory or failing to release it.

HOW IT WORKS You enable profiling in your Go application, which then collects data about memory allocations by sampling the heap and recording the call stack for each allocation. You can trigger this data collection in three main ways: first, using flags with go test (-memprofile); second, adding code to your main function to write a profile file on demand; or third, exposing a standard HTTP endpoint via import _ "net/http/pprof". The resulting profile file is then analyzed with the go tool pprof command, which provides views like a top-down list or an interactive call graph.

WHEN TO USE IT Use memory profiling when you observe your application's memory usage growing unexpectedly over time, indicating a potential leak. It's also valuable for performance tuning when you want to reduce memory churn (frequent allocations and deallocations) to lessen the load on the garbage collector. It's the standard tool for diagnosing production memory issues in Go services.

WHEN NOT TO USE IT Avoid running memory profiling continuously in production with high frequency, as the sampling process itself introduces performance overhead. For general application health monitoring, use metrics like total memory usage (RSS). Profiling is a diagnostic tool for when you've already identified a potential problem, not a general-purpose, always-on monitoring solution.

ONE CANONICAL EXAMPLE To get a memory profile from a running web server, first import the net/http/pprof package. This automatically registers handlers on the /debug/pprof/ path. With your server running, you can then use go tool pprof to fetch and analyze the current heap profile directly: go tool pprof http://localhost:8080/debug/pprof/heap. This command opens an interactive prompt where you can type top to see the functions using the most memory or web to visualize the call graph in a browser.