Introduce LocalRootSpan (replacing ServerSpan) (#5896)

* Introduce LocalRootSpan (replacing ServerSpan)

* fix tests

* bridge old ServerSpan class

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpRouteHolder.java

@@ -10,7 +10,7 @@
 import io.opentelemetry.context.ContextKey;
 import io.opentelemetry.instrumentation.api.instrumenter.ContextCustomizer;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
-import io.opentelemetry.instrumentation.api.server.ServerSpan;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import io.opentelemetry.semconv.trace.attributes.SemanticAttributes;
 import javax.annotation.Nullable;
 
@@ -101,7 +101,7 @@ public static <T, U> void updateHttpRoute(
  HttpRouteBiGetter<T, U> httpRouteGetter,
  T arg1,
  U arg2) {
- Span serverSpan = ServerSpan.fromContextOrNull(context);
+ Span serverSpan = LocalRootSpan.fromContextOrNull(context);
  // even if the server span is not sampled, we have to continue - we need to compute the
  // http.route properly so that it can be captured by the server metrics
  if (serverSpan == null) {

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/server/ServerSpan.java

@@ -8,13 +8,16 @@
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.context.Context;
-import io.opentelemetry.instrumentation.api.internal.SpanKey;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import javax.annotation.Nullable;
 
 /**
  * This class encapsulates the context key for storing the current {@link SpanKind#SERVER} span in
  * the {@link Context}.
+ *
+ * @deprecated Use {@link LocalRootSpan} instead.
  */
+@Deprecated
 public final class ServerSpan {
 
  /**
@@ -23,13 +26,7 @@ public final class ServerSpan {
  */
  @Nullable
  public static Span fromContextOrNull(Context context) {
- // try the HTTP semconv span first
- Span span = SpanKey.HTTP_SERVER.fromContextOrNull(context);
- // if it's absent then try the SERVER one - perhaps suppression by span kind is enabled
- if (span == null) {
- span = SpanKey.KIND_SERVER.fromContextOrNull(context);
- }
- return span;
+ return LocalRootSpan.fromContextOrNull(context);
  }
 
  private ServerSpan() {}

instrumentation-api-semconv/src/test/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpRouteHolderTest.java

@@ -8,31 +8,24 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNull;
 
-import io.opentelemetry.api.common.Attributes;
-import io.opentelemetry.api.trace.Span;
-import io.opentelemetry.api.trace.SpanContext;
-import io.opentelemetry.api.trace.TraceFlags;
-import io.opentelemetry.api.trace.TraceState;
 import io.opentelemetry.context.Context;
-import io.opentelemetry.instrumentation.api.internal.SpanKey;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.sdk.testing.junit5.OpenTelemetryExtension;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
 
 class HttpRouteHolderTest {
 
+ @RegisterExtension final OpenTelemetryExtension testing = OpenTelemetryExtension.create();
+
  @Test
  void shouldSetRouteEvenIfSpanIsNotSampled() {
- Span span =
- Span.wrap(
- SpanContext.create(
- "00000000000000000000000000000042",
- "0000000000000012",
- TraceFlags.getDefault(),
- TraceState.getDefault()));
-
- Context context = Context.root();
- context = context.with(span);
- context = SpanKey.HTTP_SERVER.storeInContext(context, span);
- context = HttpRouteHolder.get().start(context, null, Attributes.empty());
+ Instrumenter<String, Void> instrumenter =
+ Instrumenter.<String, Void>builder(testing.getOpenTelemetry(), "test", s -> s)
+ .addContextCustomizer(HttpRouteHolder.get())
+ .newInstrumenter();
+
+ Context context = instrumenter.start(Context.root(), "test");
 
  assertNull(HttpRouteHolder.getRoute(context));
 

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

@@ -162,6 +162,10 @@ public Context start(Context parentContext, REQUEST request) {
  }
  }
 
+ if (LocalRootSpan.isLocalRoot(parentContext)) {
+ context = LocalRootSpan.store(context, span);
+ }
+
  return spanSuppressor.storeInContext(context, spanKind, span);
  }
 

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

@@ -0,0 +1,57 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.ContextKey;
+import javax.annotation.Nullable;
+
+/**
+ * A local root span is a span that either does not have a parent span (it is the root span of a
+ * trace), or its parent span is a remote span (context was propagated from another application).
+ */
+public final class LocalRootSpan {
+
+ private static final ContextKey<Span> KEY =
+ ContextKey.named("opentelemetry-traces-local-root-span");
+
+ /**
+ * Returns the local root span from the current context or {@linkplain Span#getInvalid() invalid
+ * span} if there is no local root span.
+ */
+ public static Span current() {
+ return fromContext(Context.current());
+ }
+
+ /**
+ * Returns the local root span from the given context or {@linkplain Span#getInvalid() invalid
+ * span} if there is no local root span in the context.
+ */
+ public static Span fromContext(Context context) {
+ Span span = fromContextOrNull(context);
+ return span == null ? Span.getInvalid() : span;
+ }
+
+ /**
+ * Returns the local root span from the given context or {@code null} if there is no local root
+ * span in the context.
+ */
+ @Nullable
+ public static Span fromContextOrNull(Context context) {
+ return context.get(KEY);
+ }
+
+ static boolean isLocalRoot(Context parentContext) {
+ SpanContext spanContext = Span.fromContext(parentContext).getSpanContext();
+ return !spanContext.isValid() || spanContext.isRemote();
+ }
+
+ static Context store(Context context, Span span) {
+ return context.with(KEY, span);
+ }
+}

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

@@ -11,7 +11,6 @@
 import io.opentelemetry.instrumentation.api.config.Config;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanSuppressor.BySpanKey;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanSuppressor.DelegateBySpanKind;
-import io.opentelemetry.instrumentation.api.instrumenter.SpanSuppressor.JustStoreServer;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanSuppressor.Noop;
 import io.opentelemetry.instrumentation.api.internal.SpanKey;
 import io.opentelemetry.instrumentation.api.internal.SpanKeyProvider;
@@ -21,16 +20,11 @@
 import java.util.Set;
 
 enum SpanSuppressionStrategy {
- /**
- * Do not suppress spans at all.
- *
- * <p>This strategy will mark spans of {@link SpanKind#SERVER SERVER} kind in the context, so that
- * they can be accessed using {@code ServerSpan}, but will not suppress server spans.
- */
+ /** Do not suppress spans at all. */
  NONE {
  @Override
  SpanSuppressor create(Set<SpanKey> spanKeys) {
- return JustStoreServer.INSTANCE;
+ return Noop.INSTANCE;
  }
  },
  /**

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

@@ -250,6 +250,7 @@ void server_parent() {
 
  Context context = instrumenter.start(Context.root(), request);
  assertThat(Span.fromContext(context).getSpanContext().isValid()).isTrue();
+ assertThat(LocalRootSpan.fromContext(context)).isSameAs(Span.fromContext(context));
 
  instrumenter.end(context, request, RESPONSE, null);
 
@@ -358,6 +359,7 @@ void client_parent() {
 
  assertThat(spanContext.isValid()).isTrue();
  assertThat(request).containsKey("traceparent");
+ assertThat(LocalRootSpan.fromContextOrNull(context)).isNull();
 
  instrumenter.end(context, request, RESPONSE, new IllegalStateException("test"));
 

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

@@ -0,0 +1,85 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.api.trace.TraceFlags;
+import io.opentelemetry.api.trace.TraceState;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.Scope;
+import org.junit.jupiter.api.Test;
+
+class LocalRootSpanTest {
+
+ @Test
+ void spanWithoutParentIsLocalRoot() {
+ Context parentContext = Context.root();
+ assertTrue(LocalRootSpan.isLocalRoot(parentContext));
+ }
+
+ @Test
+ void spanWithInvalidParentIsLocalRoot() {
+ Context parentContext = Context.root().with(Span.getInvalid());
+ assertTrue(LocalRootSpan.isLocalRoot(parentContext));
+ }
+
+ @Test
+ void spanWithRemoteParentIsLocalRoot() {
+ Context parentContext =
+ Context.root()
+ .with(
+ Span.wrap(
+ SpanContext.createFromRemoteParent(
+ "00000000000000000000000000000001",
+ "0000000000000002",
+ TraceFlags.getSampled(),
+ TraceState.getDefault())));
+ assertTrue(LocalRootSpan.isLocalRoot(parentContext));
+ }
+
+ @Test
+ void spanWithValidLocalParentIsNotLocalRoot() {
+ Context parentContext =
+ Context.root()
+ .with(
+ Span.wrap(
+ SpanContext.create(
+ "00000000000000000000000000000001",
+ "0000000000000002",
+ TraceFlags.getSampled(),
+ TraceState.getDefault())));
+ assertFalse(LocalRootSpan.isLocalRoot(parentContext));
+ }
+
+ @Test
+ void shouldGetLocalRootSpan() {
+ Span span = Span.getInvalid();
+ Context context = LocalRootSpan.store(Context.root(), span);
+
+ try (Scope ignored = context.makeCurrent()) {
+ assertSame(span, LocalRootSpan.current());
+ }
+ assertSame(span, LocalRootSpan.fromContext(context));
+ assertSame(span, LocalRootSpan.fromContextOrNull(context));
+ }
+
+ @Test
+ void shouldNotGetLocalRootSpanIfThereIsNone() {
+ Context context = Context.root();
+
+ try (Scope ignored = context.makeCurrent()) {
+ assertFalse(LocalRootSpan.current().getSpanContext().isValid());
+ }
+ assertFalse(LocalRootSpan.fromContext(context).getSpanContext().isValid());
+ assertNull(LocalRootSpan.fromContextOrNull(context));
+ }
+}

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

@@ -69,20 +69,9 @@ void none_shouldNotSuppressAnything(SpanKind spanKind, SpanKey spanKey) {
  assertFalse(suppressor.shouldSuppress(context, spanKind));
  }
 
- @Test
- void none_shouldStoreServerSpanInContext() {
- SpanSuppressor suppressor = SpanSuppressionStrategy.NONE.create(emptySet());
- Context context = Context.root();
-
- Context newContext = suppressor.storeInContext(context, SpanKind.SERVER, span);
-
- assertNotSame(newContext, context);
- assertSame(span, SpanKey.KIND_SERVER.fromContextOrNull(newContext));
- }
-
  @ParameterizedTest
- @EnumSource(value = SpanKind.class, mode = EnumSource.Mode.EXCLUDE, names = "SERVER")
- void none_shouldNotStoreNonServerSpansInContext(SpanKind spanKind) {
+ @EnumSource(value = SpanKind.class)
+ void none_shouldNotStoreSpansInContext(SpanKind spanKind) {
  SpanSuppressor suppressor = SpanSuppressionStrategy.NONE.create(emptySet());
  Context context = Context.root();
 

instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxrs/v2_0/RequestContextHelper.java

@@ -9,9 +9,9 @@
 
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import io.opentelemetry.instrumentation.api.instrumenter.http.HttpRouteHolder;
 import io.opentelemetry.instrumentation.api.instrumenter.http.HttpRouteSource;
-import io.opentelemetry.instrumentation.api.server.ServerSpan;
 import io.opentelemetry.javaagent.instrumentation.api.Java8BytecodeBridge;
 import javax.ws.rs.container.ContainerRequestContext;
 
@@ -25,7 +25,7 @@ public static Context createOrUpdateAbortSpan(
 
  requestContext.setProperty(JaxrsSingletons.ABORT_HANDLED, true);
  Context parentContext = Java8BytecodeBridge.currentContext();
- Span serverSpan = ServerSpan.fromContextOrNull(parentContext);
+ Span serverSpan = LocalRootSpan.fromContextOrNull(parentContext);
  Span currentSpan = Java8BytecodeBridge.spanFromContext(parentContext);
 
  HttpRouteHolder.updateHttpRoute(

instrumentation/jaxws/jaxws-2.0-axis2-1.6/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/axis2/Axis2ServerSpanNaming.java

@@ -7,15 +7,15 @@
 
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.context.Context;
-import io.opentelemetry.instrumentation.api.server.ServerSpan;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import io.opentelemetry.javaagent.bootstrap.servlet.ServletContextPath;
 import javax.servlet.http.HttpServletRequest;
 import org.apache.axis2.jaxws.core.MessageContext;
 
 public final class Axis2ServerSpanNaming {
 
  public static void updateServerSpan(Context context, Axis2Request axis2Request) {
- Span serverSpan = ServerSpan.fromContextOrNull(context);
+ Span serverSpan = LocalRootSpan.fromContextOrNull(context);
  if (serverSpan == null) {
  return;
  }

instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/cxf/CxfServerSpanNaming.java

@@ -7,7 +7,7 @@
 
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.context.Context;
-import io.opentelemetry.instrumentation.api.server.ServerSpan;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import io.opentelemetry.javaagent.bootstrap.servlet.ServletContextPath;
 import javax.servlet.http.HttpServletRequest;
 
@@ -19,7 +19,7 @@ public static void updateServerSpanName(Context context, CxfRequest cxfRequest)
  return;
  }
 
- Span serverSpan = ServerSpan.fromContextOrNull(context);
+ Span serverSpan = LocalRootSpan.fromContextOrNull(context);
  if (serverSpan == null) {
  return;
  }

instrumentation/jaxws/jaxws-2.0-metro-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/metro/MetroServerSpanNaming.java

@@ -8,7 +8,7 @@
 import com.sun.xml.ws.api.message.Packet;
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.context.Context;
-import io.opentelemetry.instrumentation.api.server.ServerSpan;
+import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import io.opentelemetry.javaagent.bootstrap.servlet.ServletContextPath;
 import javax.servlet.http.HttpServletRequest;
 import javax.xml.ws.handler.MessageContext;
@@ -21,7 +21,7 @@ public static void updateServerSpanName(Context context, MetroRequest metroReque
  return;
  }
 
- Span serverSpan = ServerSpan.fromContextOrNull(context);
+ Span serverSpan = LocalRootSpan.fromContextOrNull(context);
  if (serverSpan == null) {
  return;
  }