Proxy

class Proxy(val options: ProxyOptions, proxyPort: Int = options.proxyPort, inProcessServerName: String = "", testMode: Boolean = false, initBlock: Proxy.() -> Unit? = null) : GenericService<ConfigVals> (source)

Prometheus Proxy that enables metrics scraping across firewalls.

The Proxy is the component that runs outside the firewall alongside Prometheus server. It accepts scrape requests from Prometheus, routes them to appropriate Agents behind firewalls, and returns the collected metrics back to Prometheus. This enables the standard Prometheus pull model to work across network boundaries that would normally block direct access.

Architecture

The Proxy serves as a bridge between Prometheus and Agents, handling:

HTTP Service: Serves metrics endpoints that Prometheus can scrape
gRPC Service: Manages connections from multiple agents
Request Routing: Routes scrape requests to appropriate agents based on path mappings
Service Discovery: Provides Prometheus service discovery endpoints
Agent Management: Tracks agent connections and handles disconnections
Health Monitoring: Provides comprehensive health checks and metrics

Configuration

Proxies are configured via HOCON configuration files that specify:

HTTP port for Prometheus scrape requests
gRPC port for agent connections
Admin endpoints for monitoring and debugging
TLS settings for secure communication
Service discovery configuration
Agent cleanup and timeout settings

Usage Examples

Basic Usage

val proxy = Proxy(ProxyOptions(args))
proxy.startSync()

With Custom Initialization

val proxy = Proxy(options) {
    // Custom initialization logic
    logger.info { "Proxy initialized with custom settings" }
}
proxy.startSync()

In-Process for Testing

val proxy = Proxy(options, inProcessServerName = "test-server")
// Agents can connect using the same in-process server name

Request Flow

Prometheus Request: Prometheus sends scrape request to proxy HTTP endpoint
Path Resolution: Proxy determines which agent(s) can handle the requested path
Agent Communication: Proxy forwards request to appropriate agent(s) via gRPC
Metric Collection: Agent scrapes actual endpoint and returns metrics
Response Aggregation: Proxy aggregates responses from multiple agents if needed
Prometheus Response: Proxy returns collected metrics to Prometheus

Service Discovery

The Proxy can provide Prometheus-compatible service discovery by exposing an endpoint that returns JSON describing all available scrape targets. This allows Prometheus to automatically discover new metrics endpoints as agents register them.

High Availability

Multiple Proxy instances can run simultaneously for high availability:

Each proxy can handle the full set of agents
Agents automatically reconnect to available proxies
Load balancers can distribute Prometheus requests across proxies

Since

1.0.0

Parameters

options

Configuration options for the proxy, typically loaded from command line or config files

proxyPort

Port for the HTTP service that Prometheus scrapes. Defaults to value in options.

inProcessServerName

Optional in-process server name for testing scenarios. When specified, the proxy will create an in-process gRPC server instead of a network server.

testMode

Whether to run in test mode. Test mode may disable certain features or use different defaults suitable for testing environments.

initBlock

Optional initialization block executed after construction but before startup. Useful for custom configuration or testing setup.

Constructors

Proxy

constructor(options: ProxyOptions, proxyPort: Int = options.proxyPort, inProcessServerName: String = "", testMode: Boolean = false, initBlock: Proxy.() -> Unit? = null)