pprof

Documentation

Overview

Package pprof provides Go runtime profiling endpoints.

This package registers standard Go pprof handlers at configurable paths with auto-generated authentication for security.

Quick Start

Use the default configuration:

app := zh.New()
pp := pprof.New(app)
log.Printf("pprof credentials: %s / %s", pp.Auth.Username, pp.Auth.Password)

Access profiles at http://localhost:8080/debug/pprof/

Configuration

Customize endpoints or provide explicit credentials:

// Override specific fields (uses defaults for rest)
pprof.New(app, pprof.Config{
    Prefix: "/admin/pprof",
})

// Full custom config
pprof.New(app, pprof.Config{
    Prefix: "/debug/pprof",
    Auth: &pprof.AuthConfig{
        Username: "admin",
        Password: "secret",
    },
})

If Auth is nil, a secure password is auto-generated and available via pp.Auth. Set Auth to &AuthConfig{} with empty Username/Password to disable auth.

Available Endpoints

The following profiles are available (when enabled):

• /debug/pprof/ - Index page listing all profiles
• /debug/pprof/cmdline - Command line arguments
• /debug/pprof/profile - CPU profile (30 seconds by default)
• /debug/pprof/symbol - Symbol lookup
• /debug/pprof/trace - Execution trace
• /debug/pprof/heap - Heap profile
• /debug/pprof/goroutine - Goroutine profile
• /debug/pprof/threadcreate - Thread creation profile
• /debug/pprof/block - Block profile
• /debug/pprof/mutex - Mutex profile
• /debug/pprof/allocs - Allocs profile

Index

• Variables
• type AuthConfig
• type Config
• type PProf
  • func New(app *zh.Server, cfg ...Config) *PProf

Variables

var DefaultConfig = Config{
	Prefix:             "/debug/pprof",
	EnableIndex:        config.Bool(true),
	EnableCmdline:      config.Bool(true),
	EnableProfile:      config.Bool(true),
	EnableSymbol:       config.Bool(true),
	EnableTrace:        config.Bool(true),
	EnableHeap:         config.Bool(true),
	EnableGoroutine:    config.Bool(true),
	EnableThreadCreate: config.Bool(true),
	EnableBlock:        config.Bool(true),
	EnableMutex:        config.Bool(true),
	Auth:               nil,
	AllowedIPs:         []string{"127.0.0.1/8", "::1/128"},
}

DefaultConfig is the default pprof configuration. Modify this to change system-wide defaults.

Types

type AuthConfig

type AuthConfig struct {
	// Username for basic auth
	// Default: "pprof"
	Username string

	// Password for basic auth
	// Default: auto-generated secure random password
	Password string
}

AuthConfig holds basic authentication configuration

type Config

type Config struct {
	// Prefix is the base path for all pprof endpoints
	// Default: "/debug/pprof"
	Prefix string

	// EnableIndex enables the index page listing all profiles
	// nil = use default (true)
	// Default: nil
	EnableIndex *bool

	// EnableCmdline enables the cmdline endpoint
	// nil = use default (true)
	// Default: nil
	EnableCmdline *bool

	// EnableProfile enables the CPU profile endpoint
	// nil = use default (true)
	// Default: nil
	EnableProfile *bool

	// EnableSymbol enables the symbol endpoint
	// nil = use default (true)
	// Default: nil
	EnableSymbol *bool

	// EnableTrace enables the trace endpoint
	// nil = use default (true)
	// Default: nil
	EnableTrace *bool

	// EnableHeap enables the heap profile endpoint
	// nil = use default (true)
	// Default: nil
	EnableHeap *bool

	// EnableGoroutine enables the goroutine profile endpoint
	// nil = use default (true)
	// Default: nil
	EnableGoroutine *bool

	// EnableThreadCreate enables the threadcreate profile endpoint
	// nil = use default (true)
	// Default: nil
	EnableThreadCreate *bool

	// EnableBlock enables the block profile endpoint
	// nil = use default (true)
	// Default: nil
	EnableBlock *bool

	// EnableMutex enables the mutex profile endpoint
	// nil = use default (true)
	// Default: nil
	EnableMutex *bool

	// Auth is the basic auth configuration.
	// If nil, a random password will be generated.
	// Set to &AuthConfig{} with empty Username/Password to disable auth.
	// Default: nil (auto-generates secure password)
	Auth *AuthConfig

	// AllowedIPs restricts access to specific IPs or CIDR ranges.
	// Supports IPv4 and IPv6 addresses and CIDR notation (e.g., "10.0.0.0/8", "192.168.1.100").
	// Default: []string{"127.0.0.1/8", "::1/128"} (localhost only)
	// Set to empty slice to allow any IP (with auth still required).
	AllowedIPs []string
}

Config holds the pprof configuration

type PProf

type PProf struct {
	// Config is the configuration used
	Config Config

	// Auth contains the actual authentication config used (auto-generated or provided)
	Auth *AuthConfig
}

PProf holds the pprof configuration and runtime information

func New

func New(app *zh.Server, cfg ...Config) *PProf

New creates and registers all pprof endpoints with the provided configuration. Uses DefaultConfig if no config is provided, or merges user config with defaults. Returns a PProf struct containing the configuration and actual auth credentials used.

See package documentation for usage examples.