Prometheus Metrics

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

Quick Start

Disabled by Default

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

export METRICS_ENABLED=true
./bin/aurora
# Metrics available at http://your-aurora-host/metrics
 

Disable Metrics

Option 1: Environment Variable

export METRICS_ENABLED=false
./bin/aurora
 

Option 2: .env file

echo "METRICS_ENABLED=false" >> .env
./bin/aurora
 

Option 3: config.yaml

metrics:
  enabled: false
 

Custom Metrics Endpoint

Change the default /metrics path:

export METRICS_ENDPOINT=/internal/prometheus
./bin/aurora
 

Configuration Options

Via Environment Variables

Via config.yaml

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

PORT=8080
AURORA_MASTER_KEY=<your-aurora-master-key>
METRICS_ENABLED=true
METRICS_ENDPOINT=/metrics
OPENAI_API_KEY=<your-openai-api-key>
 

Development Setup (Metrics Disabled)

.env

PORT=8080
METRICS_ENABLED=false
OPENAI_API_KEY=<your-openai-api-key>
 

Custom Endpoint for Internal Monitoring

config.yaml

server:
  port: "8080"
  master_key: "${AURORA_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:

{ "level": "INFO", "msg": "prometheus metrics enabled", "endpoint": "/metrics" }
 

Metrics Disabled:

{ "level": "INFO", "msg": "prometheus metrics disabled" }
 

Test Metrics Endpoint

When Enabled:

curl http://your-aurora-host/metrics
# Returns Prometheus metrics in text format
 

When Disabled:

curl http://your-aurora-host/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:

   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:

   location /metrics {
       auth_basic "Metrics";
       auth_basic_user_file /etc/nginx/.htpasswd;
       proxy_pass http://aurora:8080/metrics;
   }
 

Prometheus Configuration

Scrape Config

prometheus.yml

scrape_configs:
  - job_name: "aurora"
    static_configs:
      - targets: ["your-aurora-host"]
    metrics_path: "/metrics" # Or your custom path
    scrape_interval: 15s
    scrape_timeout: 10s
 

With Custom Endpoint

scrape_configs:
  - job_name: "aurora"
    static_configs:
      - targets: ["your-aurora-host"]
    metrics_path: "/internal/prometheus" # Custom path
    scrape_interval: 15s
 

Troubleshooting

Metrics Endpoint Returns 404

Cause: metrics are disabled (the default).

Solution:

# Check configuration
echo $METRICS_ENABLED  # "true" enables; empty or "false" disables
 
# Enable metrics
export METRICS_ENABLED=true
./bin/aurora
 

No Metrics Data Appearing

Cause: no requests have been made yet.

Solution: make some requests to generate metrics:

curl -X POST http://your-aurora-host/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://your-aurora-host/metrics | grep aurora_requests_total
 

Custom Endpoint Not Working

Cause: the endpoint must start with /.

Incorrect:

export METRICS_ENDPOINT=metrics  # Missing leading slash
 

Correct:

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 � full environment variable reference
• config.yaml � YAML configuration reference