add Exemplar support for OpenTelemetry tracing (review)

Author: fstab

.circleci/config.yml

@@ -14,6 +14,5 @@ jobs:
           paths:
             - ~/.m2
           key: maven-dependencies-{{ checksum "pom.xml" }}
-      - run: mvn verify
 orbs:
-  prometheus: prometheus/prometheus@0.11.0
+  prometheus: prometheus/prometheus@0.11.0

.gitignore

@@ -12,4 +12,4 @@ target/
 simpleclient_pushgateway/mockserver.log
 simpleclient_pushgateway/mockserver_request.log
 nb-configuration.xml
-
+dependency-reduced-pom.xml

README.md

@@ -334,25 +334,25 @@ Note that this is an example application for a unit test, so durations don't rep
 By default, Exemplars are enabled if OpenTelemetry tracing is detected. You can disable this globally with:
 
 ```java
-ExemplarConfig.disableByDefault();
+ExemplarConfig.disableExemplars();
 ```
 
-If you want to enable Exemplars only for a single metric, use `withExemplarSampler()` in the metric builder.
+If you want to enable Exemplars only for a single metric, use `withExemplars()` in the metric builder.
 
 ```java
-// This also works with Gauges, Histograms, and Summaries.
+// The same API is also provided by Histograms
 Counter labelsCustomExemplar = Counter.build()
     .name("number_of_events_total")
     .help("help")
-    .withExemplarSampler(new MyExemplarSampler())
+    .withExemplars()
     ...
     .register();
 ```
 
 Likewise, you can disable Exemplars for a single metric like this:
 
 ```java
-// This also works with Gauges, Histograms, and Summaries.
+// The same API is also provided by Histograms
 Counter labelsCustomExemplar = Counter.build()
     .name("number_of_events_total")
     .help("help")
@@ -370,23 +370,31 @@ You might want to implement your own Exemplar sampler that provides more interes
 In order to do so, just implement the following interfaces:
 
 * `CounterExemplarSampler`
-* `GaugeExemplarSampler`
 * `HistogramExemplarSampler`
-* `SummaryExemplarSampler`
 
 You can set your implementations as default like this:
 
 ```java
 ExemplarConfig.setDefaultCounterExemplarSampler(mySampler);
-ExemplarConfig.setDefaultGaugeExemplarSampler(mySampler);
 ExemplarConfig.setDefaultHistogramExemplarSampler(mySampler);
