New Instrumenter API

gradle/enforcement/checkstyle.xml

@@ -234,7 +234,8 @@
         value="Method type name ''{0}'' must match pattern ''{1}''."/>
     </module>
     <module name="InterfaceTypeParameterName">
-      <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][a-zA-Z0-9]*[T]$)"/>
+      <!-- modified from default Google Java Style -->
+      <property name="format" value="^[A-Z]+[0-9]?$"/>
       <message key="name.invalidPattern"
         value="Interface type name ''{0}'' must match pattern ''{1}''."/>
     </module>

instrumentation-api/instrumentation-api.gradle

@@ -33,4 +33,5 @@ dependencies {
   testImplementation deps.mockito
   testImplementation deps.assertj
   testImplementation deps.awaitility
+  testImplementation deps.opentelemetrySdkTesting
 }

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

@@ -0,0 +1,44 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.AttributesBuilder;
+
+/**
+ * Extractor of {@link io.opentelemetry.api.common.Attributes} for a given request and response.
+ * Will be called {@linkplain #onStart(AttributesBuilder, Object) on start} with just the {@link
+ * REQUEST} and again {@linkplain #onEnd(AttributesBuilder, Object, Object) on end} with both {@link
+ * REQUEST} and {@link RESPONSE} to allow populating attributes at each stage of a request's
+ * lifecycle. It is best to populate as much as possible in {@link #onStart(AttributesBuilder,
+ * Object)} to have it available during sampling.
+ *
+ * @see HttpAttributesExtractor
+ * @see NetAttributesExtractor
+ */
+public abstract class AttributesExtractor<REQUEST, RESPONSE> {
+  /**
+   * Extracts attributes from the {@link REQUEST} into the {@link AttributesBuilder} at the
+   * beginning of a request.
+   */
+  protected abstract void onStart(AttributesBuilder attributes, REQUEST request);
+
+  /**
+   * Extracts attributes from the {@link REQUEST} and {@link RESPONSE} into the {@link
+   * AttributesBuilder} at the end of a request.
+   */
+  protected abstract void onEnd(AttributesBuilder attributes, REQUEST request, RESPONSE response);
+
+  /**
+   * Sets the {@code value} with the given {@code key} to the {@link AttributesBuilder} if {@code
+   * value} is not {@code null}.
+   */
+  protected static <T> void set(AttributesBuilder attributes, AttributeKey<T> key, T value) {
+    if (value != null) {
+      attributes.put(key, value);
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.propagation.ContextPropagators;
+import io.opentelemetry.context.propagation.TextMapSetter;
+import java.util.List;
+
+final class ClientInstrumenter<REQUEST, RESPONSE> extends Instrumenter<REQUEST, RESPONSE> {
+
+  private final ContextPropagators propagators;
+  private final TextMapSetter<REQUEST> setter;
+
+  ClientInstrumenter(
+      Tracer tracer,
+      SpanNameExtractor<? super REQUEST> spanNameExtractor,
+      SpanKindExtractor<? super REQUEST> spanKindExtractor,
+      SpanStatusExtractor<? super REQUEST, ? super RESPONSE> spanStatusExtractor,
+      List<? extends AttributesExtractor<? super REQUEST, ? super RESPONSE>> attributesExtractors,
+      ErrorCauseExtractor errorCauseExtractor,
+      ContextPropagators propagators,
+      TextMapSetter<REQUEST> setter) {
+    super(
+        tracer,
+        spanNameExtractor,
+        spanKindExtractor,
+        spanStatusExtractor,
+        attributesExtractors,
+        errorCauseExtractor);
+    this.propagators = propagators;
+    this.setter = setter;
+  }
+
+  @Override
+  public Context start(Context parentContext, REQUEST request) {
+    Context newContext = super.start(parentContext, request);
+    propagators.getTextMapPropagator().inject(newContext, request, setter);
+    return newContext;
+  }
+}

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

@@ -0,0 +1,23 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import io.opentelemetry.api.trace.StatusCode;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+final class DefaultSpanStatusExtractor<REQUEST, RESPONSE>
+    implements SpanStatusExtractor<REQUEST, RESPONSE> {
+
+  static final SpanStatusExtractor<Object, Object> INSTANCE = new DefaultSpanStatusExtractor<>();
+
+  @Override
+  public StatusCode extract(REQUEST request, RESPONSE response, @Nullable Throwable error) {
+    if (error != null) {
+      return StatusCode.ERROR;
+    }
+    return StatusCode.UNSET;
+  }
+}

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

@@ -0,0 +1,23 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+/**
+ * Extractor of the root cause of a {@link Throwable}. When instrumenting a library which wraps user
+ * exceptions with a framework exception, generally for propagating checked exceptions across
+ * unchecked boundaries, it is recommended to override this to unwrap back to the user exception.
+ */
+public interface ErrorCauseExtractor {
+  Throwable extractCause(Throwable error);
+
+  /**
+   * Returns a {@link ErrorCauseExtractor} which unwraps common standard library wrapping
+   * exceptions.
+   */
+  static ErrorCauseExtractor jdk() {
+    return JdkErrorCauseExtractor.INSTANCE;
+  }
+}

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

@@ -0,0 +1,107 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import io.opentelemetry.api.common.AttributesBuilder;
+import io.opentelemetry.semconv.trace.attributes.SemanticAttributes;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * Extractor of <a
+ * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md">HTTP
+ * attributes</a>. Instrumentation of HTTP server or client frameworks should extend this class,
+ * defining {@link REQUEST} and {@link RESPONSE} with the actual request / response types of the
+ * instrumented library. If an attribute is not available in this library, it is appropriate to
+ * return {@code null} from the protected attribute methods, but implement as many as possible for
+ * best compliance with the OpenTelemetry specification.
+ */
+public abstract class HttpAttributesExtractor<REQUEST, RESPONSE>
+    extends AttributesExtractor<REQUEST, RESPONSE> {
+
+  @Override
+  protected final void onStart(AttributesBuilder attributes, REQUEST request) {
+    set(attributes, SemanticAttributes.HTTP_METHOD, method(request));
+    set(attributes, SemanticAttributes.HTTP_URL, url(request));
+    set(attributes, SemanticAttributes.HTTP_TARGET, target(request));
+    set(attributes, SemanticAttributes.HTTP_HOST, host(request));
+    set(attributes, SemanticAttributes.HTTP_ROUTE, route(request));
+    set(attributes, SemanticAttributes.HTTP_SCHEME, scheme(request));
+    set(attributes, SemanticAttributes.HTTP_USER_AGENT, userAgent(request));
+  }
+
+  @Override
+  protected final void onEnd(AttributesBuilder attributes, REQUEST request, RESPONSE response) {
+    set(
+        attributes,
+        SemanticAttributes.HTTP_REQUEST_CONTENT_LENGTH,
+        requestContentLength(request, response));
+    set(
+        attributes,
+        SemanticAttributes.HTTP_REQUEST_CONTENT_LENGTH_UNCOMPRESSED,
+        requestContentLengthUncompressed(request, response));
+    set(attributes, SemanticAttributes.HTTP_STATUS_CODE, statusCode(request, response));
+    set(attributes, SemanticAttributes.HTTP_FLAVOR, flavor(request, response));
+    set(
+        attributes,
+        SemanticAttributes.HTTP_RESPONSE_CONTENT_LENGTH,
+        responseContentLength(request, response));
+    set(
+        attributes,
+        SemanticAttributes.HTTP_RESPONSE_CONTENT_LENGTH_UNCOMPRESSED,
+        responseContentLengthUncompressed(request, response));
+    set(attributes, SemanticAttributes.HTTP_SERVER_NAME, serverName(request, response));
+    set(attributes, SemanticAttributes.HTTP_CLIENT_IP, clientIp(request, response));
+  }
+
+  // Attributes that always exist in a request
+
+  @Nullable
+  protected abstract String method(REQUEST request);
+
+  @Nullable
+  protected abstract String url(REQUEST request);
+
+  @Nullable
+  protected abstract String target(REQUEST request);
+
+  @Nullable
+  protected abstract String host(REQUEST request);
+
+  @Nullable
+  protected abstract String route(REQUEST request);
+
+  @Nullable
+  protected abstract String scheme(REQUEST request);
+
+  @Nullable
+  protected abstract String userAgent(REQUEST request);
+
+  // Attributes which are not always available when the request is ready.
+
+  @Nullable
+  protected abstract Long requestContentLength(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract Long requestContentLengthUncompressed(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract Long statusCode(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract String flavor(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract Long responseContentLength(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract Long responseContentLengthUncompressed(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract String serverName(REQUEST request, RESPONSE response);
+
+  @Nullable
+  protected abstract String clientIp(REQUEST request, RESPONSE response);
+}

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

@@ -0,0 +1,28 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+final class HttpSpanNameExtractor<REQUEST> implements SpanNameExtractor<REQUEST> {
+
+  private final HttpAttributesExtractor<REQUEST, ?> attributesExtractor;
+
+  HttpSpanNameExtractor(HttpAttributesExtractor<REQUEST, ?> attributesExtractor) {
+    this.attributesExtractor = attributesExtractor;
+  }
+
+  @Override
+  public String extract(REQUEST request) {
+    String route = attributesExtractor.route(request);
+    if (route != null) {
+      return route;
+    }
+    String method = attributesExtractor.method(request);
+    if (method != null) {
+      return "HTTP " + method;
+    }
+    return "HTTP request";
+  }
+}

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

@@ -0,0 +1,29 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import io.opentelemetry.api.trace.StatusCode;
+import io.opentelemetry.instrumentation.api.tracer.HttpStatusConverter;
+
+final class HttpSpanStatusExtractor<REQUEST, RESPONSE>
+    implements SpanStatusExtractor<REQUEST, RESPONSE> {
+
+  private final HttpAttributesExtractor<REQUEST, RESPONSE> attributesExtractor;
+
+  protected HttpSpanStatusExtractor(
+      HttpAttributesExtractor<REQUEST, RESPONSE> attributesExtractor) {
+    this.attributesExtractor = attributesExtractor;
+  }
+
+  @Override
+  public StatusCode extract(REQUEST request, RESPONSE response, Throwable error) {
+    Long statusCode = attributesExtractor.statusCode(request, response);
+    if (statusCode != null) {
+      return HttpStatusConverter.statusFromHttpStatus((int) (long) statusCode);
+    }
+    return SpanStatusExtractor.getDefault().extract(request, response, error);
+  }
+}

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

@@ -0,0 +1,61 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * Extractor of <a
+ * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/span-general.md#general-network-connection-attributes">Network
+ * attributes</a> from a {@link InetSocketAddress}. Most network libraries will provide access to a
+ * {@link InetSocketAddress} so this is a convenient alternative to {@link NetAttributesExtractor}.
+ * There is no meaning to implement both in the same instrumentation.
+ */
+public abstract class InetSocketAddressNetAttributesExtractor<REQUEST, RESPONSE>
+    extends NetAttributesExtractor<REQUEST, RESPONSE> {
+
+  @Nullable
+  protected abstract InetSocketAddress getAddress(REQUEST request, RESPONSE response);
+
+  @Override
+  @Nullable
+  protected final String peerName(REQUEST request, RESPONSE response) {
+    InetSocketAddress address = getAddress(request, response);
+    if (address == null) {
+      return null;
+    }
+    if (address.getAddress() != null) {
+      return address.getAddress().getHostName();
+    }
+    return address.getHostString();
+  }
+
+  @Override
+  @Nullable
+  protected final Long peerPort(REQUEST request, RESPONSE response) {
+    InetSocketAddress address = getAddress(request, response);
+    if (address == null) {
+      return null;
+    }
+    return (long) address.getPort();
+  }
+
+  @Override
+  @Nullable
+  protected final String peerIp(REQUEST request, RESPONSE response) {
+    InetSocketAddress address = getAddress(request, response);
+    if (address == null) {
+      return null;
+    }
+    InetAddress remoteAddress = address.getAddress();
+    if (remoteAddress != null) {
+      return remoteAddress.getHostAddress();
+    }
+    return null;
+  }
+}