Documentation Index
Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The pprof middleware exposes Go’s built-in profiling endpoints for performance analysis and debugging. It integrates the standard net/http/pprof package with Mizu.
Installation
import "github.com/go-mizu/mizu/middlewares/pprof"
Quick Start
app := mizu.New()
// Expose pprof endpoints at /debug/pprof
app.Use(pprof.New())
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
app := mizu.New()
// Add pprof middleware
app.Use(pprof.New())
// Access at http://localhost:8080/debug/pprof/
Custom Prefix
app.Use(pprof.WithOptions(pprof.Options{
Prefix: "/internal/profiling",
}))
// Access at http://localhost:8080/internal/profiling/
Protected Pprof
// Create a sub-app for admin routes
admin := app.Group("/admin")
// Add authentication
admin.Use(basicauth.New(basicauth.Options{
Users: map[string]string{
"admin": "secret",
},
}))
// Add pprof to admin group
admin.Use(pprof.WithOptions(pprof.Options{
Prefix: "/admin/pprof",
}))
Conditional Pprof
// Only enable in development
if os.Getenv("ENV") == "development" {
app.Use(pprof.New())
}
IP Restricted
// Only allow from localhost
app.Use(ipfilter.WithOptions(ipfilter.Options{
Whitelist: []string{"127.0.0.1", "::1"},
PathPrefix: "/debug/pprof",
}))
app.Use(pprof.New())
Using the Profiles
CPU Profile
Capture a 30-second CPU profile:
go tool pprof http://localhost:8080/debug/pprof/profile
Or with a custom duration:
curl "http://localhost:8080/debug/pprof/profile?seconds=60" > cpu.prof
go tool pprof cpu.prof
Heap Profile
go tool pprof http://localhost:8080/debug/pprof/heap
Goroutine Dump
curl http://localhost:8080/debug/pprof/goroutine?debug=2
Execution Trace
curl "http://localhost:8080/debug/pprof/trace?seconds=5" > trace.out
go tool trace trace.out
Memory Allocations
go tool pprof http://localhost:8080/debug/pprof/allocs
Common Pprof Commands
Inside go tool pprof:
# Top functions by CPU/memory
top 10
# View call graph
web
# List function source
list <function_name>
# Show flamegraph (web view)
web
API Reference
func New() mizu.Middleware
func WithOptions(opts Options) mizu.Middleware
Technical Details
The pprof middleware integrates Go’s standard net/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 using pprof.Index()
- Special Handlers: Four endpoints have dedicated handlers:
/cmdline: Command line invocation using pprof.Cmdline()
/profile: CPU profiling using pprof.Profile()
/symbol: Symbol lookup using pprof.Symbol()
/trace: Execution tracing using pprof.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
Request -> Path Check -> Match Prefix? -> No -> Next Middleware
|
Yes
|
Extract Subpath -> Route to Handler -> Serve Profile
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
// Production-safe setup
if os.Getenv("ENABLE_PPROF") == "true" {
app.Use(ipfilter.WithOptions(ipfilter.Options{
Whitelist: []string{"10.0.0.0/8"},
PathPrefix: "/debug/pprof",
}))
app.Use(pprof.New())
}
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)