fix timestamp style

Signed-off-by: Gregor Zeitlinger <[email protected]>

Author: zeitlinger

benchmarks/src/main/java/io/prometheus/metrics/benchmarks/TextFormatUtilBenchmark.java

@@ -50,9 +50,9 @@ public class TextFormatUtilBenchmark {
   }
 
   private static final ExpositionFormatWriter OPEN_METRICS_TEXT_FORMAT_WRITER =
-      new OpenMetricsTextFormatWriter(false, false);
+      OpenMetricsTextFormatWriter.create();
   private static final ExpositionFormatWriter PROMETHEUS_TEXT_FORMAT_WRITER =
-      new PrometheusTextFormatWriter(false);
+      PrometheusTextFormatWriter.create();
 
   @State(Scope.Benchmark)
   public static class WriterState {

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java

@@ -6,14 +6,19 @@
 public class ExporterProperties {
 
   private static final String INCLUDE_CREATED_TIMESTAMPS = "includeCreatedTimestamps";
+  // milliseconds is the default - we only provide a boolean flag to avoid a breaking change
+  private static final String TIMESTAMPS_IN_MS = "timestampsInMs";
   private static final String EXEMPLARS_ON_ALL_METRIC_TYPES = "exemplarsOnAllMetricTypes";
   private static final String PREFIX = "io.prometheus.exporter";
 
   private final Boolean includeCreatedTimestamps;
+  private final Boolean timestampsInMs;
   private final Boolean exemplarsOnAllMetricTypes;
 
-  private ExporterProperties(Boolean includeCreatedTimestamps, Boolean exemplarsOnAllMetricTypes) {
+  private ExporterProperties(
+      Boolean includeCreatedTimestamps, Boolean timestampsInMs, Boolean exemplarsOnAllMetricTypes) {
     this.includeCreatedTimestamps = includeCreatedTimestamps;
+    this.timestampsInMs = timestampsInMs;
     this.exemplarsOnAllMetricTypes = exemplarsOnAllMetricTypes;
   }
 
@@ -22,6 +27,11 @@ public boolean getIncludeCreatedTimestamps() {
     return includeCreatedTimestamps != null && includeCreatedTimestamps;
   }
 
+  /** Use milliseconds for timestamps in text format? Default is {@code false}. */
+  public boolean getTimestampsInMs() {
+    return timestampsInMs != null && timestampsInMs;
+  }
+
   /**
    * Allow Exemplars on all metric types in OpenMetrics format? Default is {@code false}, which
    * means Exemplars will only be added for Counters and Histogram buckets.
@@ -38,9 +48,12 @@ static ExporterProperties load(Map<Object, Object> properties)
       throws PrometheusPropertiesException {
     Boolean includeCreatedTimestamps =
         Util.loadBoolean(PREFIX + "." + INCLUDE_CREATED_TIMESTAMPS, properties);
+    Boolean timestampsInMs = Util.loadBoolean(PREFIX + "." + TIMESTAMPS_IN_MS, properties);
     Boolean exemplarsOnAllMetricTypes =
         Util.loadBoolean(PREFIX + "." + EXEMPLARS_ON_ALL_METRIC_TYPES, properties);
-    return new ExporterProperties(includeCreatedTimestamps, exemplarsOnAllMetricTypes);
+    // new prop?
+    return new ExporterProperties(
+        includeCreatedTimestamps, timestampsInMs, exemplarsOnAllMetricTypes);
   }
 
   public static Builder builder() {
@@ -51,6 +64,7 @@ public static class Builder {
 
     private Boolean includeCreatedTimestamps;
     private Boolean exemplarsOnAllMetricTypes;
+    boolean timestampsInMs;
 
     private Builder() {}
 
@@ -66,8 +80,15 @@ public Builder exemplarsOnAllMetricTypes(boolean exemplarsOnAllMetricTypes) {
       return this;
     }
 
+    /** See {@link #getTimestampsInMs()}. */
+    public Builder setTimestampsInMs(boolean timestampsInMs) {
+      this.timestampsInMs = timestampsInMs;
+      return this;
+    }
+
     public ExporterProperties build() {
-      return new ExporterProperties(includeCreatedTimestamps, exemplarsOnAllMetricTypes);
+      return new ExporterProperties(
+          includeCreatedTimestamps, timestampsInMs, exemplarsOnAllMetricTypes);
     }
   }
 }

prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/PushGateway.java

@@ -80,6 +80,7 @@ public class PushGateway {
 
   private final URL url;
   private final ExpositionFormatWriter writer;
+  private final boolean timestampsInMs;
   private final Map<String, String> requestHeaders;
   private final PrometheusRegistry registry;
   private final HttpConnectionFactory connectionFactory;
@@ -89,20 +90,23 @@ private PushGateway(
       Format format,
       URL url,
       HttpConnectionFactory connectionFactory,
-      Map<String, String> requestHeaders) {
+      Map<String, String> requestHeaders,
+      boolean timestampsInMs) {
     this.registry = registry;
     this.url = url;
     this.requestHeaders = Collections.unmodifiableMap(new HashMap<>(requestHeaders));
     this.connectionFactory = connectionFactory;
+    this.timestampsInMs = timestampsInMs;
     writer = getWriter(format);
     if (!writer.isAvailable()) {
       throw new RuntimeException(writer.getClass() + " is not available");
     }
   }
 
+  @SuppressWarnings("deprecation")
   private ExpositionFormatWriter getWriter(Format format) {
     if (format == Format.PROMETHEUS_TEXT) {
-      return new PrometheusTextFormatWriter(false);
+      return PrometheusTextFormatWriter.builder().setTimestampsInMs(this.timestampsInMs).build();
     } else {
       // use reflection to avoid a compile-time dependency on the expositionformats module
       return new PrometheusProtobufWriter();
@@ -264,6 +268,7 @@ public static class Builder {
     private String address;
     private Scheme scheme;
     private String job;
+    private boolean timestampsInMs;
     private final Map<String, String> requestHeaders = new HashMap<>();
     private PrometheusRegistry registry = PrometheusRegistry.defaultRegistry;
     private HttpConnectionFactory connectionFactory = new DefaultHttpConnectionFactory();
@@ -380,6 +385,20 @@ public Builder registry(PrometheusRegistry registry) {
       return this;
     }
 
+    /**
+     * Use milliseconds for timestamps in text format? Default is {@code false}. Can be overwritten
+     * at runtime with the {@code io.prometheus.exporter.timestampsInMs} property.
+     */
+    public Builder setTimestampsInMs(boolean timestampsInMs) {
+      this.timestampsInMs = timestampsInMs;
+      return this;
+    }
+
+    private boolean getTimestampsInMs() {
+      // accept either to opt in to timestamps in milliseconds
+      return config.getExporterProperties().getTimestampsInMs() || this.timestampsInMs;
+    }
+
     private Scheme getScheme(ExporterPushgatewayProperties properties) {
       if (properties != null && properties.getScheme() != null) {
         return Scheme.valueOf(properties.getScheme());
@@ -453,7 +472,12 @@ public PushGateway build() {
           config == null ? null : config.getExporterPushgatewayProperties();
       try {
         return new PushGateway(
-            registry, getFormat(), makeUrl(properties), connectionFactory, requestHeaders);
+            registry,
+            getFormat(),
+            makeUrl(properties),
+            connectionFactory,
+            requestHeaders,
+            getTimestampsInMs());
       } catch (MalformedURLException e) {
         throw new PrometheusPropertiesException(
             address + ": Invalid address. Expecting <host>:<port>");

prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormats.java

@@ -22,12 +22,19 @@ public static ExpositionFormats init() {
     return init(PrometheusProperties.get().getExporterProperties());
   }
 
+  @SuppressWarnings("deprecation")
   public static ExpositionFormats init(ExporterProperties properties) {
     return new ExpositionFormats(
         new PrometheusProtobufWriter(),
-        new PrometheusTextFormatWriter(properties.getIncludeCreatedTimestamps()),
-        new OpenMetricsTextFormatWriter(
-            properties.getIncludeCreatedTimestamps(), properties.getExemplarsOnAllMetricTypes()));
+        PrometheusTextFormatWriter.builder()
+            .setIncludeCreatedTimestamps(properties.getIncludeCreatedTimestamps())
+            .setTimestampsInMs(properties.getTimestampsInMs())
+            .build(),
+        OpenMetricsTextFormatWriter.builder()
+            .setCreatedTimestampsEnabled(properties.getIncludeCreatedTimestamps())
+            .setExemplarsOnAllMetricTypesEnabled(properties.getExemplarsOnAllMetricTypes())
+            .setTimestampsInMs(properties.getTimestampsInMs())
+            .build());
   }
 
   public ExpositionFormatWriter findWriter(String acceptHeader) {

prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java

@@ -38,68 +38,76 @@
 public class OpenMetricsTextFormatWriter implements ExpositionFormatWriter {
 
   public static class Builder {
-    CreatedTimestampStyle createdTimestampStyle;
+    boolean createdTimestampsEnabled;
+    boolean timestampsInMs = true;
     boolean exemplarsOnAllMetricTypesEnabled;
 
-    private Builder() {
-    }
+    private Builder() {}
 
     /**
      * @param createdTimestampsEnabled whether to include the _created timestamp in the output
      */
-    public void setCreatedTimestampsEnabled(boolean createdTimestampsEnabled) {
-      this.createdTimestampStyle = CreatedTimestampStyle.fromEnabled(createdTimestampsEnabled);
+    public Builder setCreatedTimestampsEnabled(boolean createdTimestampsEnabled) {
+      this.createdTimestampsEnabled = createdTimestampsEnabled;
+      return this;
     }
 
     /**
-     * @param exemplarsOnAllMetricTypesEnabled whether to include exemplars in the output for all metric types
+     * @param exemplarsOnAllMetricTypesEnabled whether to include exemplars in the output for all
+     *     metric types
      */
-    public void setExemplarsOnAllMetricTypesEnabled(boolean exemplarsOnAllMetricTypesEnabled) {
+    public Builder setExemplarsOnAllMetricTypesEnabled(boolean exemplarsOnAllMetricTypesEnabled) {
       this.exemplarsOnAllMetricTypesEnabled = exemplarsOnAllMetricTypesEnabled;
+      return this;
     }
-  }
-
-  private enum CreatedTimestampStyle {
-    DISABLED,
-    DEPRECATED,
-    MILLISECONDS;
 
-    private static CreatedTimestampStyle fromDeprecated(boolean createdTimestampsEnabled) {
-      return createdTimestampsEnabled ? DEPRECATED : DISABLED;
+    @Deprecated
+    public Builder setTimestampsInMs(boolean timestampsInMs) {
+      this.timestampsInMs = timestampsInMs;
+      return this;
     }
 
-    private static CreatedTimestampStyle fromEnabled(boolean createdTimestampsEnabled) {
-      return createdTimestampsEnabled ? MILLISECONDS : DISABLED;
+    public OpenMetricsTextFormatWriter build() {
+      return new OpenMetricsTextFormatWriter(
+          createdTimestampsEnabled, timestampsInMs, exemplarsOnAllMetricTypesEnabled);
     }
   }
 
   public static final String CONTENT_TYPE =
       "application/openmetrics-text; version=1.0.0; charset=utf-8";
-  private final CreatedTimestampStyle createdTimestampStyle;
+  private final boolean createdTimestampsEnabled;
+  private final boolean timestampsInMs;
   private final boolean exemplarsOnAllMetricTypesEnabled;
 
   /**
-   * @param createdTimestampsEnabled whether to include the _created timestamp in the output - This will produce an invalid OpenMetrics output, but is kept for backwards compatibility.
-   * @deprecated this constructor is deprecated and will be removed in the next major version. Use
+   * @param createdTimestampsEnabled whether to include the _created timestamp in the output - This
+   *     will produce an invalid OpenMetrics output, but is kept for backwards compatibility.
+   * @deprecated this constructor is deprecated and will be removed in the next major version -
+   *     {@link #builder()} or {@link #create()} instead
    */
   @Deprecated
   public OpenMetricsTextFormatWriter(
       boolean createdTimestampsEnabled, boolean exemplarsOnAllMetricTypesEnabled) {
-    this(CreatedTimestampStyle.fromDeprecated(createdTimestampsEnabled), exemplarsOnAllMetricTypesEnabled);
+    this(createdTimestampsEnabled, false, exemplarsOnAllMetricTypesEnabled);
   }
 
-  // some new ctor that produces milliceconds timestamps as required by the OpenMetrics spec
-  // https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information
   private OpenMetricsTextFormatWriter(
-    CreatedTimestampStyle createdTimestampStyle, boolean exemplarsOnAllMetricTypesEnabled) {
-    this.createdTimestampStyle = createdTimestampStyle;
+      boolean createdTimestampsEnabled,
+      boolean timestampsInMs,
+      boolean exemplarsOnAllMetricTypesEnabled) {
+    this.createdTimestampsEnabled = createdTimestampsEnabled;
+    this.timestampsInMs = timestampsInMs;
     this.exemplarsOnAllMetricTypesEnabled = exemplarsOnAllMetricTypesEnabled;
   }
 
   public static Builder builder() {
     return new Builder();
   }
 
+  public static OpenMetricsTextFormatWriter create() {
+    return builder().build();
+  }
+
   @Override
   public boolean accepts(String acceptHeader) {
     if (acceptHeader == null) {
@@ -345,12 +353,12 @@ private void writeCountAndSum(
 
   private void writeCreated(Writer writer, MetricMetadata metadata, DataPointSnapshot data)
       throws IOException {
-    if (createdTimestampStyle != CreatedTimestampStyle.DISABLED && data.hasCreatedTimestamp()) {
+    if (createdTimestampsEnabled && data.hasCreatedTimestamp()) {
       writeNameAndLabels(writer, metadata.getPrometheusName(), "_created", data.getLabels());
-      writeTimestamp(writer, data.getCreatedTimestampMillis());
+      writeTimestamp(writer, data.getCreatedTimestampMillis(), timestampsInMs);
       if (data.hasScrapeTimestamp()) {
         writer.write(' ');
-        writeTimestamp(writer, data.getScrapeTimestampMillis());
+        writeTimestamp(writer, data.getScrapeTimestampMillis(), timestampsInMs);
       }
       writer.write('\n');
     }
@@ -383,7 +391,7 @@ private void writeScrapeTimestampAndExemplar(
       Writer writer, DataPointSnapshot data, Exemplar exemplar) throws IOException {
     if (data.hasScrapeTimestamp()) {
       writer.write(' ');
-      writeTimestamp(writer, data.getScrapeTimestampMillis());
+      writeTimestamp(writer, data.getScrapeTimestampMillis(), timestampsInMs);
     }
     if (exemplar != null) {
       writer.write(" # ");
@@ -392,7 +400,7 @@ private void writeScrapeTimestampAndExemplar(
       writeDouble(writer, exemplar.getValue());
       if (exemplar.hasTimestamp()) {
         writer.write(' ');
-        writeTimestamp(writer, exemplar.getTimestampMillis());
+        writeTimestamp(writer, exemplar.getTimestampMillis(), timestampsInMs);
       }
     }
     writer.write('\n');

prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java

@@ -36,9 +36,55 @@ public class PrometheusTextFormatWriter implements ExpositionFormatWriter {
   public static final String CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
 
   private final boolean writeCreatedTimestamps;
+  private final boolean timestampsInMs;
 
+  public static class Builder {
+    boolean includeCreatedTimestamps;
+    boolean timestampsInMs = true;
+
+    private Builder() {}
+
+    /**
+     * @param includeCreatedTimestamps whether to include the _created timestamp in the output
+     */
+    public Builder setIncludeCreatedTimestamps(boolean includeCreatedTimestamps) {
+      this.includeCreatedTimestamps = includeCreatedTimestamps;
+      return this;
+    }
+
+    @Deprecated
+    public Builder setTimestampsInMs(boolean timestampsInMs) {
+      this.timestampsInMs = timestampsInMs;
+      return this;
+    }
+
+    public PrometheusTextFormatWriter build() {
+      return new PrometheusTextFormatWriter(includeCreatedTimestamps, timestampsInMs);
+    }
+  }
+
+  /**
+   * @param writeCreatedTimestamps whether to include the _created timestamp in the output - This
+   *     will produce an invalid OpenMetrics output, but is kept for backwards compatibility.
+   * @deprecated this constructor is deprecated and will be removed in the next major version -
+   *     {@link #builder()} or {@link #create()} instead
+   */
+  @Deprecated
   public PrometheusTextFormatWriter(boolean writeCreatedTimestamps) {
+    this(writeCreatedTimestamps, false);
+  }
+
+  private PrometheusTextFormatWriter(boolean writeCreatedTimestamps, boolean timestampsInMs) {
     this.writeCreatedTimestamps = writeCreatedTimestamps;
+    this.timestampsInMs = timestampsInMs;
+  }
+
+  public static PrometheusTextFormatWriter.Builder builder() {
+    return new Builder();
+  }
+
+  public static PrometheusTextFormatWriter create() {
+    return builder().build();
   }
 
   @Override
@@ -106,7 +152,7 @@ public void writeCreated(Writer writer, MetricSnapshot snapshot) throws IOExcept
           metadataWritten = true;
         }
         writeNameAndLabels(writer, metadata.getPrometheusName(), "_created", data.getLabels());
-        writeTimestamp(writer, data.getCreatedTimestampMillis());
+        writeTimestamp(writer, data.getCreatedTimestampMillis(), timestampsInMs);
         writeScrapeTimestampAndNewline(writer, data);
       }
     }
@@ -363,7 +409,7 @@ private void writeScrapeTimestampAndNewline(Writer writer, DataPointSnapshot dat
       throws IOException {
     if (data.hasScrapeTimestamp()) {
       writer.write(' ');
-      writeTimestamp(writer, data.getScrapeTimestampMillis());
+      writeTimestamp(writer, data.getScrapeTimestampMillis(), timestampsInMs);
     }
     writer.write('\n');
   }