Skip to main content
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

VariableDefaultDescription
METRICS_ENABLEDfalseEnable/disable metrics collection
METRICS_ENDPOINT/metricsHTTP 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