001package io.prometheus.metrics.exporter.pushgateway;
002
003import static io.prometheus.metrics.exporter.pushgateway.Scheme.HTTP;
004import static io.prometheus.metrics.model.snapshots.PrometheusNaming.escapeName;
005import static java.util.Objects.requireNonNull;
006
007import io.prometheus.metrics.annotations.StableApi;
008import io.prometheus.metrics.config.EscapingScheme;
009import io.prometheus.metrics.config.ExporterPushgatewayProperties;
010import io.prometheus.metrics.config.PrometheusProperties;
011import io.prometheus.metrics.config.PrometheusPropertiesException;
012import io.prometheus.metrics.expositionformats.ExpositionFormatWriter;
013import io.prometheus.metrics.expositionformats.PrometheusProtobufWriter;
014import io.prometheus.metrics.expositionformats.PrometheusTextFormatWriter;
015import io.prometheus.metrics.model.registry.Collector;
016import io.prometheus.metrics.model.registry.MultiCollector;
017import io.prometheus.metrics.model.registry.PrometheusRegistry;
018import java.io.ByteArrayOutputStream;
019import java.io.IOException;
020import java.io.InputStream;
021import java.io.OutputStream;
022import java.io.UnsupportedEncodingException;
023import java.net.HttpURLConnection;
024import java.net.InetAddress;
025import java.net.MalformedURLException;
026import java.net.URI;
027import java.net.URL;
028import java.net.URLEncoder;
029import java.net.UnknownHostException;
030import java.nio.charset.StandardCharsets;
031import java.time.Duration;
032import java.util.Base64;
033import java.util.Collections;
034import java.util.HashMap;
035import java.util.Locale;
036import java.util.Map;
037import java.util.TreeMap;
038import javax.annotation.Nullable;
039
040/**
041 * Export metrics via the <a href="https://github.com/prometheus/pushgateway">Prometheus
042 * Pushgateway</a>
043 *
044 * <p>The Prometheus Pushgateway exists to allow ephemeral and batch jobs to expose their metrics to
045 * Prometheus. Since these kinds of jobs may not exist long enough to be scraped, they can instead
046 * push their metrics to a Pushgateway. This Java class allows pushing the contents of a {@link
047 * PrometheusRegistry} to a Pushgateway.
048 *
049 * <p>Example usage:
050 *
051 * <pre>{@code
052 * void executeBatchJob() throws Exception {
053 *     PrometheusRegistry registry = new PrometheusRegistry();
054 *     Gauge duration = Gauge.builder()
055 *             .name("my_batch_job_duration_seconds")
056 *             .help("Duration of my batch job in seconds.")
057 *             .register(registry);
058 *     Timer durationTimer = duration.startTimer();
059 *     try {
060 *         // Your code here.
061 *
062 *         // This is only added to the registry after success,
063 *         // so that a previous success in the Pushgateway isn't overwritten on failure.
064 *         Gauge lastSuccess = Gauge.builder()
065 *                 .name("my_batch_job_last_success")
066 *                 .help("Last time my batch job succeeded, in unixtime.")
067 *                 .register(registry);
068 *         lastSuccess.set(System.currentTimeMillis());
069 *     } finally {
070 *         durationTimer.observeDuration();
071 *         PushGateway pg = PushGateway.builder()
072 *                 .address("127.0.0.1:9091")
073 *                 .job("my_batch_job")
074 *                 .registry(registry)
075 *                 .build();
076 *         pg.pushAdd();
077 *     }
078 * }
079 * }</pre>
080 *
081 * <p>See <a
082 * href="https://github.com/prometheus/pushgateway">https://github.com/prometheus/pushgateway</a>.
083 */
084@StableApi
085public class PushGateway {
086  private final URL url;
087  private final ExpositionFormatWriter writer;
088  private final boolean prometheusTimestampsInMs;
089  private final Map<String, String> requestHeaders;
090  private final PrometheusRegistry registry;
091  private final HttpConnectionFactory connectionFactory;
092  private final EscapingScheme escapingScheme;
093  private final Duration connectionTimeout;
094  private final Duration readTimeout;
095
096  private PushGateway(
097      PrometheusRegistry registry,
098      Format format,
099      URL url,
100      HttpConnectionFactory connectionFactory,
101      Map<String, String> requestHeaders,
102      boolean prometheusTimestampsInMs,
103      EscapingScheme escapingScheme,
104      Duration connectionTimeout,
105      Duration readTimeout) {
106    this.registry = registry;
107    this.url = url;
108    this.requestHeaders = Collections.unmodifiableMap(new HashMap<>(requestHeaders));
109    this.connectionFactory = connectionFactory;
110    this.prometheusTimestampsInMs = prometheusTimestampsInMs;
111    this.escapingScheme = escapingScheme;
112    this.connectionTimeout = connectionTimeout;
113    this.readTimeout = readTimeout;
114    writer = getWriter(format);
115    if (!writer.isAvailable()) {
116      throw new RuntimeException(writer.getClass() + " is not available");
117    }
118  }
119
120  @SuppressWarnings("deprecation")
121  private ExpositionFormatWriter getWriter(Format format) {
122    if (format == Format.PROMETHEUS_TEXT) {
123      return PrometheusTextFormatWriter.builder()
124          .setTimestampsInMs(this.prometheusTimestampsInMs)
125          .build();
126    } else {
127      // use reflection to avoid a compile-time dependency on the expositionformats module
128      return new PrometheusProtobufWriter();
129    }
130  }
131
132  /**
133   * Push all metrics. All metrics with the same job and grouping key are replaced.
134   *
135   * <p>This uses the PUT HTTP method.
136   */
137  public void push() throws IOException {
138    doRequest(registry, "PUT");
139  }
140
141  /**
142   * Push a single metric. All metrics with the same job and grouping key are replaced.
143   *
144   * <p>This is useful for pushing a single Gauge.
145   *
146   * <p>This uses the PUT HTTP method.
147   */
148  public void push(Collector collector) throws IOException {
149    PrometheusRegistry registry = new PrometheusRegistry();
150    registry.register(collector);
151    doRequest(registry, "PUT");
152  }
153
154  /**
155   * Push a single collector. All metrics with the same job and grouping key are replaced.
156   *
157   * <p>This uses the PUT HTTP method.
158   */
159  public void push(MultiCollector collector) throws IOException {
160    PrometheusRegistry registry = new PrometheusRegistry();
161    registry.register(collector);
162    doRequest(registry, "PUT");
163  }
164
165  /**
166   * Like {@link #push()}, but only metrics with the same name as the newly pushed metrics are
167   * replaced.
168   *
169   * <p>This uses the POST HTTP method.
170   */
171  public void pushAdd() throws IOException {
172    doRequest(registry, "POST");
173  }
174
175  /**
176   * Like {@link #push(Collector)}, but only the specified metric will be replaced.
177   *
178   * <p>This uses the POST HTTP method.
179   */
180  public void pushAdd(Collector collector) throws IOException {
181    PrometheusRegistry registry = new PrometheusRegistry();
182    registry.register(collector);
183    doRequest(registry, "POST");
184  }
185
186  /**
187   * Like {@link #push(MultiCollector)}, but only the metrics from the collector will be replaced.
188   *
189   * <p>This uses the POST HTTP method.
190   */
191  public void pushAdd(MultiCollector collector) throws IOException {
192    PrometheusRegistry registry = new PrometheusRegistry();
193    registry.register(collector);
194    doRequest(registry, "POST");
195  }
196
197  /**
198   * Deletes metrics from the Pushgateway.
199   *
200   * <p>This uses the DELETE HTTP method.
201   */
202  public void delete() throws IOException {
203    doRequest(null, "DELETE");
204  }
205
206  private void doRequest(@Nullable PrometheusRegistry registry, String method) throws IOException {
207    try {
208      HttpURLConnection connection = connectionFactory.create(url);
209      requestHeaders.forEach(connection::setRequestProperty);
210      connection.setRequestProperty("Content-Type", writer.getContentType());
211      if (!method.equals("DELETE")) {
212        connection.setDoOutput(true);
213      }
214      connection.setRequestMethod(method);
215
216      connection.setConnectTimeout((int) this.connectionTimeout.toMillis());
217      connection.setReadTimeout((int) this.readTimeout.toMillis());
218      connection.connect();
219
220      try {
221        if (!method.equals("DELETE")) {
222          OutputStream outputStream = connection.getOutputStream();
223          writer.write(outputStream, requireNonNull(registry).scrape(), this.escapingScheme);
224          outputStream.flush();
225          outputStream.close();
226        }
227
228        int response = connection.getResponseCode();
229        if (response / 100 != 2) {
230          String errorMessage;
231          InputStream errorStream = connection.getErrorStream();
232          if (errorStream != null) {
233            String errBody = readFromStream(errorStream);
234            errorMessage =
235                "Response code from " + url + " was " + response + ", response body: " + errBody;
236          } else {
237            errorMessage = "Response code from " + url + " was " + response;
238          }
239          throw new IOException(errorMessage);
240        }
241
242      } finally {
243        connection.disconnect();
244      }
245    } catch (IOException e) {
246      String baseUrl = url.getProtocol() + "://" + url.getHost();
247      if (url.getPort() != -1) {
248        baseUrl += ":" + url.getPort();
249      }
250      throw new IOException(
251          "Failed to push metrics to the Prometheus Pushgateway on "
252              + baseUrl
253              + ": "
254              + e.getMessage(),
255          e);
256    }
257  }
258
259  // toString with Charset is only available in Java 10+, but we want to support Java 8
260  @SuppressWarnings("JdkObsolete")
261  private static String readFromStream(InputStream is) throws IOException {
262    ByteArrayOutputStream result = new ByteArrayOutputStream();
263    byte[] buffer = new byte[1024];
264    int length;
265    while ((length = is.read(buffer)) != -1) {
266      result.write(buffer, 0, length);
267    }
268    return result.toString("UTF-8");
269  }
270
271  public static Builder builder() {
272    return builder(PrometheusProperties.get());
273  }
274
275  /**
276   * The {@link PrometheusProperties} will be used to override what is set in the {@link Builder}.
277   */
278  public static Builder builder(PrometheusProperties config) {
279    return new Builder(config);
280  }
281
282  public static class Builder {
283
284    private final PrometheusProperties config;
285    @Nullable private Format format;
286    @Nullable private String address;
287    @Nullable private Scheme scheme;
288    @Nullable private String job;
289    @Nullable private Duration connectionTimeout;
290    @Nullable private Duration readTimeout;
291    private boolean prometheusTimestampsInMs;
292    private final Map<String, String> requestHeaders = new HashMap<>();
293    private PrometheusRegistry registry = PrometheusRegistry.defaultRegistry;
294    private HttpConnectionFactory connectionFactory = new DefaultHttpConnectionFactory();
295    private final Map<String, String> groupingKey = new TreeMap<>();
296    @Nullable private EscapingScheme escapingScheme;
297
298    private Builder(PrometheusProperties config) {
299      this.config = config;
300    }
301
302    /** Default is {@link Format#PROMETHEUS_PROTOBUF}. */
303    public Builder format(Format format) {
304      this.format = requireNonNull(format, "format must not be null");
305      return this;
306    }
307
308    /**
309     * Address of the Pushgateway in format {@code host:port}. Default is {@code localhost:9091}.
310     * Can be overwritten at runtime with the {@code io.prometheus.exporter.pushgateway.address}
311     * property.
312     */
313    public Builder address(String address) {
314      this.address = requireNonNull(address, "address must not be null");
315      return this;
316    }
317
318    /** Username and password for HTTP basic auth when pushing to the Pushgateway. */
319    public Builder basicAuth(String user, String password) {
320      byte[] credentialsBytes =
321          (requireNonNull(user, "user must not be null")
322                  + ":"
323                  + requireNonNull(password, "password must not be null"))
324              .getBytes(StandardCharsets.UTF_8);
325      String encoded = Base64.getEncoder().encodeToString(credentialsBytes);
326      requestHeaders.put("Authorization", String.format("Basic %s", encoded));
327      return this;
328    }
329
330    /** Bearer token authorization when pushing to the Pushgateway. */
331    public Builder bearerToken(String token) {
332      requestHeaders.put(
333          "Authorization",
334          String.format("Bearer %s", requireNonNull(token, "token must not be null")));
335      return this;
336    }
337
338    /**
339     * Specify if metrics should be pushed using HTTP or HTTPS. Default is HTTP. Can be overwritten
340     * at runtime with the {@code io.prometheus.exporter.pushgateway.scheme} property.
341     */
342    public Builder scheme(Scheme scheme) {
343      this.scheme = requireNonNull(scheme, "scheme must not be null");
344      return this;
345    }
346
347    /**
348     * Custom connection factory. Default is {@link DefaultHttpConnectionFactory}.
349     *
350     * <p>The {@code PushGatewayTestApp} in {@code integration-tests/it-pushgateway/} has an example
351     * of a custom connection factory that skips SSL certificate validation for HTTPS connections.
352     */
353    public Builder connectionFactory(HttpConnectionFactory connectionFactory) {
354      this.connectionFactory =
355          requireNonNull(connectionFactory, "connectionFactory must not be null");
356      return this;
357    }
358
359    /**
360     * The {@code job} label to be used when pushing metrics. If not provided, the name of the JAR
361     * file will be used by default. Can be overwritten at runtime with the {@code
362     * io.prometheus.exporter.pushgateway.job} property.
363     */
364    public Builder job(String job) {
365      this.job = requireNonNull(job, "job must not be null");
366      return this;
367    }
368
369    /**
370     * Grouping keys to be used when pushing/deleting metrics. Call this method multiple times for
371     * adding multiple grouping keys.
372     */
373    public Builder groupingKey(String name, String value) {
374      groupingKey.put(
375          requireNonNull(name, "name must not be null"),
376          requireNonNull(value, "value must not be null"));
377      return this;
378    }
379
380    /** Convenience method for adding the current IP address as an "instance" label. */
381    public Builder instanceIpGroupingKey() throws UnknownHostException {
382      return groupingKey("instance", InetAddress.getLocalHost().getHostAddress());
383    }
384
385    /** Push metrics from this registry instead of {@link PrometheusRegistry#defaultRegistry}. */
386    public Builder registry(PrometheusRegistry registry) {
387      this.registry = requireNonNull(registry, "registry must not be null");
388      return this;
389    }
390
391    /**
392     * Specify the escaping scheme to be used when pushing metrics. Default is {@link
393     * EscapingScheme#UNDERSCORE_ESCAPING}.
394     */
395    public Builder escapingScheme(EscapingScheme escapingScheme) {
396      this.escapingScheme = requireNonNull(escapingScheme, "escapingScheme must not be null");
397      return this;
398    }
399
400    /**
401     * Use milliseconds for timestamps in text format? Default is {@code false}. Can be overwritten
402     * at runtime with the {@code io.prometheus.exporter.timestamps_in_ms} property.
403     */
404    public Builder prometheusTimestampsInMs(boolean prometheusTimestampsInMs) {
405      this.prometheusTimestampsInMs = prometheusTimestampsInMs;
406      return this;
407    }
408
409    /**
410     * Specify the connection timeout for HTTP connections to the PushGateway. Default is 10
411     * seconds.
412     *
413     * @param connectionTimeout timeout value
414     * @return this {@link Builder} instance
415     */
416    public Builder connectionTimeout(Duration connectionTimeout) {
417      this.connectionTimeout = connectionTimeout;
418      return this;
419    }
420
421    private Duration getConnectionTimeout(@Nullable ExporterPushgatewayProperties properties) {
422      if (properties != null && properties.getConnectTimeout() != null) {
423        return properties.getConnectTimeout();
424      } else if (this.connectionTimeout != null) {
425        return this.connectionTimeout;
426      } else {
427        return Duration.ofSeconds(10);
428      }
429    }
430
431    /**
432     * Specify the read timeout for HTTP connections to the PushGateway. Default is 10 seconds.
433     *
434     * @param readTimeout timeout value
435     * @return this {@link Builder} instance
436     */
437    public Builder readTimeout(Duration readTimeout) {
438      this.readTimeout = readTimeout;
439      return this;
440    }
441
442    private Duration getReadTimeout(@Nullable ExporterPushgatewayProperties properties) {
443      if (properties != null && properties.getReadTimeout() != null) {
444        return properties.getReadTimeout();
445      } else if (this.readTimeout != null) {
446        return this.readTimeout;
447      } else {
448        return Duration.ofSeconds(10);
449      }
450    }
451
452    private boolean getPrometheusTimestampsInMs() {
453      // accept either to opt in to timestamps in milliseconds
454      return config.getExporterProperties().getPrometheusTimestampsInMs()
455          || this.prometheusTimestampsInMs;
456    }
457
458    private Scheme getScheme(@Nullable ExporterPushgatewayProperties properties) {
459      if (properties != null && properties.getScheme() != null) {
460        return Scheme.fromString(properties.getScheme().toLowerCase(Locale.ROOT));
461      } else if (this.scheme != null) {
462        return this.scheme;
463      } else {
464        return HTTP;
465      }
466    }
467
468    private String getAddress(@Nullable ExporterPushgatewayProperties properties) {
469      if (properties != null && properties.getAddress() != null) {
470        return properties.getAddress();
471      } else if (this.address != null) {
472        return this.address;
473      } else {
474        return "localhost:9091";
475      }
476    }
477
478    private String getJob(@Nullable ExporterPushgatewayProperties properties) {
479      if (properties != null && properties.getJob() != null) {
480        return properties.getJob();
481      } else if (this.job != null) {
482        return this.job;
483      } else {
484        return DefaultJobLabelDetector.getDefaultJobLabel();
485      }
486    }
487
488    private EscapingScheme getEscapingScheme(@Nullable ExporterPushgatewayProperties properties) {
489      if (properties != null && properties.getEscapingScheme() != null) {
490        return properties.getEscapingScheme();
491      } else if (this.escapingScheme != null) {
492        return this.escapingScheme;
493      }
494      return EscapingScheme.UNDERSCORE_ESCAPING;
495    }
496
497    private Format getFormat() {
498      // currently not configurable via properties
499      if (this.format != null) {
500        return this.format;
501      }
502      return Format.PROMETHEUS_PROTOBUF;
503    }
504
505    // encode with Charset is only available in Java 10+, but we want to support Java 8
506    @SuppressWarnings("JdkObsolete")
507    private URL makeUrl(@Nullable ExporterPushgatewayProperties properties)
508        throws UnsupportedEncodingException, MalformedURLException {
509      StringBuilder url =
510          new StringBuilder(getScheme(properties) + "://" + getAddress(properties) + "/metrics/");
511      String job = getJob(properties);
512      if (needsBase64(job)) {
513        url.append("job@base64/").append(base64url(job));
514      } else {
515        url.append("job/").append(URLEncoder.encode(job, "UTF-8"));
516      }
517      for (Map.Entry<String, String> entry : groupingKey.entrySet()) {
518        if (entry.getValue().isEmpty()) {
519          url.append("/")
520              .append(escapeName(entry.getKey(), EscapingScheme.VALUE_ENCODING_ESCAPING))
521              .append("@base64/=");
522        } else if (needsBase64(entry.getValue())) {
523          url.append("/")
524              .append(escapeName(entry.getKey(), EscapingScheme.VALUE_ENCODING_ESCAPING))
525              .append("@base64/")
526              .append(base64url(entry.getValue()));
527        } else {
528          url.append("/")
529              .append(escapeName(entry.getKey(), EscapingScheme.VALUE_ENCODING_ESCAPING))
530              .append("/")
531              .append(URLEncoder.encode(entry.getValue(), "UTF-8"));
532        }
533      }
534      return URI.create(url.toString()).normalize().toURL();
535    }
536
537    // "/" would split the value into several path segments, and "." and ".." are dot segments
538    // that normalize() would remove from the path, sending the request to a different group.
539    private boolean needsBase64(String v) {
540      return v.contains("/") || v.equals(".") || v.equals("..");
541    }
542
543    private String base64url(String v) {
544      return Base64.getEncoder()
545          .encodeToString(v.getBytes(StandardCharsets.UTF_8))
546          .replace("+", "-")
547          .replace("/", "_");
548    }
549
550    public PushGateway build() {
551      ExporterPushgatewayProperties properties =
552          config == null ? null : config.getExporterPushgatewayProperties();
553      try {
554        return new PushGateway(
555            registry,
556            getFormat(),
557            makeUrl(properties),
558            connectionFactory,
559            requestHeaders,
560            getPrometheusTimestampsInMs(),
561            getEscapingScheme(properties),
562            getConnectionTimeout(properties),
563            getReadTimeout(properties));
564      } catch (MalformedURLException | IllegalArgumentException e) {
565        throw new PrometheusPropertiesException(
566            "Invalid Pushgateway address. Expecting <host>:<port>");
567      } catch (UnsupportedEncodingException e) {
568        throw new RuntimeException(e); // cannot happen, UTF-8 is always supported
569      }
570    }
571  }
572}