add Exemplar support for OpenTelemetry tracing (review)

Author: fstab

benchmark/src/main/java/io/prometheus/benchmark/CounterBenchmark.java benchmark/src/main/java/io/prometheus/client/benchmark/CounterBenchmark.java

@@ -1,4 +1,4 @@
-package io.prometheus.benchmark;
+package io.prometheus.client.benchmark;
 
 import com.codahale.metrics.MetricRegistry;
 

benchmark/src/main/java/io/prometheus/benchmark/ExemplarsBenchmark.java benchmark/src/main/java/io/prometheus/client/benchmark/ExemplarsBenchmark.java

@@ -1,4 +1,4 @@
-package io.prometheus.benchmark;
+package io.prometheus.client.benchmark;
 
 import io.prometheus.client.Counter;
 import io.prometheus.client.exemplars.DefaultExemplarSampler;

benchmark/src/main/java/io/prometheus/benchmark/GaugeBenchmark.java benchmark/src/main/java/io/prometheus/client/benchmark/GaugeBenchmark.java

@@ -1,4 +1,4 @@
-package io.prometheus.benchmark;
+package io.prometheus.client.benchmark;
 
 import com.codahale.metrics.MetricRegistry;
 

benchmark/src/main/java/io/prometheus/benchmark/SummaryBenchmark.java benchmark/src/main/java/io/prometheus/client/benchmark/SummaryBenchmark.java

@@ -1,4 +1,4 @@
-package io.prometheus.benchmark;
+package io.prometheus.client.benchmark;
 
 import com.codahale.metrics.MetricRegistry;
 

integration_tests/pom.xml

@@ -28,6 +28,17 @@
         <module>java_versions</module>
     </modules>
 
+    <build>
+        <pluginManagement>
+            <plugins>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-failsafe-plugin</artifactId>
+                    <version>2.22.2</version>
+                </plugin>
+            </plugins>
+        </pluginManagement>
+    </build>
     <dependencyManagement>
       <dependencies>
         <dependency>

simpleclient/src/main/java/io/prometheus/client/Counter.java

