Prometheus Metrics

Configure and scrape GoModel’s Prometheus metrics endpoint.

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.

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:

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

Disable Metrics

Option 1: Environment Variable

export METRICS_ENABLED=false
./bin/gomodel

Option 2: .env file

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

Option 3: config.yaml

metrics:
  enabled: false

Custom Metrics Endpoint

Change the default /metrics path:

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

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

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
GOMODEL_MASTER_KEY=your-secret-key
METRICS_ENABLED=true
METRICS_ENDPOINT=/metrics
OPENAI_API_KEY=sk-...

Development Setup (Metrics Disabled)

.env

PORT=8080
METRICS_ENABLED=false
OPENAI_API_KEY=sk-...

Custom Endpoint for Internal Monitoring

config.yaml

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:

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

Metrics Disabled:

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

Test Metrics Endpoint

When Enabled:

curl http://localhost:8080/metrics
# Returns Prometheus metrics in text format

When Disabled:

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:

   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://gomodel:8080/metrics;
   }
   

Prometheus Configuration

Scrape Config

prometheus.yml

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

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:

# Check configuration
echo $METRICS_ENABLED  # "true" enables; empty or "false" disables

# Enable metrics
export METRICS_ENABLED=true
./bin/gomodel

No Metrics Data Appearing

Cause: no requests have been made yet.

Solution: make some requests to generate metrics:

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:

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