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}