> ## 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.

# Pprof

> Profiling endpoints middleware for performance analysis.

## 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

```go theme={null}
import "github.com/go-mizu/mizu/middlewares/pprof"
```

## Quick Start

```go theme={null}
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

```go theme={null}
app := mizu.New()

// Add pprof middleware
app.Use(pprof.New())

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

### Custom Prefix

```go theme={null}
app.Use(pprof.WithOptions(pprof.Options{
    Prefix: "/internal/profiling",
}))

// Access at http://localhost:8080/internal/profiling/
```

### Protected Pprof

```go theme={null}
// 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

```go theme={null}
// Only enable in development
if os.Getenv("ENV") == "development" {
    app.Use(pprof.New())
}
```

### IP Restricted

```go theme={null}
// 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:

```bash theme={null}
go tool pprof http://localhost:8080/debug/pprof/profile
```

Or with a custom duration:

```bash theme={null}
curl "http://localhost:8080/debug/pprof/profile?seconds=60" > cpu.prof
go tool pprof cpu.prof
```

### Heap Profile

```bash theme={null}
go tool pprof http://localhost:8080/debug/pprof/heap
```

### Goroutine Dump

```bash theme={null}
curl http://localhost:8080/debug/pprof/goroutine?debug=2
```

### Execution Trace

```bash theme={null}
curl "http://localhost:8080/debug/pprof/trace?seconds=5" > trace.out
go tool trace trace.out
```

### Memory Allocations

```bash theme={null}
go tool pprof http://localhost:8080/debug/pprof/allocs
```

## Common Pprof Commands

Inside `go tool pprof`:

```bash theme={null}
# Top functions by CPU/memory
top 10

# View call graph
web

# List function source
list <function_name>

# Show flamegraph (web view)
web
```

## API Reference

```go theme={null}
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:

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

```
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:

1. Use authentication
2. Restrict by IP address
3. Use a separate admin port
4. Or disable entirely

```go theme={null}
// 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)

## Related Middlewares

* [basicauth](/middlewares/basicauth) - Basic authentication
* [ipfilter](/middlewares/ipfilter) - IP filtering
* [timing](/middlewares/timing) - Performance timing