@@ -207,7 +207,7 @@ public void inc(double amt) {
      *
      * @param amt            same as in {@link #inc(double)}
      * @param exemplarLabels list of name/value pairs, as documented in {@link Exemplar#Exemplar(double, String...)}.
-     *                       A commonly used name is {@link Exemplar#TRACE_ID}.
+     *                       A commonly used name is {@code "trace_id"}.
      *                       Calling {@code incWithExemplar(amt)} means that an exemplar without labels will be created.
      *                       Calling {@code incWithExemplar(amt, (String[]) null)} is equivalent
      *                       to calling {@code inc(amt)}.

simpleclient/src/main/java/io/prometheus/client/Histogram.java

@@ -366,7 +366,7 @@ public void observe(double amt) {
      *
      * @param amt            same as in {@link #observe(double)} (double)}
      * @param exemplarLabels list of name/value pairs, as documented in {@link Exemplar#Exemplar(double, String...)}.
-     *                       A commonly used name is {@link Exemplar#TRACE_ID}.
+     *                       A commonly used name is {@code "trace_id"}.
      *                       Calling {@code observeWithExemplar(amt)} means that an exemplar without labels is created.
      *                       Calling {@code observeWithExemplar(amt, (String[]) null)} is equivalent
      *                       to calling {@code observe(amt)}.

simpleclient/src/main/java/io/prometheus/client/exemplars/DefaultExemplarSampler.java

@@ -2,16 +2,16 @@
 
 import io.prometheus.client.exemplars.tracer.common.SpanContextSupplier;
 
-import static io.prometheus.client.exemplars.Exemplar.SPAN_ID;
-import static io.prometheus.client.exemplars.Exemplar.TRACE_ID;
-
 /**
  * Default Exemplar sampler.
  * <p/>
  * Keeps each Exemplar for a minimum of ~7 seconds, then samples a new one.
  */
 public class DefaultExemplarSampler implements ExemplarSampler {
 
+  private static final String SPAN_ID = "span_id";
+  private static final String TRACE_ID = "trace_id";
+
   private final SpanContextSupplier spanContextSupplier;
   // Choosing a prime number for the retention interval makes behavior more predictable,
   // because it is unlikely that retention happens at the exact same time as a Prometheus scrape.
@@ -43,10 +43,10 @@ private Exemplar doSample(double value, Exemplar previous) {
     long timestampMs = clock.currentTimeMillis();
     if (previous == null || previous.getTimestampMs() == null
         || timestampMs - previous.getTimestampMs() > minRetentionIntervalMs) {
-      String traceId = spanContextSupplier.getTraceId();
       String spanId = spanContextSupplier.getSpanId();
+      String traceId = spanContextSupplier.getTraceId();
       if (traceId != null && spanId != null) {
-        return new Exemplar(value, timestampMs, TRACE_ID, traceId, SPAN_ID, spanId);
+        return new Exemplar(value, timestampMs, SPAN_ID, spanId, TRACE_ID, traceId);
       }
     }
     return null;

simpleclient/src/main/java/io/prometheus/client/exemplars/Exemplar.java

@@ -9,14 +9,11 @@
  */
 public class Exemplar {
 
-  public static final String TRACE_ID = "trace_id";
-  public static final String SPAN_ID = "span_id";
-
   private final String[] labels;
   private final double value;
   private final Long timestampMs;
 
-  private static final Pattern labelNameRegex = Pattern.compile("[a-zA-Z_]\\w*"); // \w is [a-zA-Z_0-9]
+  private static final Pattern labelNameRegex = Pattern.compile("[a-zA-Z_][a-zA-Z_0-9]*");
 
   /**
    * Create an Exemplar without a timestamp

simpleclient/src/main/java/io/prometheus/client/exemplars/ExemplarConfig.java

@@ -18,6 +18,10 @@ public class ExemplarConfig {
   }
 
   /**
+   * Set the exemplar sampler used when building Counters.
+   * <p>
+   * This must be called before a Counter is created.
+   *
    * @param counterExemplarSampler will be used by default when creating new {@code Counter} metrics,
    *                               unless {@link #disableExemplarSamplers()} was called.
    */
@@ -29,6 +33,10 @@ public static void setCounterExemplarSampler(CounterExemplarSampler counterExemp
   }
 
   /**
+   * Set the exemplar sampler used when building Histograms.
+   * <p>
+   * This must be called before a Histogram is created.
+   *
    * @param histogramExemplarSampler will be used by default when creating new {@code Histogram} metrics,
    *                                 unless {@link #disableExemplarSamplers()} was called.
    */
@@ -41,8 +49,11 @@ public static void setHistogramExemplarSampler(HistogramExemplarSampler histogra
 
   /**
    * Disable the implicit exemplar samplers by default.
+   * <p>
    * Exemplars can still be enabled for individual metrics in the metric builder,
    * or they can be provided explicitly for individual observations with the {@code ...withExemplar()} methods.
+   * <p>
+   * This must be called before a Counter or a Histogram is created.
    */
   public static void disableExemplarSamplers() {
     enabled = false;

simpleclient/src/test/java/io/prometheus/client/exemplars/DefaultExemplarSamplerTest.java

@@ -8,13 +8,14 @@
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.concurrent.atomic.AtomicReference;
 
-import static io.prometheus.client.exemplars.Exemplar.SPAN_ID;
-import static io.prometheus.client.exemplars.Exemplar.TRACE_ID;
 import static java.lang.Double.NEGATIVE_INFINITY;
 import static java.lang.Double.POSITIVE_INFINITY;
 
 public class DefaultExemplarSamplerTest {
 
+  private static final String SPAN_ID = "span_id";
+  private static final String TRACE_ID = "trace_id";
+
   final AtomicReference<String> traceId = new AtomicReference<String>();
   final AtomicReference<String> spanId = new AtomicReference<String>();
   final AtomicLong timestamp = new AtomicLong();

simpleclient/src/test/java/io/prometheus/client/exemplars/ExemplarTest.java

@@ -7,11 +7,11 @@
 import java.util.Map;
 import java.util.TreeMap;
 
-import static io.prometheus.client.exemplars.Exemplar.SPAN_ID;
-import static io.prometheus.client.exemplars.Exemplar.TRACE_ID;
-
 public class ExemplarTest {
 
+  private final String SPAN_ID = "span_id";
+  private final String TRACE_ID = "trace_id";
+
   @Test
   public void testCompleteExemplar() {
     double value = 42;

simpleclient_common/src/main/java/io/prometheus/client/exporter/common/TextFormat.java

@@ -267,7 +267,7 @@ public static void writeOpenMetrics100(Writer writer, Enumeration<Collector.Metr
     writer.write("# EOF\n");
   }
 
-  private static void omWriteTimestamp(Writer writer, long timestampMs) throws IOException {
+  static void omWriteTimestamp(Writer writer, long timestampMs) throws IOException {
     writer.write(Long.toString(timestampMs / 1000L));
     writer.write(".");
     long ms = timestampMs % 1000;