Example Configs

The repository ships a set of ready-to-run config files under examples/. Each is shown below verbatim. For the full set of options see Agent Configuration and Proxy Configuration.

Precedence

Config files are the lowest-precedence source: CLI args → env vars → config file → built-in defaults. See the CLI Reference.

Self-monitoring — `simple.conf`

Enables admin and metrics on both components and points the agent at the proxy's and agent's own /metrics endpoints, so the proxy and agent monitor themselves. A good first run on a single host.

proxy {
  admin.debugEnabled = false

  admin.enabled: true
  metrics.enabled: true

  http.requestLoggingEnabled: true
}

agent {
  proxy.hostname = localhost
  admin.enabled: true
  metrics.enabled: true

  pathConfigs: [
    {
      name: "Proxy metrics"
      path: proxy_metrics
      labels: "{\"key1\": \"value1\", \"key2\": 2}"
      url: "http://localhost:8082/metrics"
      //url: "http://"${?HOSTNAME}":8082/metrics"
    }
    {
      name: "Agent metrics"
      path: agent_metrics
      labels: "{\"key3\": \"value3\", \"key4\": 4}"
      url: "http://localhost:8083/metrics"
      //url: "http://"${?HOSTNAME}":8083/metrics"
    }
  ]
}

Run it with:

java -jar prometheus-proxy.jar --config examples/simple.conf
java -jar prometheus-agent.jar  --config examples/simple.conf

Multiple application endpoints — `myapps.conf`

Three application endpoints, each on its own proxy path and tagged with custom labels. This is the typical shape of a real agent config.

agent {
  pathConfigs: [
    {
      name: "App1 metrics"
      path: app1_metrics
      labels: "{\"key1\": \"value1\", \"key2\": 2}"
      url: "http://app1.local:9100/metrics"
    },
    {
      name: "App2 metrics"
      path: app2_metrics
      labels: "{\"key3\": \"value3\", \"key4\": 4}"
      url: "http://app2.local:9100/metrics"
    },
    {
      name: "App3 metrics"
      path: app3_metrics
      labels: "{\"key5\": \"value5\", \"key6\": 6}"
      url: "http://app3.local:9100/metrics"
    }
  ]
}

Prometheus then scrapes /app1_metrics, /app2_metrics, and /app3_metrics from the proxy. See the Quick Start.

Metric filtering — `agent-filters.conf`

Drops whole metric families at the agent, before the payload is gzipped, chunked, and sent across the WAN. Filters live in a top-level agent.filters list keyed by path rather than nested inside pathConfigs, so a filter applies to that path whether it was registered statically or by dynamic discovery.

agent {
  pathConfigs: [
    {
      name: "app1"
      path: "app1_metrics"
      url: "http://app1:9090/metrics"
    }
  ]

  // Drop Go runtime GC metrics for app1 before they cross the WAN.
  // Regexes are fully anchored, matching Prometheus relabel_config semantics:
  // "go_" matches nothing; "go_.*" matches go_gc_duration_seconds.
  filters: [
    {
      path: "app1_metrics"
      metricNameAllow: []
      metricNameDeny: [ "go_gc_.*", "go_memstats_.*" ]
    }
  ]
}

Regexes are fully anchored, matching Prometheus relabel_config semantics: go_ matches nothing, while go_.* matches go_gc_duration_seconds. See Metric Filtering.

Dynamic discovery targets — `discovery-targets.conf`

Unlike every other file on this page, this one is not passed to --config. It is the targets file an agent watches when dynamic target discovery is enabled, so it has a top-level paths list and no agent { } wrapper. The agent re-reads it every reconcileIntervalSecs and registers, unregisters, or re-registers paths to match — no restart, and paths that did not change keep scraping.

// Dynamic target discovery file, referenced by agent.discovery.file.path.
//
// This is a standalone targets file, NOT an agent config -- there is no `agent { }` wrapper here.
// Point an agent at it from that agent's own config:
//
//   agent {
//     discovery {
//       enabled = true
//       file.path = "examples/discovery-targets.conf"
//       reconcileIntervalSecs = 30
//     }
//   }
//
// The agent re-reads this file every reconcileIntervalSecs and registers, unregisters, or
// re-registers paths so the live set matches it -- no restart, and paths that did not change keep
// scraping. Static agent.pathConfigs entries are a baseline reconciliation never touches; if a path
// here collides with a static one, the static entry wins and the collision is logged.
//
// JSON is equally valid, since HOCON is a JSON superset -- convenient if this file is generated.

