> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-docs-aws-gateway-benchmark.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prometheus Metrics

> Configure and scrape GoModel's Prometheus metrics endpoint.

<Warning>
  Prometheus support is **experimental**. The metric names, labels, and
  configuration surface may change without notice. Pin to a specific GoModel
  version if you depend on a stable schema.
</Warning>

This guide explains how to configure the experimental Prometheus metrics
endpoint in GoModel.

## Quick Start

### Disabled by Default

Metrics are **disabled by default**. To enable metrics collection, set
`METRICS_ENABLED=true` and start GoModel:

<CodeGroup>
  ```bash Docker (.env file) theme={null}
  # Add METRICS_ENABLED=true to your .env file, then:
  docker run --rm -p 8080:8080 --env-file .env enterpilot/gomodel
  # Metrics available at http://localhost:8080/metrics
  ```

  ```bash Docker (inline -e) theme={null}
  docker run --rm -p 8080:8080 \
    -e METRICS_ENABLED=true \
    enterpilot/gomodel
  # Metrics available at http://localhost:8080/metrics
  ```

  ```bash Binary (make build) theme={null}
  # Requires Go 1.26.4+; produces bin/gomodel.
  make build

  export METRICS_ENABLED=true
  ./bin/gomodel
  # Metrics available at http://localhost:8080/metrics
  ```
</CodeGroup>

<Note>
  The rest of this guide shows just the variable being set. Apply it via
  whichever launcher you picked above — `.env` plus `--env-file`, an inline
  `-e` flag, or `export` before `./bin/gomodel` — and restart GoModel.
</Note>

### Disable Metrics

**Option 1: Environment Variable**

```bash theme={null}
METRICS_ENABLED=false
```

**Option 2: .env file**

```bash theme={null}
echo "METRICS_ENABLED=false" >> .env
```

**Option 3: config.yaml**

```yaml theme={null}
metrics:
  enabled: false
```

### Custom Metrics Endpoint

Change the default `/metrics` path:

```bash theme={null}
METRICS_ENABLED=true
METRICS_ENDPOINT=/internal/prometheus
```

## Configuration Options

### Via Environment Variables

| Variable           | Default    | Description                       |
| ------------------ | ---------- | --------------------------------- |
| `METRICS_ENABLED`  | `false`    | Enable/disable metrics collection |
| `METRICS_ENDPOINT` | `/metrics` | HTTP path for metrics endpoint    |

### Via config.yaml

```yaml theme={null}
metrics:
  # Enable or disable Prometheus metrics collection
  # When disabled, no metrics are collected and the endpoint returns 404
  enabled: true

  # HTTP endpoint path where metrics are exposed
  endpoint: "/metrics"
```

## Examples

### Production Setup (Metrics Enabled)

**.env**

```bash theme={null}
PORT=8080
GOMODEL_MASTER_KEY=your-secret-key
METRICS_ENABLED=true
METRICS_ENDPOINT=/metrics
OPENAI_API_KEY=sk-...
```

### Development Setup (Metrics Disabled)

**.env**

```bash theme={null}
PORT=8080
METRICS_ENABLED=false
OPENAI_API_KEY=sk-...
```

### Custom Endpoint for Internal Monitoring

**config.yaml**

```yaml theme={null}
server:
  port: "8080"
  master_key: "${GOMODEL_MASTER_KEY}"

metrics:
  enabled: true
  endpoint: "/internal/prometheus" # Custom path

providers:
  openai:
    type: "openai"
    api_key: "${OPENAI_API_KEY}"
```

## Verification

### Check if Metrics are Enabled

Start the server and look for log messages:

**Metrics Enabled:**

```json theme={null}
{ "level": "INFO", "msg": "prometheus metrics enabled", "endpoint": "/metrics" }
```

**Metrics Disabled:**

```json theme={null}
{ "level": "INFO", "msg": "prometheus metrics disabled" }
```

### Test Metrics Endpoint

**When Enabled:**

```bash theme={null}
curl http://localhost:8080/metrics
# Returns Prometheus metrics in text format
```

**When Disabled:**

```bash theme={null}
curl http://localhost:8080/metrics
# Returns 404 Not Found
```

## Performance Impact

### Metrics Enabled

* Minimal overhead: \~100ns per request for hook execution
* Memory: \~1MB for metric storage (depends on cardinality)
* CPU: Negligible impact (`<0.1%` in benchmarks)

### Metrics Disabled

* **Zero overhead**: no hooks registered, no collection
* The metrics library is still linked but inactive
* Recommended for maximum performance in non-production environments

## Security Considerations

### Exposing the Metrics Endpoint

The `/metrics` endpoint is protected by master key authentication when a master
key is configured, just like other HTTP endpoints. If no master key is
configured, the endpoint is accessible without authentication, which allows
Prometheus to scrape metrics without credentials.

If you need to protect the metrics endpoint further:

1. **Use a custom internal path:**

   ```yaml theme={null}
   metrics:
     endpoint: "/internal/prometheus" # Harder to guess
   ```

2. **Use network-level security:**
   * Configure firewall rules to allow only the Prometheus server
   * Use a private network for metrics collection
   * Deploy Prometheus in the same VPC/network

3. **Reverse proxy with authentication:**

   ```nginx theme={null}
   location /metrics {
       auth_basic "Metrics";
       auth_basic_user_file /etc/nginx/.htpasswd;
       proxy_pass http://gomodel:8080/metrics;
   }
   ```

## Prometheus Configuration

### Scrape Config

**prometheus.yml**

```yaml theme={null}
scrape_configs:
  - job_name: "gomodel"
    static_configs:
      - targets: ["localhost:8080"]
    metrics_path: "/metrics" # Or your custom path
    scrape_interval: 15s
    scrape_timeout: 10s
```

### With Custom Endpoint

```yaml theme={null}
scrape_configs:
  - job_name: "gomodel"
    static_configs:
      - targets: ["localhost:8080"]
    metrics_path: "/internal/prometheus" # Custom path
    scrape_interval: 15s
```

## Troubleshooting

### Metrics Endpoint Returns 404

**Cause:** metrics are disabled (the default).

**Solution:**

```bash theme={null}
# Check configuration
echo $METRICS_ENABLED  # "true" enables; empty or "false" disables
```

Set `METRICS_ENABLED=true` via your `.env` file, an inline `-e METRICS_ENABLED=true`
flag, or `export METRICS_ENABLED=true` (see the [Quick Start](#disabled-by-default)
for the three launch forms), then restart GoModel.

### No Metrics Data Appearing

**Cause:** no requests have been made yet.

**Solution:** make some requests to generate metrics:

```bash theme={null}
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-master-key" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]}'

# Then check metrics
curl http://localhost:8080/metrics | grep gomodel_requests_total
```

### Custom Endpoint Not Working

**Cause:** the endpoint must start with `/`.

**Incorrect:**

```bash theme={null}
export METRICS_ENDPOINT=metrics  # Missing leading slash
```

**Correct:**

```bash theme={null}
export METRICS_ENDPOINT=/metrics  # Has leading slash
```

## Best Practices

### Development

* **Disable metrics** for faster startup and reduced noise
* Enable only when testing observability features

### Staging

* **Enable metrics** to test the monitoring setup
* Use a custom endpoint if needed for security

### Production

* **Enable metrics** for full observability
* Set up Prometheus alerting
* Use Grafana dashboards for visualization
* Consider a custom endpoint for security
* Monitor metric cardinality to avoid explosion

## See Also

* [Configuration](/advanced/configuration) — full environment variable reference
* [config.yaml](/advanced/config-yaml) — YAML configuration reference