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
    maxThreads = -1                   // -1 uses default
    minThreads = -1                   // -1 uses default
    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
  }
}

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: all, trace, debug, info, warn, error, off

Full Reference

See the complete configuration schema: config/config.conf