Skip to content

Configuration Overview

Prometheus Proxy uses the Typesafe Config library for configuration. Values are evaluated in this precedence order (highest first):

Configuration precedence (highest to lowest):

1. CLI options:       --port 9090
2. System properties: -Dproxy.http.port=9090
3. Environment vars:  PROXY_PORT=9090
4. Config file:       proxy.http.port = 9090
5. Default values:    8080

Configuration Formats

Typesafe Config supports three formats:

Format Extension Description
HOCON .conf Human-friendly JSON superset (recommended)
JSON .json Standard JSON format
Properties .properties Java properties format

Loading Configuration

From a Local File

java -jar prometheus-agent.jar --config /etc/prometheus-proxy/agent.conf
java -jar prometheus-proxy.jar --config /etc/prometheus-proxy/proxy.conf

From a URL

# Load configuration from a URL:
java -jar prometheus-agent.jar \
  --config https://raw.githubusercontent.com/pambrose/prometheus-proxy/master/examples/simple.conf

# Or from a local file:
java -jar prometheus-agent.jar --config /etc/prometheus-proxy/agent.conf

Dynamic Properties

Override any configuration value using -D flags:

java -jar prometheus-proxy.jar -Dproxy.http.port=9090 -Dproxy.admin.enabled=true
java -jar prometheus-agent.jar -Dagent.proxy.hostname=myproxy.com --config agent.conf

Environment Variables

Common environment variables:

Common environment variables:

Proxy:
  PROXY_CONFIG             - Config file path or URL
  PROXY_PORT               - HTTP listen port (default: 8080)
  AGENT_PORT               - gRPC listen port (default: 50051)
  ADMIN_ENABLED            - Enable admin endpoints
  METRICS_ENABLED          - Enable metrics collection
  SD_ENABLED               - Enable service discovery

Agent:
  AGENT_CONFIG             - Config file path or URL (required)
  PROXY_HOSTNAME           - Proxy hostname
  AGENT_NAME               - Agent name for metrics
  ADMIN_ENABLED            - Enable admin endpoints
  METRICS_ENABLED          - Enable metrics collection
  MAX_CONCURRENT_CLIENTS   - Parallel scrape limit

See the CLI Reference for the complete list.

HOCON Basics

HOCON (Human-Optimized Config Object Notation) is a superset of JSON:

# Comments start with # or //
agent {
  // Nested keys with dot notation
  proxy.hostname = "proxy-host.example.com"
  proxy.port = 50051

  // Arrays use brackets
  pathConfigs: [
    {
      name: "My App"
      path: my_app_metrics
      url: "http://localhost:9100/metrics"
    }
  ]

  // Reference environment variables
  name = ${?AGENT_NAME}
}

Key HOCON features:

  • Comments with # or //
  • Unquoted strings for simple values
  • Environment variable substitution with ${?VAR_NAME}
  • Dot notation for nested paths (proxy.hostname)
  • Merging and includes (include "other.conf")

Configuration Reference

For the complete configuration schema, see the reference file: config/config.conf

Next Steps