Master Go Performance Profiling with go tool pprof: A Step‑by‑Step Guide

1. Basics of Profiling

1.1 What is pprof

pprof is Go's built‑in profiling tool that can analyze CPU usage, memory allocation, and other runtime characteristics.

1.2 Installation and Basic Usage

pprof is part of the Go standard library, so it is available once Go is installed. The typical workflow is:

Import the net/http/pprof package. import _ "net/http/pprof" Start an HTTP server that exposes profiling endpoints.

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof"
)

func main() {
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()
    log.Println("starting server")
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, world!"))
    })
    log.Println(http.ListenAndServe(":80", nil))
    log.Println("server stopped")
    select {}
}

Build and run the program.

go build -o myapp
./myapp

Generate a CPU profile file (30‑second collection).

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

This command creates a profile file that can be examined with pprof.

Typical profiling UI screenshot:

2. Analyzing Data

2.1 CPU Profiling

After the go tool pprof command finishes, a CPU profile file is saved and the interactive pprof console opens. You can also load a saved file manually:

go tool pprof .\pprof.app.exe.samples.cpu.001.pb.gz

Inside the console, common commands are: top: Show functions that consume the most CPU time. list function_name: Display source code and detailed metrics for a specific function. web: Generate a flame graph and open it in a browser.

2.2 Memory Profiling

pprof can also capture heap usage:

go tool pprof http://localhost:6060/debug/pprof/heap

Or analyze a saved heap profile with a similar command, e.g.,

go tool pprof pprof.app.exe.alloc_objects.alloc_space.inuse_objects.inuse_space.001.pb.gz

Typical memory‑profiling UI screenshot:

3. Understanding Results

3.1 top Command Output

The top command lists functions with columns such as: flat: Time spent in the function itself. cum: Cumulative time including called sub‑functions. flat% and cum%: Percentages of total runtime.

3.2 Flame Graph

Running web produces a flame graph where each rectangle represents a function; the rectangle width corresponds to the time spent.

4. Optimization Suggestions

Reduce unnecessary memory allocations : Examine the cost of runtime.mallocgc and eliminate superfluous allocations.

Parallelize processing : If a function dominates CPU time, consider splitting work across goroutines.

Cache frequently used data : Store results that are repeatedly computed to avoid redundant work.

5. Conclusion

By following this guide, you can effectively use go tool pprof to profile Go applications, interpret CPU and memory data, generate visual flame graphs, and apply concrete optimizations that improve overall performance.