From ca2bce9608ffe4ae3e151bda28bf7782484f52b6 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Sun, 12 Dec 2021 21:14:36 +0100 Subject: [PATCH] Deprecate the Tracer API (#4868) --- .../api/tracer/AttributeSetter.java | 7 ++++++- .../instrumentation/api/tracer/BaseTracer.java | 3 +++ .../instrumentation/api/tracer/ClientSpan.java | 4 ++++ .../api/tracer/ConsumerSpan.java | 4 ++++ .../api/tracer/DatabaseClientTracer.java | 4 ++++ .../api/tracer/HttpClientTracer.java | 8 ++++++++ .../api/tracer/RpcClientTracer.java | 8 ++++++++ .../api/tracer/RpcServerTracer.java | 8 ++++++++ .../instrumentation/api/tracer/ServerSpan.java | 17 ++++++++++++++++- .../api/tracer/net/NetPeerAttributes.java | 11 ++++++++--- .../src/test/groovy/ContextBridgeTest.groovy | 12 ------------ 11 files changed, 69 insertions(+), 17 deletions(-) diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/AttributeSetter.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/AttributeSetter.java index 108266a52a..d901d0d2d6 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/AttributeSetter.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/AttributeSetter.java @@ -9,7 +9,12 @@ import io.opentelemetry.api.common.AttributeKey; import io.opentelemetry.api.trace.Span; import io.opentelemetry.api.trace.SpanBuilder; -/** This helper interface allows setting attributes on both {@link Span} and {@link SpanBuilder}. */ +/** + * This helper interface allows setting attributes on both {@link Span} and {@link SpanBuilder}. + * + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} instead. + */ +@Deprecated @FunctionalInterface public interface AttributeSetter { void setAttribute(AttributeKey key, T value); diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/BaseTracer.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/BaseTracer.java index 637a555afc..a2ceb6b897 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/BaseTracer.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/BaseTracer.java @@ -44,7 +44,10 @@ import javax.annotation.Nullable; *

When constructing {@link Span}s tracers should set all attributes available during * construction on a {@link SpanBuilder} instead of a {@link Span}. This way {@code SpanProcessor}s * are able to see those attributes in the {@code onStart()} method and can freely read/modify them. + * + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} instead. */ +@Deprecated public abstract class BaseTracer { private static final SupportabilityMetrics supportability = SupportabilityMetrics.instance(); diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ClientSpan.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ClientSpan.java index b368bc4ef3..6ba2c8237d 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ClientSpan.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ClientSpan.java @@ -14,7 +14,11 @@ import javax.annotation.Nullable; /** * This class encapsulates the context key for storing the current {@link SpanKind#CLIENT} span in * the {@link Context}. + * + * @deprecated This class should not be used directly; it's functionality is encapsulated inside the + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.Instrumenter Instrumenter API}. */ +@Deprecated public final class ClientSpan { /** Returns true when a {@link SpanKind#CLIENT} span is present in the passed {@code context}. */ diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ConsumerSpan.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ConsumerSpan.java index 5506099491..eb5d60db3b 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ConsumerSpan.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ConsumerSpan.java @@ -14,7 +14,11 @@ import javax.annotation.Nullable; /** * This class encapsulates the context key for storing the current {@link SpanKind#CONSUMER} span in * the {@link Context}. + * + * @deprecated This class should not be used directly; it's functionality is encapsulated inside the + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.Instrumenter Instrumenter API}. */ +@Deprecated public final class ConsumerSpan { /** diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/DatabaseClientTracer.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/DatabaseClientTracer.java index 5b8642a5fc..36504576c0 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/DatabaseClientTracer.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/DatabaseClientTracer.java @@ -21,7 +21,11 @@ import javax.annotation.Nullable; * @param type of the database connection. * @param type of the database statement being executed. * @param type of the database statement after sanitization. + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} and + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.db the database semantic + * convention utilities package} instead. */ +@Deprecated public abstract class DatabaseClientTracer extends BaseTracer { private static final String DB_QUERY = "DB Query"; diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/HttpClientTracer.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/HttpClientTracer.java index a9ab37b504..0e42409361 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/HttpClientTracer.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/HttpClientTracer.java @@ -24,6 +24,14 @@ import javax.annotation.Nullable; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Base class for implementing Tracers for HTTP clients. + * + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} and + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.http the HTTP semantic + * convention utilities package} instead. + */ +@Deprecated public abstract class HttpClientTracer extends BaseTracer { private static final Logger logger = LoggerFactory.getLogger(HttpClientTracer.class); diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcClientTracer.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcClientTracer.java index 102742154b..3d8235c7c4 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcClientTracer.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcClientTracer.java @@ -7,6 +7,14 @@ package io.opentelemetry.instrumentation.api.tracer; import io.opentelemetry.api.OpenTelemetry; +/** + * Base class for implementing Tracers for RPC clients. + * + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} and + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.rpc the RPC semantic convention + * utilities package} instead. + */ +@Deprecated public abstract class RpcClientTracer extends BaseTracer { protected RpcClientTracer() {} diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcServerTracer.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcServerTracer.java index e80f942e3e..296a200cd9 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcServerTracer.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/RpcServerTracer.java @@ -8,6 +8,14 @@ package io.opentelemetry.instrumentation.api.tracer; import io.opentelemetry.api.OpenTelemetry; import io.opentelemetry.context.propagation.TextMapGetter; +/** + * Base class for implementing Tracers for RPC servers. + * + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} and + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.rpc the RPC semantic convention + * utilities package} instead. + */ +@Deprecated public abstract class RpcServerTracer extends BaseTracer { protected RpcServerTracer() {} diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ServerSpan.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ServerSpan.java index 5707aa9c6d..e4370a67c5 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ServerSpan.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/ServerSpan.java @@ -17,7 +17,14 @@ import javax.annotation.Nullable; */ public final class ServerSpan { - /** Returns true when a {@link SpanKind#SERVER} span is present in the passed {@code context}. */ + /** + * Returns true when a {@link SpanKind#SERVER} span is present in the passed {@code context}. + * + * @deprecated This method should not be used directly; it's functionality is encapsulated inside + * the {@linkplain io.opentelemetry.instrumentation.api.instrumenter.Instrumenter Instrumenter + * API}. + */ + @Deprecated public static boolean exists(Context context) { return fromContextOrNull(context) != null; } @@ -31,6 +38,14 @@ public final class ServerSpan { return SpanKey.SERVER.fromContextOrNull(context); } + /** + * Marks the span as the server span in the passed context. + * + * @deprecated This method should not be used directly; it's functionality is encapsulated inside + * the {@linkplain io.opentelemetry.instrumentation.api.instrumenter.Instrumenter Instrumenter + * API}. + */ + @Deprecated public static Context with(Context context, Span serverSpan) { return SpanKey.SERVER.storeInContext(context, serverSpan); } diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/net/NetPeerAttributes.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/net/NetPeerAttributes.java index 0e8154f36f..625b44bced 100644 --- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/net/NetPeerAttributes.java +++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/tracer/net/NetPeerAttributes.java @@ -16,11 +16,16 @@ import java.util.Collections; import java.util.Map; import javax.annotation.Nullable; +/** + * Utility class settings the {@code net.peer.*} attributes. + * + * @deprecated Use {@link io.opentelemetry.instrumentation.api.instrumenter.Instrumenter} and + * {@linkplain io.opentelemetry.instrumentation.api.instrumenter.net the net semantic convention + * utilities package} instead. + */ +@Deprecated public final class NetPeerAttributes { - // TODO: this should only be used by the javaagent; move to javaagent-instrumentation-api after - // removing all - // library usages public static final NetPeerAttributes INSTANCE = new NetPeerAttributes( Config.get().getMap("otel.instrumentation.common.peer-service-mapping")); diff --git a/instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/src/test/groovy/ContextBridgeTest.groovy b/instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/src/test/groovy/ContextBridgeTest.groovy index 5d0afc3384..5df3b8b790 100644 --- a/instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/src/test/groovy/ContextBridgeTest.groovy +++ b/instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/src/test/groovy/ContextBridgeTest.groovy @@ -10,7 +10,6 @@ import io.opentelemetry.context.Context import io.opentelemetry.context.ContextKey import io.opentelemetry.extension.annotations.WithSpan import io.opentelemetry.instrumentation.api.instrumenter.SpanKey -import io.opentelemetry.instrumentation.api.tracer.ClientSpan import io.opentelemetry.instrumentation.api.tracer.ServerSpan import io.opentelemetry.instrumentation.test.AgentInstrumentationSpecification @@ -160,17 +159,6 @@ class ContextBridgeTest extends AgentInstrumentationSpecification { } } - def "test client span bridge"() { - expect: - AgentSpanTesting.runWithClientSpan("client") { - assert Span.current() != null - assert ClientSpan.fromContextOrNull(Context.current()) != null - runWithSpan("internal") { - assert ClientSpan.fromContextOrNull(Context.current()) != null - } - } - } - def "test span key bridge"() { expect: AgentSpanTesting.runWithAllSpanKeys("parent") {