add Exemplar support for OpenTelemetry tracing (review)

Author: fstab

benchmark/README.md

@@ -12,6 +12,7 @@ The main outcomes of the benchmarks:
 * Simpleclient Histograms are 10-100X faster than Codahale and original client Summaries.
 * Simpleclient `Gauge.Child.set` is relatively slow, especially when done concurrently.
 * Label lookups in both Prometheus clients are relatively slow.
+* The `System.currentTimeMillis()` call in the `DefaultExemplarSampler` takes about 17ns on Linux.
 
 Accordingly, in terms of client instrumentation performance I suggest the following:
 * It's cheap to extensively instrument your code with Simpleclient Counters/Gauges/Summaries without labels, or Codahale Counters.
@@ -158,4 +159,12 @@ The closest to the original client's `Summary` is Codahale's
 Note the high error bars for the original client, it got slower with each iteration
 so I suspect a flaw in the test setup.
 
+### Exemplars
 
+The `ExemplarsBenchmark` was run on a Linux laptop with a 4 Core Intel i7-8550U CPU with OpenJDK 1.8.0_282-b08.
+
+    java -jar target/benchmarks.jar ExemplarsBenchmark
+    Benchmark                                               Mode  Samples   Score   Error  Units
+    i.p.b.ExemplarsBenchmark.testCounter                    avgt      200  28.252 ± 0.312  ns/op
+    i.p.b.ExemplarsBenchmark.testCounterWithExemplars       avgt      200  46.042 ± 0.781  ns/op
+    i.p.b.ExemplarsBenchmark.testCounterWithoutExemplars    avgt      200  29.322 ± 0.475  ns/op

benchmark/pom.xml

@@ -49,7 +49,7 @@
         <dependency>
             <groupId>io.prometheus</groupId>
             <artifactId>simpleclient</artifactId>
-            <version>${project.version}</version>
+            <version>0.10.1-SNAPSHOT</version>
         </dependency>
         <dependency>
           <groupId>com.codahale.metrics</groupId>

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

@@ -1,8 +1,8 @@
 package io.prometheus.benchmark;
 
 import io.prometheus.client.Counter;
-import io.prometheus.client.exemplars.impl.DefaultExemplarSampler;
-import io.prometheus.client.exemplars.tracer.common.SpanContext;
+import io.prometheus.client.exemplars.DefaultExemplarSampler;
+import io.prometheus.client.exemplars.tracer.common.SpanContextSupplier;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
 import org.openjdk.jmh.annotations.Mode;
