Skip to main content

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

Quick Start

Configuration

Endpoints

Examples

Basic Usage

Custom Prefix

Protected Pprof

Conditional Pprof

IP Restricted

Using the Profiles

CPU Profile

Capture a 30-second CPU profile:
Or with a custom duration:

Heap Profile

Goroutine Dump

Execution Trace

Memory Allocations

Common Pprof Commands

Inside go tool pprof:

API Reference

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:
  1. Path Matching: The middleware checks if the incoming request path matches the configured prefix (default: /debug/pprof)
  2. Pass-through: If the path doesn’t match, the request is passed to the next middleware in the chain
  3. 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

Security Warning

Pprof endpoints can expose sensitive information about your application. In production:
  1. Use authentication
  2. Restrict by IP address
  3. Use a separate admin port
  4. 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 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)