fix timestamp representation (#1292)

Fixes #1277

---------

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 {

mise.toml

@@ -19,17 +19,21 @@ env = { REQUIRE_PROTO_UP_TO_DATE = "true" }
 description = "format source code"
 run = "./mvnw spotless:apply"
 
+[tasks.compile]
+description = "bare compile, ignoring formatting and linters"
+run = "./mvnw install -DskipTests -Dspotless.check.skip=true -Dcoverage.skip=true -Dcheckstyle.skip=true -Dwarnings=-nowarn"
+
 [tasks.test]
 description = "run unit tests, ignoring formatting and linters"
-run = "./mvnw test -DskipTests=true -Dspotless.check.skip=true -Dcoverage.skip=true -Dcheckstyle.skip=true -Dwarnings=-nowarn"
+run = "./mvnw test -Dspotless.check.skip=true -Dcoverage.skip=true -Dcheckstyle.skip=true -Dwarnings=-nowarn"
 
 [tasks.test-all]
 description = "run all tests"
 run = "./mvnw verify"
 
 [tasks.build]
 description = "build all modules wihthout tests"
-run = "./mvnw clean install -DskipTests"
+run = "./mvnw install -DskipTests"
 
 [tasks.acceptance-test]
 description = "Run OATs acceptance tests"
@@ -39,7 +43,7 @@ run = "oats -timeout 5m examples/"
 [tasks.native-test]
 depends = "build"
 tools.java = "graalvm-22.3.3+java17"
-run = "../../mvnw  test -PnativeTest"
+run = "../../mvnw test -PnativeTest"
 dir = "integration-tests/it-spring-boot-smoke-test"
 
 [settings]

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

@@ -6,14 +6,21 @@
 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 PROMETHEUS_TIMESTAMPS_IN_MS = "prometheusTimestampsInMs";
   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 prometheusTimestampsInMs;
   private final Boolean exemplarsOnAllMetricTypes;
 
-  private ExporterProperties(Boolean includeCreatedTimestamps, Boolean exemplarsOnAllMetricTypes) {
+  private ExporterProperties(
+      Boolean includeCreatedTimestamps,
+      Boolean prometheusTimestampsInMs,
+      Boolean exemplarsOnAllMetricTypes) {
     this.includeCreatedTimestamps = includeCreatedTimestamps;
+    this.prometheusTimestampsInMs = prometheusTimestampsInMs;
     this.exemplarsOnAllMetricTypes = exemplarsOnAllMetricTypes;
   }
 
@@ -22,6 +29,11 @@ public boolean getIncludeCreatedTimestamps() {
     return includeCreatedTimestamps != null && includeCreatedTimestamps;
   }
 
+  /** Use milliseconds for timestamps in prometheus text format? Default is {@code false}. */
+  public boolean getPrometheusTimestampsInMs() {
+    return prometheusTimestampsInMs != null && prometheusTimestampsInMs;
+  }
+
   /**
    * 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 +50,12 @@ static ExporterProperties load(Map<Object, Object> properties)
       throws PrometheusPropertiesException {
     Boolean includeCreatedTimestamps =
         Util.loadBoolean(PREFIX + "." + INCLUDE_CREATED_TIMESTAMPS, properties);
+    Boolean timestampsInMs =
+        Util.loadBoolean(PREFIX + "." + PROMETHEUS_TIMESTAMPS_IN_MS, properties);
     Boolean exemplarsOnAllMetricTypes =
         Util.loadBoolean(PREFIX + "." + EXEMPLARS_ON_ALL_METRIC_TYPES, properties);
-    return new ExporterProperties(includeCreatedTimestamps, exemplarsOnAllMetricTypes);
+    return new ExporterProperties(
+        includeCreatedTimestamps, timestampsInMs, exemplarsOnAllMetricTypes);
   }
 
   public static Builder builder() {
@@ -51,6 +66,7 @@ public static class Builder {
 
     private Boolean includeCreatedTimestamps;
     private Boolean exemplarsOnAllMetricTypes;
+    boolean prometheusTimestampsInMs;
 
     private Builder() {}
 
@@ -66,8 +82,15 @@ public Builder exemplarsOnAllMetricTypes(boolean exemplarsOnAllMetricTypes) {
       return this;
     }
 
+    /** See {@link #getPrometheusTimestampsInMs()}. */
+    public Builder prometheusTimestampsInMs(boolean prometheusTimestampsInMs) {
+      this.prometheusTimestampsInMs = prometheusTimestampsInMs;
+      return this;
+    }
+
     public ExporterProperties build() {
-      return new ExporterProperties(includeCreatedTimestamps, exemplarsOnAllMetricTypes);
+      return new ExporterProperties(
+          includeCreatedTimestamps, prometheusTimestampsInMs, exemplarsOnAllMetricTypes);
     }
   }
 }

prometheus-metrics-config/src/test/java/io/prometheus/metrics/config/ExporterPropertiesTest.java

@@ -48,6 +48,7 @@ void builder() {
         ExporterProperties.builder()
             .includeCreatedTimestamps(true)
             .exemplarsOnAllMetricTypes(true)
+            .prometheusTimestampsInMs(false)
             .build();
     assertThat(properties.getIncludeCreatedTimestamps()).isTrue();
     assertThat(properties.getExemplarsOnAllMetricTypes()).isTrue();

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 prometheusTimestampsInMs;
   private final Map<String, String> requestHeaders;
   private final PrometheusRegistry registry;
   private final HttpConnectionFactory connectionFactory;
@@ -89,20 +90,25 @@ private PushGateway(
       Format format,
       URL url,
       HttpConnectionFactory connectionFactory,
-      Map<String, String> requestHeaders) {
+      Map<String, String> requestHeaders,
+      boolean prometheusTimestampsInMs) {
     this.registry = registry;
     this.url = url;
     this.requestHeaders = Collections.unmodifiableMap(new HashMap<>(requestHeaders));
     this.connectionFactory = connectionFactory;
+    this.prometheusTimestampsInMs = prometheusTimestampsInMs;
     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.prometheusTimestampsInMs)
+          .build();
     } else {
       // use reflection to avoid a compile-time dependency on the expositionformats module
       return new PrometheusProtobufWriter();
@@ -264,6 +270,7 @@ public static class Builder {
     private String address;
     private Scheme scheme;
     private String job;
+    private boolean prometheusTimestampsInMs;
     private final Map<String, String> requestHeaders = new HashMap<>();
     private PrometheusRegistry registry = PrometheusRegistry.defaultRegistry;
     private HttpConnectionFactory connectionFactory = new DefaultHttpConnectionFactory();
@@ -380,6 +387,21 @@ 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 prometheusTimestampsInMs(boolean prometheusTimestampsInMs) {
+      this.prometheusTimestampsInMs = prometheusTimestampsInMs;
+      return this;
+    }
+
+    private boolean getPrometheusTimestampsInMs() {
+      // accept either to opt in to timestamps in milliseconds
+      return config.getExporterProperties().getPrometheusTimestampsInMs()
+          || this.prometheusTimestampsInMs;
+    }
+
     private Scheme getScheme(ExporterPushgatewayProperties properties) {
       if (properties != null && properties.getScheme() != null) {
         return Scheme.valueOf(properties.getScheme());
@@ -453,7 +475,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,
+            getPrometheusTimestampsInMs());
       } catch (MalformedURLException e) {
         throw new PrometheusPropertiesException(
             address + ": Invalid address. Expecting <host>:<port>");

prometheus-metrics-exporter-pushgateway/src/test/java/io/prometheus/metrics/exporter/pushgateway/BasicAuthPushGatewayTest.java

@@ -29,6 +29,7 @@ public void setUp() {
             .address("localhost:" + mockServerClient.getPort())
             .basicAuth("testUser", "testPwd")
             .registry(registry)
+            .prometheusTimestampsInMs(true)
             .job("j")
             .build();
   }

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

@@ -22,12 +22,18 @@ 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.getPrometheusTimestampsInMs())
+            .build(),
+        OpenMetricsTextFormatWriter.builder()
+            .setCreatedTimestampsEnabled(properties.getIncludeCreatedTimestamps())
+            .setExemplarsOnAllMetricTypesEnabled(properties.getExemplarsOnAllMetricTypes())
+            .build());
   }
 
   public ExpositionFormatWriter findWriter(String acceptHeader) {

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

@@ -4,7 +4,7 @@
 import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeEscapedLabelValue;
 import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeLabels;
 import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeLong;
-import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeTimestamp;
+import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeOpenMetricsTimestamp;
 
 import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets;
 import io.prometheus.metrics.model.snapshots.CounterSnapshot;
@@ -37,21 +37,58 @@
  */
 public class OpenMetricsTextFormatWriter implements ExpositionFormatWriter {
 
+  public static class Builder {
+    boolean createdTimestampsEnabled;
+    boolean exemplarsOnAllMetricTypesEnabled;
+
+    private Builder() {}
+
+    /**
+     * @param createdTimestampsEnabled whether to include the _created timestamp in the output
+     */
+    public Builder setCreatedTimestampsEnabled(boolean createdTimestampsEnabled) {
+      this.createdTimestampsEnabled = createdTimestampsEnabled;
+      return this;
+    }
+
+    /**
+     * @param exemplarsOnAllMetricTypesEnabled whether to include exemplars in the output for all
+     *     metric types
+     */
+    public Builder setExemplarsOnAllMetricTypesEnabled(boolean exemplarsOnAllMetricTypesEnabled) {
+      this.exemplarsOnAllMetricTypesEnabled = exemplarsOnAllMetricTypesEnabled;
+      return this;
+    }
+
+    public OpenMetricsTextFormatWriter build() {
+      return new OpenMetricsTextFormatWriter(
+          createdTimestampsEnabled, exemplarsOnAllMetricTypesEnabled);
+    }
+  }
+
   public static final String CONTENT_TYPE =
       "application/openmetrics-text; version=1.0.0; charset=utf-8";
   private final boolean createdTimestampsEnabled;
   private final boolean exemplarsOnAllMetricTypesEnabled;
 
   /**
-   * @param createdTimestampsEnabled defines if {@code _created} timestamps should be included in
-   *     the output or not.
+   * @param createdTimestampsEnabled whether to include the _created timestamp in the output - This
+   *     will produce an invalid OpenMetrics output, but is kept for backwards compatibility.
    */
   public OpenMetricsTextFormatWriter(
       boolean createdTimestampsEnabled, boolean exemplarsOnAllMetricTypesEnabled) {
     this.createdTimestampsEnabled = createdTimestampsEnabled;
     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) {
@@ -299,10 +336,10 @@ private void writeCreated(Writer writer, MetricMetadata metadata, DataPointSnaps
       throws IOException {
     if (createdTimestampsEnabled && data.hasCreatedTimestamp()) {
       writeNameAndLabels(writer, metadata.getPrometheusName(), "_created", data.getLabels());
-      writeTimestamp(writer, data.getCreatedTimestampMillis());
+      writeOpenMetricsTimestamp(writer, data.getCreatedTimestampMillis());
       if (data.hasScrapeTimestamp()) {
         writer.write(' ');
-        writeTimestamp(writer, data.getScrapeTimestampMillis());
+        writeOpenMetricsTimestamp(writer, data.getScrapeTimestampMillis());
       }
       writer.write('\n');
     }
@@ -335,7 +372,7 @@ private void writeScrapeTimestampAndExemplar(
       Writer writer, DataPointSnapshot data, Exemplar exemplar) throws IOException {
     if (data.hasScrapeTimestamp()) {
       writer.write(' ');
-      writeTimestamp(writer, data.getScrapeTimestampMillis());
+      writeOpenMetricsTimestamp(writer, data.getScrapeTimestampMillis());
     }
     if (exemplar != null) {
       writer.write(" # ");
@@ -344,7 +381,7 @@ private void writeScrapeTimestampAndExemplar(
       writeDouble(writer, exemplar.getValue());
       if (exemplar.hasTimestamp()) {
         writer.write(' ');
-        writeTimestamp(writer, exemplar.getTimestampMillis());
+        writeOpenMetricsTimestamp(writer, exemplar.getTimestampMillis());
       }
     }
     writer.write('\n');