Skip to content

Quick Start

Requirements: Java 17 or newer

Installation

Download the latest proxy and agent JAR files from the GitHub Releases page.

git clone https://github.com/pambrose/prometheus-proxy.git
cd prometheus-proxy
./gradlew shadowJar

JARs are generated in build/libs/:

  • build/libs/prometheus-proxy.jar
  • build/libs/prometheus-agent.jar

Multi-platform images (amd64, arm64, s390x) are available on Docker Hub:

docker pull pambrose/prometheus-proxy:3.1.0
docker pull pambrose/prometheus-agent:3.1.0

Start the Proxy

The proxy runs outside the firewall alongside your Prometheus server.

java -jar prometheus-proxy.jar

The proxy starts with default settings:

  • HTTP scrape port: 8080
  • gRPC agent port: 50051
docker run --rm -p 8080:8080 -p 50051:50051 \
  pambrose/prometheus-proxy:3.1.0

Start the Agent

The agent runs inside the firewall with your monitored services. It needs a configuration file that specifies which metrics endpoints to expose.

Create an Agent Config

Create a file called agent.conf:

agent {
  proxy.hostname = "proxy-host.example.com"

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

Each entry in pathConfigs maps:

  • path -- the URL path on the proxy that Prometheus will scrape
  • url -- the actual metrics endpoint the agent will fetch from

Start the Agent

java -jar prometheus-agent.jar --config agent.conf

Or specify the proxy hostname on the command line:

java -jar prometheus-agent.jar \
  --proxy proxy-host.example.com \
  --config agent.conf

docker run --rm \
  --mount type=bind,source="$(pwd)"/agent.conf,target=/app/agent.conf \
  --env AGENT_CONFIG=agent.conf \
  --env PROXY_HOSTNAME=proxy-host.example.com \
  pambrose/prometheus-agent:3.1.0

The agent can load configuration from a URL:

java -jar prometheus-agent.jar \
  --proxy proxy-host.example.com \
  --config https://example.com/configs/agent.conf

Configure Prometheus

Add scrape targets pointing to the proxy:

scrape_configs:
  - job_name: 'my-app'
    metrics_path: '/my_app_metrics'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

The metrics_path must match the path value in the agent's pathConfigs.

Verify

Check that metrics are flowing through the proxy:

curl -s http://proxy-host.example.com:8080/my_app_metrics | head

Multiple Endpoints

An agent can serve multiple metrics endpoints. Each gets its own path on the proxy:

agent {
  pathConfigs: [
    {
      name: "App1 metrics"
      path: app1_metrics
      url: "http://app1.local:9100/metrics"
    },
    {
      name: "App2 metrics"
      path: app2_metrics
      url: "http://app2.local:9100/metrics"
    },
    {
      name: "App3 metrics"
      path: app3_metrics
      url: "http://app3.local:9100/metrics"
    }
  ]
}

The corresponding Prometheus configuration:

scrape_configs:
  - job_name: 'app1'
    metrics_path: '/app1_metrics'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

  - job_name: 'app2'
    metrics_path: '/app2_metrics'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

  - job_name: 'app3'
    metrics_path: '/app3_metrics'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

Authentication

When Prometheus scrape configs include basic_auth or bearer_token, the proxy forwards the Authorization header to the agent, which includes it when fetching from the target endpoint.

scrape_configs:
  # Bearer token authentication
  - job_name: 'app1'
    metrics_path: '/app1_metrics'
    bearer_token: 'eyJhbGciOiJIUzI1NiIs...'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

  # Basic auth
  - job_name: 'app2'
    metrics_path: '/app2_metrics'
    basic_auth:
      username: 'user'
      password: 's3cr3t'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

  # No auth
  - job_name: 'app3'
    metrics_path: '/app3_metrics'
    static_configs:
      - targets: ['proxy-host.example.com:8080']

Enable TLS for auth forwarding

Without TLS, authorization headers are transmitted in plaintext between proxy and agent. See Security for TLS setup instructions.

Next Steps

  • Agent Configuration

    All agent settings including path configs, HTTP client, and scrape options

    Agent Configuration

  • Proxy Configuration

    All proxy settings including HTTP service, gRPC, and service discovery

    Proxy Configuration

  • Docker Usage

    Production Docker setups and docker-compose examples

    Docker

  • Security & TLS

    Secure the proxy-agent connection with TLS and mutual authentication

    Security