Agent Configuration

The agent runs inside the firewall and scrapes local metrics endpoints on behalf of the proxy.

Path Configs

The pathConfigs array defines which metrics endpoints the agent exposes through the proxy:

Basic Configuration

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

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

Multiple Endpoints

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"
    }
  ]
}

With Labels

Labels are included in service discovery responses and can be used for filtering:

agent {
  pathConfigs: [
    {
      name: "Production API"
      path: prod_api_metrics
      labels: "{\"env\": \"production\", \"team\": \"backend\"}"
      url: "http://api.internal:9100/metrics"
    },
    {
      name: "Staging API"
      path: staging_api_metrics
      labels: "{\"env\": \"staging\", \"team\": \"backend\"}"
      url: "http://api.staging:9100/metrics"
    }
  ]
}

Each path config entry has these fields:

Field	Required	Description
`name`	Yes	Human-readable endpoint name (for logs and debugging)
`path`	Yes	Single URL segment on the proxy that Prometheus scrapes (no embedded `/`)
`url`	Yes	Actual metrics endpoint the agent fetches from
`labels`	No	JSON string of labels for service discovery (default: `"{}"`)

Paths are a single segment

A path is one URL segment — it must not contain an embedded /. The proxy serves each registered path at /<path> (a one-segment route), so a multi-segment value like app/metrics is rejected at registration (the agent logs the failure rather than reconnecting). Use app_metrics instead.

Proxy Connection

agent {
  proxy {
    hostname = "proxy-host.example.com"   // Proxy hostname
    port = 50051                          // Proxy gRPC port
  }
}

Or specify on the command line:

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

Agent Authentication

If the proxy requires a pre-shared agent token, set the matching value on the agent. It is presented as a gRPC metadata header on every call and is never logged. Resolved from --agent_token → AGENT_TOKEN → agent.agentToken; empty (the default) sends no token.

agent {
  agentToken = "shared-secret"   // Must match the proxy's proxy.agentToken
}

HTTP Client Settings

Configure how the agent makes HTTP requests to scrape endpoints:

agent {
  http {
    maxConcurrentClients = 5          // Parallel scrape limit
    clientTimeoutSecs = 30            // HTTP client timeout
    maxContentLengthMBytes = 10       // Max response size in MB
    enableTrustAllX509Certificates = false
    trustStorePath = ""               // JKS/PKCS12 trust store for HTTPS targets (custom CA); empty = JDK default
    trustStorePassword = ""           // Password for trustStorePath
  }
}

HTTP Client Cache

The agent caches HTTP clients keyed by authentication credentials (for basic auth / bearer token scenarios). Configure cache behavior:

agent {
  http.clientCache {
    maxSize = 100                     // Maximum cached HTTP clients
    maxAgeMins = 30                   // Maximum age of cached clients
    maxIdleMins = 10                  // Idle time before eviction
    cleanupIntervalMins = 5           // Cleanup run interval
  }
}

Scraping HTTPS Endpoints

For HTTPS scrape targets signed by a private or internal CA, point the agent at a trust store that contains that CA (--https_truststore / HTTPS_TRUST_STORE_PATH / agent.http.trustStorePath, with the matching *_password) so certificates are still validated. An empty path uses the JDK default trust store, and --trust_all_x509 (which disables verification entirely) takes precedence. See Scraping HTTPS Endpoints for details.

Scrape Settings

agent {
  scrapeTimeoutSecs = 15              // Total scrape timeout including retries
  scrapeMaxRetries = 0                // 0 disables retries
  chunkContentSizeKbs = 32            // Chunking threshold in KB
  minGzipSizeBytes = 512              // Minimum size for gzip compression
}

Setting	Default	Description
`scrapeTimeoutSecs`	15	Total time allowed for a scrape including retries
`scrapeMaxRetries`	0	Maximum retries; 0 disables retries
`chunkContentSizeKbs`	32	Responses larger than this are chunked
`minGzipSizeBytes`	512	Responses larger than this are gzip-compressed

Consolidated Mode

By default, each path is owned by a single agent. Enable consolidated mode to allow multiple agents to register the same path:

agent {
  consolidated = true                 // Allow multiple agents per path

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

  pathConfigs: [
    {
      name: "Shared metrics"
      path: shared_metrics
      url: "http://localhost:9100/metrics"
    }
  ]
}

This is useful for redundancy -- if one agent goes down, another can serve the same path.

Agent Naming

Give agents descriptive names for easier identification in logs and metrics:

java -jar prometheus-agent.jar --name production-agent-01 --config agent.conf

Or in the config file:

agent.name = "production-agent-01"

If no name is provided, the agent uses Unnamed-<hostname>.

Full Example

Here is a real-world config from the examples/ directory:

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"
    }
  ]
}