Add version to the InstrumenterBuilder and Instrumenter (#4611)

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java

@@ -58,7 +58,34 @@ public static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST, RESPONSE> builder
  OpenTelemetry openTelemetry,
  String instrumentationName,
  SpanNameExtractor<? super REQUEST> spanNameExtractor) {
- return new InstrumenterBuilder<>(openTelemetry, instrumentationName, spanNameExtractor);
+ return new InstrumenterBuilder<>(
+ openTelemetry, instrumentationName, InstrumentationVersion.VERSION, spanNameExtractor);
+ }
+
+ /**
+ * Returns a new {@link InstrumenterBuilder}.
+ *
+ * <p>The {@code instrumentationName} is the name of the instrumentation library, not the name of
+ * the instrument*ed* library. The value passed in this parameter should uniquely identify the
+ * instrumentation library so that during troubleshooting it's possible to pinpoint what tracer
+ * produced problematic telemetry.
+ *
+ * <p>The {@code instrumentationVersion} is the version of the instrumentation library, not the
+ * version of the instrument*ed* library.
+ *
+ * <p>In this project we use a convention to encode the minimum supported version of the
+ * instrument*ed* library into the instrumentation name, for example {@code
+ * io.opentelemetry.apache-httpclient-4.0}. This way, if there are different instrumentations for
+ * different library versions it's easy to find out which instrumentations produced the telemetry
+ * data.
+ */
+ public static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST, RESPONSE> builder(
+ OpenTelemetry openTelemetry,
+ String instrumentationName,
+ String instrumentationVersion,
+ SpanNameExtractor<? super REQUEST> spanNameExtractor) {
+ return new InstrumenterBuilder<>(
+ openTelemetry, instrumentationName, instrumentationVersion, spanNameExtractor);
  }
 
  private static final SupportabilityMetrics supportability = SupportabilityMetrics.instance();
@@ -82,7 +109,7 @@ public static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST, RESPONSE> builder
  Instrumenter(InstrumenterBuilder<REQUEST, RESPONSE> builder) {
  this.instrumentationName = builder.instrumentationName;
  this.tracer =
- builder.openTelemetry.getTracer(instrumentationName, InstrumentationVersion.VERSION);
+ builder.openTelemetry.getTracer(instrumentationName, builder.instrumentationVersion);
  this.spanNameExtractor = builder.spanNameExtractor;
  this.spanKindExtractor = builder.spanKindExtractor;
  this.spanStatusExtractor = builder.spanStatusExtractor;

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

@@ -42,6 +42,7 @@ public final class InstrumenterBuilder<REQUEST, RESPONSE> {
  final OpenTelemetry openTelemetry;
  final Meter meter;
  final String instrumentationName;
+ final String instrumentationVersion;
  final SpanNameExtractor<? super REQUEST> spanNameExtractor;
 
  final List<SpanLinksExtractor<? super REQUEST>> spanLinksExtractors = new ArrayList<>();
@@ -63,11 +64,13 @@ public final class InstrumenterBuilder<REQUEST, RESPONSE> {
  InstrumenterBuilder(
  OpenTelemetry openTelemetry,
  String instrumentationName,
+ String instrumentationVersion,
  SpanNameExtractor<? super REQUEST> spanNameExtractor) {
  this.openTelemetry = openTelemetry;
  // TODO(anuraaga): Retrieve from openTelemetry when not alpha anymore.
  this.meter = GlobalMeterProvider.get().get(instrumentationName);
  this.instrumentationName = instrumentationName;
+ this.instrumentationVersion = instrumentationVersion;
  this.spanNameExtractor = spanNameExtractor;
  }
 

instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterTest.java

@@ -22,6 +22,7 @@
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.ContextKey;
 import io.opentelemetry.context.propagation.TextMapGetter;
+import io.opentelemetry.instrumentation.api.InstrumentationVersion;
 import io.opentelemetry.instrumentation.api.instrumenter.db.DbAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.http.HttpClientAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.http.HttpServerAttributesExtractor;
@@ -641,6 +642,53 @@ void instrumentationTypeDetected_generic() {
  assertThat(SpanKey.PRODUCER.fromContextOrNull(context)).isNull();
  }
 
+ @Test
+ void instrumentationVersion_default() {
+ InstrumenterBuilder<Map<String, String>, Map<String, String>> builder =
+ Instrumenter.builder(otelTesting.getOpenTelemetry(), "test", name -> "span");
+
+ Instrumenter<Map<String, String>, Map<String, String>> instrumenter = builder.newInstrumenter();
+
+ Context context = instrumenter.start(Context.root(), Collections.emptyMap());
+ assertThat(Span.fromContext(context)).isNotNull();
+
+ instrumenter.end(context, Collections.emptyMap(), Collections.emptyMap(), null);
+
+ otelTesting
+ .assertTraces()
+ .hasTracesSatisfyingExactly(
+ trace ->
+ trace.hasSpansSatisfyingExactly(
+ span ->
+ span.hasName("span")
+ .hasInstrumentationLibraryInfo(
+ InstrumentationLibraryInfo.create(
+ "test", InstrumentationVersion.VERSION))));
+ }
+
+ @Test
+ void instrumentationVersion_custom() {
+ InstrumenterBuilder<Map<String, String>, Map<String, String>> builder =
+ Instrumenter.builder(otelTesting.getOpenTelemetry(), "test", "1.0", name -> "span");
+
+ Instrumenter<Map<String, String>, Map<String, String>> instrumenter = builder.newInstrumenter();
+
+ Context context = instrumenter.start(Context.root(), Collections.emptyMap());
+ assertThat(Span.fromContext(context)).isNotNull();
+
+ instrumenter.end(context, Collections.emptyMap(), Collections.emptyMap(), null);
+
+ otelTesting
+ .assertTraces()
+ .hasTracesSatisfyingExactly(
+ trace ->
+ trace.hasSpansSatisfyingExactly(
+ span ->
+ span.hasName("span")
+ .hasInstrumentationLibraryInfo(
+ InstrumentationLibraryInfo.create("test", "1.0"))));
+ }
+
  private static void validateInstrumentationTypeSpanPresent(SpanKey spanKey, Context context) {
  Span span = Span.fromContext(context);