Overview
Thepprof middleware exposes Go’s built-in profiling endpoints for performance analysis and debugging. It integrates the standard net/http/pprof package with Mizu.
Installation
Quick Start
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
Prefix | string | "/debug/pprof" | URL prefix for pprof endpoints |
Endpoints
| Path | Description |
|---|---|
/debug/pprof/ | Index page with all profiles |
/debug/pprof/cmdline | Command line arguments |
/debug/pprof/profile | CPU profile (30s default) |
/debug/pprof/symbol | Symbol lookup |
/debug/pprof/trace | Execution trace |
/debug/pprof/heap | Heap memory profile |
/debug/pprof/goroutine | Goroutine stack traces |
/debug/pprof/block | Blocking profile |
/debug/pprof/mutex | Mutex contention profile |
/debug/pprof/allocs | Memory allocations |
/debug/pprof/threadcreate | Thread creation profile |
Examples
Basic Usage
Custom Prefix
Protected Pprof
Conditional Pprof
IP Restricted
Using the Profiles
CPU Profile
Capture a 30-second CPU profile:Heap Profile
Goroutine Dump
Execution Trace
Memory Allocations
Common Pprof Commands
Insidego tool pprof:
API Reference
Technical Details
The pprof middleware integrates Go’s standardnet/http/pprof package with Mizu’s middleware system. Here’s how it works:
Implementation Architecture
The middleware uses a path-based routing strategy to handle different profiling endpoints:- Path Matching: The middleware checks if the incoming request path matches the configured prefix (default:
/debug/pprof) - Pass-through: If the path doesn’t match, the request is passed to the next middleware in the chain
- Subpath Routing: For matching paths, the middleware extracts the subpath and routes to the appropriate pprof handler
Handler Routing Logic
- Index Page (
/or empty subpath): Displays the pprof index usingpprof.Index() - Special Handlers: Four endpoints have dedicated handlers:
/cmdline: Command line invocation usingpprof.Cmdline()/profile: CPU profiling usingpprof.Profile()/symbol: Symbol lookup usingpprof.Symbol()/trace: Execution tracing usingpprof.Trace()
- Named Profiles: All other subpaths are treated as named profiles (heap, goroutine, block, mutex, allocs, threadcreate) and handled by
pprof.Handler(name)
Prefix Normalization
The middleware automatically normalizes the prefix by removing trailing slashes to ensure consistent path matching regardless of how the prefix is configured.Request Flow
Security Warning
Pprof endpoints can expose sensitive information about your application. In production:- Use authentication
- Restrict by IP address
- Use a separate admin port
- Or disable entirely
Best Practices
- Never expose pprof publicly in production
- Use authentication for protected access
- Enable only when debugging is needed
- Use execution traces sparingly (high overhead)
- CPU profiles should be short (30-60 seconds)
Testing
The pprof middleware includes comprehensive test coverage to ensure all endpoints and configurations work correctly:| Test Case | Description | Expected Behavior |
|---|---|---|
TestNew/index page | Tests the pprof index page at /debug/pprof/ | Returns HTTP 200 and contains “pprof” in response body |
TestNew/cmdline | Tests the command line endpoint | Returns HTTP 200 with command line arguments |
TestNew/symbol | Tests the symbol lookup endpoint | Returns HTTP 200 for symbol queries |
TestNew/heap profile | Tests the heap memory profile endpoint | Returns HTTP 200 with heap profile data |
TestNew/goroutine profile | Tests the goroutine stack traces endpoint | Returns HTTP 200 with goroutine information |
TestNew/non-pprof path | Tests that non-pprof paths pass through to next handler | Returns “home” text from the application route |
TestWithOptions_CustomPrefix | Tests custom prefix configuration (/profiling) | Returns HTTP 200 when accessing index at custom prefix |
TestWithOptions_PrefixWithTrailingSlash | Tests prefix normalization with trailing slash | Returns HTTP 200, correctly handles trailing slash in prefix |
Test Coverage
The test suite validates:- All major pprof endpoints (index, cmdline, symbol, heap, goroutine)
- Middleware pass-through for non-matching paths
- Custom prefix configuration
- Prefix normalization (trailing slash handling)