Proxy Configuration

The proxy runs outside the firewall alongside Prometheus. It accepts scrape requests from Prometheus on HTTP and communicates with agents via gRPC.

HTTP Service

Configure the HTTP service that Prometheus scrapes:

proxy {
  http {
    port = 8080                       // Listen port for Prometheus scrapes
    idleTimeoutSecs = 45             // HTTP idle timeout
    requestLoggingEnabled = true      // Log every proxy metrics request
  }
}

gRPC Service

Configure the gRPC service that agents connect to:

proxy {
  agent.port = 50051                  // gRPC listen port for agent connections

  grpc {
    keepAliveTimeSecs = 7200          // Interval between PING frames
    keepAliveTimeoutSecs = 20         // Timeout for PING acknowledgment
    permitKeepAliveWithoutCalls = false
    maxConnectionIdleSecs = -1        // -1 = unlimited
    maxConnectionAgeSecs = -1         // -1 = unlimited
  }
}

Agent Authentication

The agent gRPC port is unauthenticated by default. Set a pre-shared token so the proxy rejects agents that do not present a matching value (UNAUTHENTICATED). Resolved from --agent_token → AGENT_TOKEN → proxy.agentToken; empty (the default) disables the check and logs a startup warning unless mutual TLS is configured. The token is never logged.

proxy {
  agentToken = "shared-secret"   // Agents must present the same value
}

Per-Agent Identities

Scope agents to specific paths with proxy.auth: a list of named identities, each with its own token and allowed path glob patterns. The proxy resolves an agent's token to an identity and rejects any registerPath for a path that does not match the identity's patterns. An empty paths list allows all paths. A legacy proxy.agentToken (above) is honored alongside auth as an allow-all identity, easing migration. See Per-Agent Identities and Path Authorization for details and a migration walkthrough.

proxy {
  auth = [
    { name = team-a, token = "team-a-token", paths = ["team_a_*"] }
    { name = team-b, token = "team-b-token", paths = ["team_b_*"] }
  ]
}

Because auth is a list of objects, it is config-file-only — there is no CLI/env equivalent, and the -D override cannot express a list. Identity names must be unique and tokens non-empty.

Service Discovery

Enable Prometheus HTTP service discovery:

proxy {
  service.discovery {
    enabled = true
    path = "discovery"
    targetPrefix = "http://proxy-host.example.com:8080/"
  }
}

See Service Discovery for complete details.

Admin Endpoints

Enable admin endpoints for health checks and debugging:

proxy {
  admin {
    enabled = true
    port = 8092
    pingPath = "ping"
    versionPath = "version"
    healthCheckPath = "healthcheck"
    threadDumpPath = "threaddump"
    debugEnabled = false
  }
}

When enabled, the following endpoints are available:

Endpoint	Description
`GET /ping`	Returns "pong" (liveness check)
`GET /healthcheck`	Returns health status JSON
`GET /version`	Returns version information
`GET /threaddump`	Returns JVM thread dump
`GET /debug`	Proxy debug info (requires `debugEnabled = true`)

Metrics

Enable internal metrics collection:

proxy {
  metrics {
    enabled = true
    port = 8082
    path = "metrics"
  }

  admin {
    enabled = true
    port = 8092
  }
}

See Monitoring for the complete metrics reference.

Internal Settings

Configure agent cleanup and scrape request management:

proxy.internal {
  staleAgentCheckEnabled = true
  maxAgentInactivitySecs = 60         // Evict after 60s of inactivity
  staleAgentCheckPauseSecs = 10       // Check every 10s

  scrapeRequestTimeoutSecs = 90       // Timeout for scrape requests
}

Setting	Default	Description
`staleAgentCheckEnabled`	true	Enable periodic stale agent cleanup
`maxAgentInactivitySecs`	60	Seconds of inactivity before agent is evicted
`staleAgentCheckPauseSecs`	10	Interval between cleanup checks
`scrapeRequestTimeoutSecs`	90	Timeout for individual scrape requests

Content Size Limits

proxy.internal {
  maxZippedContentSizeMBytes = 5      // Max zipped content size
  maxUnzippedContentSizeMBytes = 10   // Max unzipped content size
}

Transport Filter

The transport filter detects agent disconnections immediately. Disable it when using a reverse proxy like Nginx:

proxy.transportFilterDisabled = true

Warning

With transportFilterDisabled, agent disconnections are not immediately detected. Agent contexts on the proxy are removed after the inactivity timeout (default: 60 seconds).

gRPC Reflection

gRPC Reflection is enabled by default for debugging and tooling. Disable it in production if desired:

proxy.reflectionDisabled = true

Log Level

# Set log level in config file:
proxy.logLevel = "debug"
agent.logLevel = "debug"

# Or via CLI:
# java -jar prometheus-proxy.jar --log_level debug
# java -jar prometheus-agent.jar --log_level debug

# Or via environment variable:
# PROXY_LOG_LEVEL=debug
# AGENT_LOG_LEVEL=debug

# Available levels: trace, debug, info, warn, error, off

Full Reference

See the complete configuration schema: config/config.conf