Do not link current span when propagation headers are missing

PropagatorBasedSpanLinksExtractor used the caller-provided parentContext
as the fallback for TextMapPropagator.extract, which meant that when a
message carried no propagation headers the extractor would link the new
span to the ambient parent (e.g. a CONSUMER receive span). Use
Context.root() internally so that missing headers result in no link
being added, and remove the now-redundant Context.root() overrides and
stale comments in the batch extractors for kafka-clients, kafka-connect
and pulsar. Document the invariant on SpanLinksExtractor.

Author: trask

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

@@ -15,6 +15,12 @@ public interface SpanLinksExtractor<REQUEST> {
   /**
    * Extracts {@link SpanContext}s that should be linked to the newly created span and adds them to
    * {@code spanLinks}.
+   *
+   * <p>A link points to a related span other than the parent (for example, the producer span of a
+   * message being processed). Implementations should not derive link targets from the span
+   * currently in {@code parentContext}; {@code parentContext} is provided for access to
+   * request-scoped state attached via {@link io.opentelemetry.context.ContextKey ContextKey}s (for
+   * example, baggage set earlier in the pipeline).
    */
   void extract(SpanLinksBuilder spanLinks, Context parentContext, REQUEST request);
 }

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/PropagatorBasedSpanLinksExtractor.java

@@ -30,7 +30,9 @@ public PropagatorBasedSpanLinksExtractor(
 
   @Override
   public void extract(SpanLinksBuilder spanLinks, Context parentContext, REQUEST request) {
-    Context extracted = propagator.extract(parentContext, request, getter);
+    // extract from the carrier against a root context so that, when the carrier contains no
+    // propagation data, no link is added (rather than linking to the ambient parent span)
+    Context extracted = propagator.extract(Context.root(), request, getter);
     spanLinks.addLink(Span.fromContext(extracted).getSpanContext());
   }
 }

instrumentation/kafka/kafka-clients/kafka-clients-common-0.11/library/src/main/java/io/opentelemetry/instrumentation/kafkaclients/common/v0_11/internal/KafkaBatchProcessSpanLinksExtractor.java

@@ -26,11 +26,9 @@ public void extract(
       SpanLinksBuilder spanLinks, Context parentContext, KafkaReceiveRequest request) {
 
     for (ConsumerRecord<?, ?> record : request.getRecords()) {
-      // explicitly passing root to avoid situation where context propagation is turned off and the
-      // parent (CONSUMER receive) span is linked
       singleRecordLinkExtractor.extract(
           spanLinks,
-          Context.root(),
+          parentContext,
           KafkaProcessRequest.create(record, request.getConsumerGroup(), request.getClientId()));
     }
   }

instrumentation/kafka/kafka-connect-2.6/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/kafkaconnect/v2_6/KafkaConnectBatchProcessSpanLinksExtractor.java

@@ -25,8 +25,7 @@ final class KafkaConnectBatchProcessSpanLinksExtractor
   @Override
   public void extract(SpanLinksBuilder spanLinks, Context parentContext, KafkaConnectTask request) {
     for (SinkRecord record : request.getRecords()) {
-      // explicitly passing root to avoid linking the ambient context when propagation is off
-      singleRecordLinkExtractor.extract(spanLinks, Context.root(), record);
+      singleRecordLinkExtractor.extract(spanLinks, parentContext, record);
     }
   }
 }

instrumentation/pulsar/pulsar-2.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/pulsar/v2_8/telemetry/PulsarBatchRequestSpanLinksExtractor.java

@@ -26,7 +26,7 @@ public void extract(
 
     for (Message<?> message : request.getMessages()) {
       singleRecordLinkExtractor.extract(
-          spanLinks, Context.root(), PulsarRequest.create(message, request.getUrlData()));
+          spanLinks, parentContext, PulsarRequest.create(message, request.getUrlData()));
     }
   }
 }