AgentOptions

Enables the admin servlets (/ping, /version, /healthcheck, /threaddump) on this process. Resolved from CLI → ADMIN_ENABLED env var → <role>.admin.enabled config (default false).

Listen port for this process's admin servlets. -1 means "fall back to ADMIN_PORT env var, then <role>.admin.port config (Proxy default 8092, Agent default 8093)".

Friendly name for this Agent. Surfaces in metrics labels and log lines on both Proxy and Agent. Empty means "fall back to AGENT_NAME env var, then agent.name from config".

Interval between HTTP-client-cache cleanup sweeps, in minutes. -1 means "fall back to CLIENT_CACHE_CLEANUP_INTERVAL_MINS env var, then agent.http.clientCache.cleanupIntervalMins (default 5)". Validated > 0.

Filesystem path to the TLS certificate chain (PEM). Must be paired with privateKeyFilePath; supplying one without the other is rejected by validateTlsConfig. Empty disables TLS on this side and exposes plaintext gRPC. See also isTlsEnabled.

Threshold above which a scrape response is split into chunked gRPC messages, expressed in kilobytes on input. After resolution, the field is converted in-place to bytes for runtime use; the chunkContentSizeBytes name reflects that final unit.

Run the Agent in consolidated mode, allowing multiple agents to register the same path on the Proxy for redundancy/load-spreading. Resolved from CLI → CONSOLIDATED env var → agent.consolidated config.

Enables the /debug admin servlet on this process — exposes recent activity / scrape-request introspection. Distinct from DEBUG (the servlet path constant). Resolved from CLI → DEBUG_ENABLED env var → <role>.admin.debugEnabled config (default false).

Dynamic HOCON property overrides accepted as -Dkey=value (multiple -D flags allowed). Each pair is merged into the resolved config with highest precedence over the loaded config file, and any surrounding double-quotes on the value are stripped. Useful for one-off overrides that don't have a dedicated flag.

HTTP client request timeout used by the Agent when scraping endpoints, in seconds. -1 means "fall back to CLIENT_TIMEOUT_SECS env var, then agent.http.clientTimeoutSecs (default 90)". Validated > 0.

gRPC keepalive ping timeout, in seconds — how long this side waits for a keepalive ack before considering the connection dead. -1L means "fall back to KEEPALIVE_TIMEOUT_SECS env var, then <role>.grpc.keepAliveTimeoutSecs config; -1L after resolution leaves the gRPC default in place".

gRPC keepalive ping interval, in seconds — how often this side sends a keepalive ping on an idle channel. -1L means "fall back to KEEPALIVE_TIME_SECS env var, then <role>.grpc.keepAliveTimeSecs config; -1L after resolution leaves the gRPC default in place".

If true, the Agent sends gRPC keepalive pings to the Proxy even when no RPCs are in-flight — useful when the connection traverses a load balancer or NAT that idles out silent TCP sessions. The Proxy must permit this via --permit_keepalive_without_calls or it will reject the pings as a protocol violation.

Logback log level for this process: one of all, trace, debug, info, warn, error, off. Empty falls back to the role-specific env var (io.prometheus.common.EnvVars.PROXY_LOG_LEVEL or io.prometheus.common.EnvVars.AGENT_LOG_LEVEL) and then <role>.logLevel config; if still empty, the level configured in logback.xml is used.

Maximum age before a cached HTTP client is evicted, in minutes (regardless of activity). -1 means "fall back to MAX_CLIENT_CACHE_AGE_MINS env var, then agent.http.clientCache.maxAgeMins (default 30)". Validated > 0.

Maximum idle time before a cached HTTP client is evicted, in minutes. -1 means "fall back to MAX_CLIENT_CACHE_IDLE_MINS env var, then agent.http.clientCache.maxIdleMins (default 10)". Validated > 0.

Maximum number of pooled HTTP clients the Agent caches (keyed by target/auth credentials). -1 means "fall back to MAX_CLIENT_CACHE_SIZE env var, then agent.http.clientCache.maxSize (default 100)". Validated > 0.

Maximum number of concurrent HTTP scrape requests the Agent will issue across all targets. -1 means "fall back to MAX_CONCURRENT_CLIENTS env var, then agent.http.maxConcurrentClients (default 1)". Validated > 0.

Maximum allowed size of a scrape response, in megabytes. Larger payloads are rejected by the Agent. -1 falls back to agent.http.maxContentLengthMBytes from config (default 10). Validated > 0.

Enables this process's Prometheus metrics endpoint. Resolved from CLI → METRICS_ENABLED env var → <role>.metrics.enabled config (default false).

Listen port for this process's Prometheus metrics endpoint. -1 means "fall back to METRICS_PORT env var, then <role>.metrics.port config (Proxy default 8082, Agent default 8083)".

Scrape responses larger than this size are gzipped before being streamed to the Proxy, in bytes. -1 means "fall back to MIN_GZIP_SIZE_BYTES env var, then agent.minGzipSizeBytes (default 512)".

TLS authority override for the Agent's outbound gRPC channel — useful when the Proxy hostname does not match its certificate SAN (e.g. connecting through a reverse proxy or load balancer using a private DNS name). Empty disables the override and gRPC validates against the Proxy hostname.

Filesystem path to the TLS private key (PEM) matching certChainFilePath. Must be paired with the cert file; supplying one without the other is rejected by validateTlsConfig. Empty disables TLS on this side.

Proxy address the Agent connects to. Accepts either hostname (port defaults to agent.proxy.port from config, normally 50051) or hostname:port. Empty means "fall back to PROXY_HOSTNAME env var, then agent.proxy.hostname[:port] from config".

Maximum number of retries on a failed scrape before reporting failure to the Proxy. 0 disables retries entirely. -1 means "fall back to SCRAPE_MAX_RETRIES env var, then config (default 0)".

Per-scrape timeout when the Agent fetches the underlying metrics endpoint, in seconds. -1 means "fall back to SCRAPE_TIMEOUT_SECS env var, then agent.scrapeTimeoutSecs config (default 15)".

Disables the gRPC transport filter that records remote-peer information per call. Set when running behind an L7 reverse proxy (e.g. nginx) that already strips this information.

Insecure. When true, the Agent's HTTP client trusts every X.509 certificate presented by HTTPS scrape targets — no hostname or chain validation. Intended only for self-signed internal endpoints during development; logs a warning at startup. Resolved from CLI → TRUST_ALL_X509_CERTIFICATES env var → agent.http.enableTrustAllX509Certificates config.

Filesystem path to the trust-store certificate collection (PEM) used to validate the peer's certificate. Required for mTLS; for one-way TLS the JDK default trust store is used when this is empty.

Per-call deadline applied to unary gRPC calls (e.g. registerAgent, registerPath) from Agent to Proxy, in seconds. Streaming RPCs are not affected. -1 means "fall back to UNARY_DEADLINE_SECS env var, then agent.grpc.unaryDeadlineSecs (default 30)".