paths = [
  // Only `path` and `url` are required: `name` defaults to `path`, `labels` defaults to "{}".
  { path = "app1_metrics", url = "http://app1.local:9100/metrics" }

  // Full form. `labels` is a JSON *string*, not a nested object; HOCON triple quotes avoid the
  // backslash escaping used in the pathConfigs examples.
  {
    name   = "App2 metrics"
    path   = "app2_metrics"
    url    = "http://app2.local:9100/metrics"
    labels = """{"env": "prod", "team": "platform"}"""
  }
]

// `path` must be a single segment: the proxy serves each registered path at /<path>, so a
// multi-segment value like "app/metrics" is rejected at registration. Use "app_metrics".

// Substitutions are resolved, so a generated or environment-driven file can avoid repetition.
// The ${?VAR} form is optional: it overrides the preceding value when set and falls back to it
// when unset. Uncomment to try:
//
//   host = "app3.local"
//   port = 9100
//   port = ${?METRICS_PORT}
//
//   paths = [
//     { path = "app3_metrics", url = "http://"${host}":"${port}"/metrics" }
//   ]

// Removing every discovered path is spelled `paths = []` -- an empty-but-valid file is a real
// instruction and is honored. Deleting or corrupting this file is NOT: an unreadable file is
// treated as a failed read, so the agent logs a warning, skips the tick, and keeps its
// last-known-good set rather than tearing every target down on a bad write.

An agent points at it from its own config:

agent {
  discovery {
    enabled = true
    file.path = "examples/discovery-targets.conf"
    reconcileIntervalSecs = 30
  }
}

Prometheus federation — `federate.conf`

Pulls metrics from an existing Prometheus server through its /federate endpoint, exposing them on a proxy path. See Prometheus Federation.

agent {
  pathConfigs: [
    {
      name: "Federate metrics"
      path: federate_metrics
      url: "http://prometheus:9090/federate?match[]={job=~'.*'}"
    },
    {
      name: "Agent metrics"
      path: agent_metrics
      url: "http://localhost:8083/metrics"
    }
  ]
}

Server-only TLS — `tls-no-mutual-auth.conf`

Encrypts the gRPC channel with a server certificate; the agent verifies the proxy but does not present a client certificate. Note the non-default agent port 50440 and the overrideAuthority used to match the test fixture's SAN.

proxy {

  agent.port = 50440

  tls {
    certChainFilePath = "testing/certs/server1.pem"       // Server certificate chain file path
    privateKeyFilePath = "testing/certs/server1.key"      // Server private key file path
    trustCertCollectionFilePath = ""                      // Trust certificate collection file path
  }
}

agent {

  proxy {
    hostname = "localhost"                                // Proxy hostname
    port = 50440                                          // Proxy port
  }

  http {
    enableTrustAllX509Certificates = true
  }

  // Only trustCertCollectionFilePath is required on the client with TLS (no mutual authentication)
  tls {
    overrideAuthority = "foo.test.google.fr"              // Override authority (for testing only)
    certChainFilePath = ""                                // Client certificate chain file path
    privateKeyFilePath = ""                               // Client private key file path
    trustCertCollectionFilePath = "testing/certs/ca.pem"  // Trust certificate collection file path
  }
}

Mutual TLS — `tls-with-mutual-auth.conf`

Both sides present certificates: the proxy trusts the client CA and the agent supplies its own certChainFilePath / privateKeyFilePath. This is the recommended production posture.

proxy {

  agent.port = 50440

  tls {
    certChainFilePath = "testing/certs/server1.pem"       // Server certificate chain file path
    privateKeyFilePath = "testing/certs/server1.key"      // Server private key file path
    trustCertCollectionFilePath = "testing/certs/ca.pem"  // Trust certificate collection file path
  }
}

agent {

  proxy {
    hostname = "localhost"                                // Proxy hostname
    port = 50440                                          // Proxy port
  }

  // Only trustCertCollectionFilePath is required on the client with TLS (with mutual authentication)
  tls {
    overrideAuthority = "foo.test.google.fr"              // Override authority (for testing only)
    certChainFilePath = "testing/certs/client.pem"        // Client certificate chain file path
    privateKeyFilePath = "testing/certs/client.key"       // Client private key file path
    trustCertCollectionFilePath = "testing/certs/ca.pem"  // Trust certificate collection file path
  }
}

See TLS Setup for generating certificates and the full TLS option set.

Example Configs

Self-monitoring — simple.conf

Multiple application endpoints — myapps.conf

Metric filtering — agent-filters.conf

Dynamic discovery targets — discovery-targets.conf

Prometheus federation — federate.conf

Server-only TLS — tls-no-mutual-auth.conf

Mutual TLS — tls-with-mutual-auth.conf