-ExemplarConfig.setDefaultSummaryExemplarSampler(mySampler);
+```
+
+If you don't want to use your implementation as a global default, you can also set it for a single metric like this:
+
+```java
+// The same API is also provided by Histograms
+Counter labelsCustomExemplar = Counter.build()
+    .name("number_of_events_total")
+    .help("help")
+    .withExemplars(new MyExemplarSampler())
+    ...
+    .register();
 ```
 
 ### Implement Support for Other Tracing Vendors
 
-Version 0.11.0 implements support for OpenTelemetry. If you are a vendor for another distributed tracer,
-please create a pull request adding support for your system. The idea is that copy-and-paste the
+Version 0.11.0 provides support for OpenTelemetry. If you are a vendor for another distributed tracer,
+please create a pull request adding support for your system. The idea is to copy-and-paste the
 `tracer_otel` module and modify it for your needs. If this turns out to be too simplistic, please create
 a GitHub issue and let us know what you need.
 

benchmark/pom.xml

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

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

@@ -0,0 +1,80 @@
+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 org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+
+import java.util.concurrent.TimeUnit;
+
+@State(Scope.Benchmark)
+public class ExemplarsBenchmark {
+
+  private Counter counter;
+  private Counter counterWithExemplars;
+  private Counter counterWithoutExemplars;
+
+  @Setup
+  public void setup() {
+
+    counter = Counter.build()
+        .name("counter_total")
+        .help("Total number of requests.")
+        .labelNames("path")
+        .create();
+
+    counterWithExemplars = Counter.build()
+        .name("counter_with_exemplars_total")
+        .help("Total number of requests.")
+        .labelNames("path")
+        .withExemplars(new DefaultExemplarSampler(new MockSpanContext()))
+        .create();
+
+    counterWithoutExemplars = Counter.build()
+        .name("counter_without_exemplars_total")
+        .help("Total number of requests.")
+        .labelNames("path")
+        .withoutExemplars()
+        .create();
+  }
+
+  @Benchmark
+  @BenchmarkMode({Mode.AverageTime})
+  @OutputTimeUnit(TimeUnit.NANOSECONDS)
+  public void testCounter() {
+    counter.labels("test").inc();
+  }
+
+  @Benchmark
+  @BenchmarkMode({Mode.AverageTime})
+  @OutputTimeUnit(TimeUnit.NANOSECONDS)
+  public void testCounterWithExemplars() {
+    counterWithExemplars.labels("test").inc();
+  }
+
+  @Benchmark
+  @BenchmarkMode({Mode.AverageTime})
+  @OutputTimeUnit(TimeUnit.NANOSECONDS)
+  public void testCounterWithoutExemplars() {
+    counterWithoutExemplars.labels("test").inc();
+  }
+
+  private static class MockSpanContext implements SpanContext {
+
+    @Override
+    public String getTraceId() {
+      return "trace-id";
+    }
+
+    @Override
+    public String getSpanId() {
+      return "span-id";
+    }
+  }
+}

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

@@ -6,12 +6,13 @@
 public interface CounterExemplarSampler {
 
   /**
-   * @param value    the new counter value.
-   *                 Note that {@link Value#get()} might be an expensive operation. The implementation
-   *                 of {@link CounterExemplarSampler} should call {@link Value#get()} only if needed.
-   * @param previous the previously sampled exemplar, or {@code null} if there is none.
+   * @param increment     the value added to the counter on this event
+   * @param newTotalValue the new total counter value after adding the increment.
+   *                      Note that {@link Value#get()} might be an expensive operation. The implementation
+   *                      of {@link CounterExemplarSampler} should call {@link Value#get()} only if needed.
+   * @param previous      the previously sampled exemplar, or {@code null} if there is none.
    * @return an Exemplar to be sampled, or {@code null} if the previous exemplar does not need to be updated.
    * Returning {@code null} and returning {@code previous} is equivalent.
    */
-  Exemplar sample(Value value, Exemplar previous);
+  Exemplar sample(double increment, Value newTotalValue, Exemplar previous);
 }

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

@@ -1,48 +1,86 @@
 package io.prometheus.client.exemplars.api;
 
+import java.util.Arrays;
+
 /**
  * Immutable data class holding an Exemplar.
  */
 public class Exemplar {
 
-  private final String traceId;
-  private final String spanId;
+  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;
 
-  public Exemplar(String traceId, String spanId, double value, long timestampMs) {
-    if (traceId == null) {
-      throw new NullPointerException("traceId");
-    }
-    if (spanId == null) {
-      throw new NullPointerException("spanId");
-    }
-    this.traceId = traceId;
-    this.spanId = spanId;
+  /**
+   * Create an Exemplar without a timestamp
+   *
+   * @param value  the observed value
+   * @param labels name/value pairs. Expecting an even number of strings. The combined length of the label names and
+   *               values must not exceed 128 UTF-8 characters. Neither a label name nor a label value may be null.
+   */
+  public Exemplar(double value, String... labels) {
+    this(value, 0, labels);
+  }
+
+  /**
+   * Create an Exemplar
+   *
+   * @param value       the observed value
+   * @param timestampMs as in {@link System#currentTimeMillis()}
+   * @param labels      name/value pairs. Expecting an even number of strings. The combined length of the
+   *                    label names and values must not exceed 128 UTF-8 characters. Neither a label name
+   *                    nor a label value may be null.
+   */
+  public Exemplar(double value, long timestampMs, String... labels) {
+    validateLabels(labels);
+    this.labels = Arrays.copyOf(labels, labels.length);
     this.value = value;
     this.timestampMs = timestampMs;
   }
 
-  public Exemplar(String traceId, String spanId, double value) {
-    this(traceId, spanId, value, System.currentTimeMillis());
+  public int getNumberOfLabels() {
+    return labels.length / 2;
   }
 
-  public String getTraceId() {
-    return traceId;
+  public String getLabelName(int i) {
+    return labels[2 * i];
   }
 
-  public String getSpanId() {
-    return spanId;
+  public String getLabelValue(int i) {
+    return labels[2 * i + 1];
   }
 
   public double getValue() {
     return value;
   }
 
+  /**
+   * @return 0 means no timestamp.
+   */
   public long getTimestampMs() {
     return timestampMs;
   }
 
+  private void validateLabels(String... labels) {
+    if (labels.length % 2 != 0) {
+      throw new IllegalArgumentException("labels are name/value pairs, expecting an even number");
+    }
+    int charsTotal = 0;
+    for (int i = 0; i < labels.length; i++) {
+      if (labels[i] == null) {
+        throw new IllegalArgumentException("labels[" + i + "] is null");
+      }
+      charsTotal += labels[i].length();
+    }
+    if (charsTotal > 128) {
+      throw new IllegalArgumentException(
+          "the combined length of the label names and values must not exceed 128 UTF-8 characters");
+    }
+  }
+
   @Override
   public boolean equals(Object obj) {
     if (this == obj) {
@@ -52,16 +90,14 @@ public boolean equals(Object obj) {
       return false;
     }
     Exemplar other = (Exemplar) obj;
-    return traceId.equals(other.traceId) &&
-        spanId.equals(other.spanId) &&
+    return Arrays.equals(this.labels, other.labels) &&
         Double.compare(other.value, value) == 0 &&
         timestampMs == other.timestampMs;
   }
 
   @Override
   public int hashCode() {
-    int hash = traceId.hashCode();
-    hash = 37 * hash + spanId.hashCode();
+    int hash = Arrays.hashCode(labels);
     long d = Double.doubleToLongBits(value);
     hash = 37 * hash + (int) (d ^ (d >>> 32));
     hash = 37 * hash + (int) timestampMs;