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	URL path on the proxy that Prometheus will scrape
`url`	Yes	Actual metrics endpoint the agent fetches from
`labels`	No	JSON string of labels for service discovery (default: `"{}"`)

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

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

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

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