Pushgateway

The Prometheus Pushgateway exists to allow ephemeral and batch jobs to expose their metrics to Prometheus. Since these kinds of jobs may not exist long enough to be scraped, they can instead push their metrics to a Pushgateway. The Pushgateway then exposes these metrics to Prometheus.

The PushGateway Java class allows you to push metrics to a Prometheus Pushgateway.

Example

Gradle

implementation 'io.prometheus:prometheus-metrics-core:1.3.0'
implementation 'io.prometheus:prometheus-metrics-exporter-pushgateway:1.3.0'

Maven

<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>prometheus-metrics-core</artifactId>
    <version>1.3.0</version>
</dependency>
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>prometheus-metrics-exporter-pushgateway</artifactId>
    <version>1.3.0</version>
</dependency>

public class ExampleBatchJob {

    private static PushGateway pushGateway = PushGateway.builder()
            .address("localhost:9091") // not needed as localhost:9091 is the default
            .job("example")
            .build();

    private static Gauge dataProcessedInBytes = Gauge.builder()
            .name("data_processed")
            .help("data processed in the last batch job run")
            .unit(Unit.BYTES)
            .register();

    public static void main(String[] args) throws Exception {
        try {
            long bytesProcessed = processData();
            dataProcessedInBytes.set(bytesProcessed);
        } finally {
            pushGateway.push();
        }
    }

    public static long processData() {
        // Imagine a batch job here that processes data
        // and returns the number of Bytes processed.
        return 42;
    }
}

Basic Auth

The PushGateway supports basic authentication.

PushGateway pushGateway = PushGateway.builder()
    .job("example")
    .basicAuth("my_user", "my_password")
    .build();

The PushGatewayTestApp in integration-tests/it-pushgateway has a complete example of this.

Bearer token

The PushGateway supports Bearer token authentication.

PushGateway pushGateway = PushGateway.builder()
    .job("example")
    .bearerToken("my_token")
    .build();

The PushGatewayTestApp in integration-tests/it-pushgateway has a complete example of this.

SSL

The PushGateway supports SSL.

PushGateway pushGateway = PushGateway.builder()
    .job("example")
    .scheme(Scheme.HTTPS)
    .build();

However, this requires that the JVM can validate the server certificate.

If you want to skip certificate verification, you need to provide your own HttpConnectionFactory. See the API docs. The PushGatewayTestApp in integration-tests/it-pushgateway has a complete example of this.

Configuration Properties

The PushGateway supports a couple of properties that can be configured at runtime. See config.

Troubleshooting shaded jars

If you build a shaded jar with the Maven Shade Plugin and minimizeJar=true, the PushGateway may fail at runtime with an error like this:

java.lang.RuntimeException: class
io.prometheus.metrics.expositionformats.PrometheusProtobufWriter is not available

This happens because the PushGateway loads the protobuf writer implementation via reflection. The Maven Shade Plugin does not detect that reflective usage during minimization, so it may strip the required classes from the final jar.

To avoid this, keep the prometheus-metrics-exposition-formats artifact on the classpath and preserve the protobuf-related packages in your shade configuration:

<filters>
  <filter>
    <artifact>io.prometheus:prometheus-metrics-exposition-formats</artifact>
    <includes>
      <include>io/prometheus/metrics/expositionformats/**</include>
      <include>io/prometheus/metrics/shaded/**</include>
    </includes>
  </filter>
</filters>

Alternatively, disable jar minimization for the shaded build.