@@ -33,7 +33,7 @@ public void setup() {
         .name("counter_with_exemplars_total")
         .help("Total number of requests.")
         .labelNames("path")
-        .withExemplars(new DefaultExemplarSampler(new MockSpanContext()))
+        .withExemplars(new DefaultExemplarSampler(new MockSpanContextSupplier()))
         .create();
 
     counterWithoutExemplars = Counter.build()
@@ -65,7 +65,7 @@ public void testCounterWithoutExemplars() {
     counterWithoutExemplars.labels("test").inc();
   }
 
-  private static class MockSpanContext implements SpanContext {
+  private static class MockSpanContextSupplier implements SpanContextSupplier {
 
     @Override
     public String getTraceId() {

exemplars_parent/exemplars/src/main/java/io/prometheus/client/exemplars/api/ExemplarSampler.java

@@ -43,7 +43,7 @@
     </developers>
 
     <modules>
-        <module>exemplars_parent</module>
+        <module>tracer_parent</module>
         <module>simpleclient</module>
         <module>simpleclient_common</module>
         <module>simpleclient_caffeine</module>

exemplars_parent/exemplars/src/test/java/io/prometheus/client/exemplars/api/ExemplarTest.java

@@ -37,10 +37,10 @@
   <dependencies>
     <!-- The simpleclient has no required 3rd party runtime dependencies by design, so that
          it can be included into any other project without having to worry about conflicts.
-         All transitive dependencies of exemplars are scoped as provided and optional at runtime. -->
+         All transitive dependencies of tracer libraries are scoped as provided and optional at runtime. -->
     <dependency>
       <groupId>io.prometheus</groupId>
-      <artifactId>exemplars</artifactId>
+      <artifactId>tracer</artifactId>
       <version>${project.version}</version>
     </dependency>
     <!-- Test Dependencies Follow -->

pom.xml

@@ -258,7 +258,6 @@ private class Item {
         public final double value;
         public int g;
         public final int delta;
-        // TODO Exemplars here would be cool :)
 
         public Item(double value, int lower_delta, int delta) {
             this.value = value;

simpleclient/pom.xml

@@ -1,7 +1,7 @@
 
 package io.prometheus.client;
 
-import io.prometheus.client.exemplars.api.Exemplar;
+import io.prometheus.client.exemplars.Exemplar;
 
 import java.util.ArrayList;
 import java.util.List;

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

@@ -1,9 +1,9 @@
 package io.prometheus.client;
 
-import io.prometheus.client.exemplars.api.CounterExemplarSampler;
-import io.prometheus.client.exemplars.api.Exemplar;
-import io.prometheus.client.exemplars.api.ExemplarConfig;
-import io.prometheus.client.exemplars.api.Value;
+import io.prometheus.client.exemplars.CounterExemplarSampler;
+import io.prometheus.client.exemplars.Exemplar;
+import io.prometheus.client.exemplars.ExemplarConfig;
+import io.prometheus.client.exemplars.Value;
 
 import java.util.ArrayList;
 import java.util.Collections;
@@ -101,6 +101,9 @@ public Counter create() {
       return new Counter(this);
     }
 
+    /**
+     * Enable exemplars and provide a custom {@link CounterExemplarSampler}.
+     */
     public Builder withExemplars(CounterExemplarSampler exemplarSampler) {
       if (exemplarSampler == null) {
         throw new NullPointerException();
@@ -109,10 +112,16 @@ public Builder withExemplars(CounterExemplarSampler exemplarSampler) {
       return this;
     }
 
+    /**
+     * Enable exemplars using the default {@link CounterExemplarSampler} as configured in {@link ExemplarConfig}.
+     */
     public Builder withExemplars() {
       return withExemplars(ExemplarConfig.getDefaultExemplarSampler());
     }
 
+    /**
+     * Disable exemplars.
+     */
     public Builder withoutExemplars() {
       return withExemplars(ExemplarConfig.getNoopExemplarSampler());
     }

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

@@ -1,8 +1,8 @@
 package io.prometheus.client;
 
-import io.prometheus.client.exemplars.api.Exemplar;
-import io.prometheus.client.exemplars.api.ExemplarConfig;
-import io.prometheus.client.exemplars.api.HistogramExemplarSampler;
+import io.prometheus.client.exemplars.Exemplar;
+import io.prometheus.client.exemplars.ExemplarConfig;
+import io.prometheus.client.exemplars.HistogramExemplarSampler;
 
 import java.io.Closeable;
 import java.util.ArrayList;
@@ -138,6 +138,9 @@ public Builder exponentialBuckets(double start, double factor, int count) {
       return this;
     }
 
+    /**
+     * Enable exemplars and provide a custom {@link HistogramExemplarSampler}.
+     */
     public Builder withExemplars(HistogramExemplarSampler exemplarSampler) {
       if (exemplarSampler == null) {
         throw new NullPointerException();
@@ -146,10 +149,16 @@ public Builder withExemplars(HistogramExemplarSampler exemplarSampler) {
       return this;
     }
 
+    /**
+     * Enable exemplars using the default {@link HistogramExemplarSampler} as configured in {@link ExemplarConfig}.
+     */
     public Builder withExemplars() {
       return withExemplars(ExemplarConfig.getDefaultExemplarSampler());
     }
 
+    /**
+     * Disable exemplars.
+     */
     public Builder withoutExemplars() {
       return withExemplars(ExemplarConfig.getNoopExemplarSampler());
     }

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

@@ -1,4 +1,4 @@
-package io.prometheus.client.exemplars.api;
+package io.prometheus.client.exemplars;
 
 /**
  * Exemplar sampler for counter metrics.

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

@@ -1,12 +1,12 @@
-package io.prometheus.client.exemplars.impl;
+package io.prometheus.client.exemplars;
 
-import io.prometheus.client.exemplars.api.Exemplar;
-import io.prometheus.client.exemplars.api.ExemplarSampler;
-import io.prometheus.client.exemplars.api.Value;
-import io.prometheus.client.exemplars.tracer.common.SpanContext;
+import io.prometheus.client.exemplars.Exemplar;
+import io.prometheus.client.exemplars.ExemplarSampler;
+import io.prometheus.client.exemplars.Value;
+import io.prometheus.client.exemplars.tracer.common.SpanContextSupplier;
 
-import static io.prometheus.client.exemplars.api.Exemplar.SPAN_ID;
-import static io.prometheus.client.exemplars.api.Exemplar.TRACE_ID;
+import static io.prometheus.client.exemplars.Exemplar.SPAN_ID;
+import static io.prometheus.client.exemplars.Exemplar.TRACE_ID;
 
 /**
  * Default Exemplar sampler.
@@ -15,20 +15,20 @@
  */
 public class DefaultExemplarSampler implements ExemplarSampler {
 
-  private final SpanContext spanContext;
+  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.
   private final long minRetentionIntervalMs = 7109;
   private final Clock clock;
 
-  public DefaultExemplarSampler(SpanContext spanContext) {
-    this.spanContext = spanContext;
+  public DefaultExemplarSampler(SpanContextSupplier spanContextSupplier) {
+    this.spanContextSupplier = spanContextSupplier;
     this.clock = new SystemClock();
   }
 
   // for unit tests only
-  DefaultExemplarSampler(SpanContext spanContext, Clock clock) {
-    this.spanContext = spanContext;
+  DefaultExemplarSampler(SpanContextSupplier spanContextSupplier, Clock clock) {
+    this.spanContextSupplier = spanContextSupplier;
     this.clock = clock;
   }
 
@@ -44,9 +44,10 @@ public Exemplar sample(double value, double bucketFrom, double bucketTo, Exempla
 
   private Exemplar doSample(double value, Exemplar previous) {
     long timestampMs = clock.currentTimeMillis();
-    if (previous == null || timestampMs - previous.getTimestampMs() > minRetentionIntervalMs) {
-      String traceId = spanContext.getTraceId();
-      String spanId = spanContext.getSpanId();
+    if (previous == null || previous.getTimestampMs() == null
+        || timestampMs - previous.getTimestampMs() > minRetentionIntervalMs) {
+      String traceId = spanContextSupplier.getTraceId();
+      String spanId = spanContextSupplier.getSpanId();
       if (traceId != null && spanId != null) {
         return new Exemplar(value, timestampMs, TRACE_ID, traceId, SPAN_ID, spanId);
       }