pprof - net/http Package Documentation

Package pprof

Package pprof provides support for profiling Go programs. It exposes execution profiles over HTTP, including CPU, memory, goroutine, and blocking profiles. This allows for runtime inspection and debugging of performance characteristics.

Overview

The pprof package is an integral part of Go's performance analysis tooling. By exposing profiles via HTTP, it enables developers to interactively explore the runtime behavior of their applications. This is particularly useful in production environments where attaching traditional debuggers might be impractical.

Key Features

CPU Profiling: Collects CPU usage data, showing which functions are consuming the most CPU time.
Memory Profiling: Tracks memory allocations, helping to identify memory leaks or excessive usage.
Goroutine Profiling: Provides insights into the number and state of goroutines, useful for debugging deadlocks or excessive concurrency.
Blocking Profiling: Records goroutine blocking events, such as waiting for mutexes or channels.
HTTP Endpoint: Profiles are served via HTTP on specific endpoints, typically under /debug/pprof/.

Usage

To enable pprof in your application, you typically need to import the net/http/pprof package and register its handlers with your HTTP server.


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

func main() {
	// For example, start a regular HTTP server
	go func() {
		log.Println(http.ListenAndServe("localhost:6060", nil))
	}()

	// ... your application logic ...
}

Once registered, you can access the profiles via HTTP. The default endpoints include:

/debug/pprof/: A web UI for exploring profiles.
/debug/pprof/cmdline: Prints the command line.
/debug/pprof/profile: CPU profile.
/debug/pprof/heap: Heap profile.
/debug/pprof/goroutine: Goroutine profile.
/debug/pprof/block: Blocking profile.
/debug/pprof/threadcreate: Thread creation profile.
/debug/pprof/mutex: Mutex profile.

Example: Capturing a CPU Profile

Capturing a CPU profile for 30 seconds:

You can use curl to fetch a CPU profile:


curl -o cpu.pprof http://localhost:6060/debug/pprof/profile?seconds=30

Then, analyze the profile using the go tool pprof command:


go tool pprof cpu.pprof

Configuration Options

While the default configuration is often sufficient, pprof offers ways to customize the profiling behavior. For instance, you can control the sampling rate or specify which handlers to register.

To use a custom HTTP handler, you can register the pprof handlers manually:


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

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/debug/pprof/", pprof.Index)
	mux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
	mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
	mux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
	mux.HandleFunc("/debug/pprof/trace", pprof.Trace)

	// ... register your other handlers on mux ...

	go http.ListenAndServe("localhost:6060", mux)
	// ...
}

Best Practices

Enable in Development and Staging: Use pprof extensively during development and in staging environments to catch performance issues early.
Secure Production Access: Be cautious when exposing pprof endpoints in production. It's recommended to protect these endpoints with authentication or restrict access to trusted IP addresses.
Understand Profile Types: Choose the appropriate profile type (CPU, memory, etc.) based on the performance issue you are investigating.
Use go tool pprof: Familiarize yourself with the go tool pprof command-line utility for in-depth analysis of collected profile data.

Go Documentation