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

# Expvar

> Expvar metrics endpoint middleware for Go runtime metrics.

## Overview

The `expvar` middleware exposes Go's expvar metrics including runtime stats, memory usage, and custom variables.

Use it when you need:

* Go runtime metrics
* Memory usage monitoring
* Custom variable export

## Installation

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

## Quick Start

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

// Expose expvar endpoint
app.Get("/debug/vars", expvar.Handler())
```

## Examples

### Basic Setup

```go theme={null}
app.Get("/debug/vars", expvar.Handler())
```

### Custom Variables

```go theme={null}
import "expvar"

// Publish custom variable
var requests = expvar.NewInt("requests")

app.Use(func(next mizu.Handler) mizu.Handler {
    return func(c *mizu.Ctx) error {
        requests.Add(1)
        return next(c)
    }
})

app.Get("/debug/vars", expvar.Handler())
```

### With Auth Protection

```go theme={null}
debug := app.Group("/debug")
debug.Use(basicauth.New(adminCredentials))
debug.Get("/vars", expvar.Handler())
```

## Default Variables

| Variable   | Description            |
| ---------- | ---------------------- |
| `cmdline`  | Command line arguments |
| `memstats` | Memory statistics      |

## API Reference

### Functions

```go theme={null}
// Handler returns expvar HTTP handler
func Handler() mizu.Handler
```

## Response Format

```json theme={null}
{
    "cmdline": ["./myapp"],
    "memstats": {
        "Alloc": 1234567,
        "TotalAlloc": 9876543,
        "Sys": 12345678,
        ...
    },
    "requests": 42
}
```

## Technical Details

### Standard Library Integration

The middleware wraps Go's standard `expvar` package:

* Uses `expvar.Handler()` to serve the variables endpoint
* Exports all published variables as JSON
* Includes built-in `cmdline` and `memstats` variables

### Path Matching

* Only intercepts requests to the configured path (default: `/debug/vars`)
* All other requests pass through to the next handler
* Efficient path comparison using string equality

### Helper Functions

The package provides convenience wrappers for common expvar types:

* `NewInt(name)`: Creates and publishes an expvar.Int
* `NewFloat(name)`: Creates and publishes an expvar.Float
* `NewString(name)`: Creates and publishes an expvar.String
* `NewMap(name)`: Creates and publishes an expvar.Map

### Thread Safety

All expvar types are safe for concurrent use across goroutines.

## Best Practices

* Protect endpoint in production
* Use for debugging and monitoring
* Combine with custom metrics
* Don't expose sensitive data

## Testing

The middleware includes comprehensive test coverage. Key test cases:

| Test Case                    | Description            | Expected Behavior                  |
| ---------------------------- | ---------------------- | ---------------------------------- |
| `TestNew/expvar_endpoint`    | Request to /debug/vars | Returns 200 OK with expvar JSON    |
| `TestNew/non-expvar_path`    | Request to other paths | Passes through to next handler     |
| `TestWithOptions_CustomPath` | Custom expvar path     | Returns expvar data at custom path |
| `TestHelpers/NewInt`         | Integer counter helper | Creates and increments counter     |
| `TestHelpers/NewFloat`       | Float gauge helper     | Creates and sets float value       |
| `TestHelpers/NewString`      | String variable helper | Creates and sets string value      |
| `TestHelpers/NewMap`         | Map variable helper    | Creates map with key-value pairs   |
| `TestHelpers/Get`            | Get published variable | Returns published variable by name |
| `TestHelpers/Do`             | Iterate all variables  | Iterates over all expvars          |
| `TestJSON`                   | JSON export function   | Returns valid JSON object          |

## Related Middlewares

* [prometheus](/middlewares/prometheus) - Prometheus metrics
* [pprof](/middlewares/pprof) - Profiling
* [healthcheck](/middlewares/healthcheck) - Health checks