feat(testing): Add span links support

Author: PerfectSlayer

utils/test-agent-utils/decoder/src/main/java/datadog/trace/test/agent/decoder/DecodedSpan.java

@@ -37,6 +37,7 @@ public interface DecodedSpan {
 
   /**
    * Returns the links.
+   *
    * @return The span links, empty when the span carries none.
    */
   List<DecodedSpanLink> getLinks();

utils/test-agent-utils/decoder/src/main/java/datadog/trace/test/agent/decoder/json/raw/SpanJson.java

@@ -5,6 +5,9 @@
 
 import com.squareup.moshi.Json;
 import datadog.trace.test.agent.decoder.DecodedSpan;
+import datadog.trace.test.agent.decoder.DecodedSpanLink;
+import datadog.trace.test.agent.decoder.DecodedSpanLinks;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -44,6 +47,9 @@ public final class SpanJson implements DecodedSpan {
 
   Map<String, Number> metrics;
 
+  /** Lazily decoded from the span-links meta tag; transient so Moshi does not bind it. */
+  private transient List<DecodedSpanLink> links;
+
   @Override
   public String getService() {
     return this.service;
@@ -109,6 +115,15 @@ public String getType() {
     return this.type;
   }
 
+  @Override
+  public List<DecodedSpanLink> getLinks() {
+    List<DecodedSpanLink> links = this.links;
+    if (links == null) {
+      links = this.links = DecodedSpanLinks.fromMeta(getMeta());
+    }
+    return links;
+  }
+
   @Override
   public String toString() {
     return "SpanJson{"

utils/test-agent-utils/decoder/src/main/java/datadog/trace/test/agent/decoder/v04/raw/SpanV04.java

@@ -263,7 +263,8 @@ public SpanV04(
       String type,
       Map<String, Number> metrics,
       Map<String, String> meta,
-      Map<String, Object> metaStruct, List<DecodedSpanLink> links) {
+      Map<String, Object> metaStruct,
+      List<DecodedSpanLink> links) {
     this.service = service;
     this.name = name;
     this.resource = resource;

utils/test-agent-utils/decoder/src/test/java/datadog/trace/test/agent/decoder/SpanLinksDecoderTest.java

@@ -1,6 +1,6 @@
 package datadog.trace.test.agent.decoder;
 
-import static datadog.trace.test.agent.decoder.DecodedSpanLinks.SPAN_LINKS_TAG;
+import static java.util.Collections.emptyMap;
 import static java.util.Collections.singletonMap;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -13,22 +13,24 @@
 import org.junit.jupiter.api.Test;
 
 class SpanLinksDecoderTest {
+  // The decoder keeps the tag name private, so spell it out the way the tracer writes it.
+  private static final String SPAN_LINKS_TAG = "_dd.span_links";
   private static final String TRACE_ID_128 = "11223344556677889900aabbccddeeff";
   private static final long TRACE_ID_LOW = 0x9900aabbccddeeffL;
 
   @Test
   void absentOrEmptyTagYieldsNoLink() {
-    assertTrue(DecodedSpanLinks.fromMeta(null).isEmpty(), "null tag");
-    assertTrue(DecodedSpanLinks.fromMeta("").isEmpty(), "empty tag");
-    assertTrue(DecodedSpanLinks.fromMeta("[]").isEmpty(), "empty array");
-    assertTrue(DecodedSpanLinks.fromMeta("null").isEmpty(), "JSON null");
+    assertTrue(DecodedSpanLinks.fromMeta(emptyMap()).isEmpty(), "no tag in meta");
+    assertTrue(fromTag(null).isEmpty(), "null tag");
+    assertTrue(fromTag("").isEmpty(), "empty tag");
+    assertTrue(fromTag("[]").isEmpty(), "empty array");
+    assertTrue(fromTag("null").isEmpty(), "JSON null");
   }
 
   @Test
   void decodesMinimalLinkApplyingDefaults() {
     List<DecodedSpanLink> links =
-        DecodedSpanLinks.fromMeta(
-            "[{\"span_id\":\"123456789abcdef0\",\"trace_id\":\"" + TRACE_ID_128 + "\"}]");
+        fromTag("[{\"span_id\":\"123456789abcdef0\",\"trace_id\":\"" + TRACE_ID_128 + "\"}]");
 
     assertEquals(1, links.size());
     DecodedSpanLink link = links.get(0);
@@ -42,7 +44,7 @@ void decodesMinimalLinkApplyingDefaults() {
   @Test
   void decodesFullLink() {
     List<DecodedSpanLink> links =
-        DecodedSpanLinks.fromMeta(
+        fromTag(
             "[{\"trace_id\":\""
                 + TRACE_ID_128
                 + "\",\"span_id\":\"a\",\"flags\":1,"
@@ -62,7 +64,7 @@ void decodesFullLink() {
   @Test
   void preservesLinkOrderAndDecodesUnsignedSpanIds() {
     List<DecodedSpanLink> links =
-        DecodedSpanLinks.fromMeta(
+        fromTag(
             "[{\"trace_id\":\"0\",\"span_id\":\"1\"},"
                 + "{\"trace_id\":\"0\",\"span_id\":\"ffffffffffffffff\"},"
                 + "{\"trace_id\":\"0\",\"span_id\":\"2\"}]");
@@ -75,40 +77,31 @@ void preservesLinkOrderAndDecodesUnsignedSpanIds() {
 
   @Test
   void decodesAShortTraceId() {
-    DecodedSpanLink link =
-        DecodedSpanLinks.fromMeta("[{\"trace_id\":\"abcd\",\"span_id\":\"1\"}]").get(0);
+    DecodedSpanLink link = fromTag("[{\"trace_id\":\"abcd\",\"span_id\":\"1\"}]").get(0);
 
     assertEquals(0xabcdL, link.getTraceId());
   }
 
   @Test
   void unknownKeysAreIgnored() {
     DecodedSpanLink link =
-        DecodedSpanLinks.fromMeta(
-                "[{\"trace_id\":\"1\",\"span_id\":\"1\",\"something_new\":\"whatever\"}]")
-            .get(0);
+        fromTag("[{\"trace_id\":\"1\",\"span_id\":\"1\",\"something_new\":\"whatever\"}]").get(0);
 
     assertEquals(1L, link.getTraceId());
   }
 
   @Test
   void malformedTagsThrow() {
+    assertThrows(IllegalStateException.class, () -> fromTag("not json"), "malformed JSON");
     assertThrows(
-        IllegalStateException.class, () -> DecodedSpanLinks.fromMeta("not json"), "malformed JSON");
-    assertThrows(
-        IllegalStateException.class,
-        () -> DecodedSpanLinks.fromMeta("[{\"span_id\":\"1\"}]"),
-        "missing trace_id");
+        IllegalStateException.class, () -> fromTag("[{\"span_id\":\"1\"}]"), "missing trace_id");
     assertThrows(
-        IllegalStateException.class,
-        () -> DecodedSpanLinks.fromMeta("[{\"trace_id\":\"1\"}]"),
-        "missing span_id");
+        IllegalStateException.class, () -> fromTag("[{\"trace_id\":\"1\"}]"), "missing span_id");
     assertThrows(
         IllegalStateException.class,
-        () -> DecodedSpanLinks.fromMeta("[{\"trace_id\":\"1\",\"span_id\":\"zz\"}]"),
+        () -> fromTag("[{\"trace_id\":\"1\",\"span_id\":\"zz\"}]"),
         "malformed span id");
-    assertThrows(
-        IllegalStateException.class, () -> DecodedSpanLinks.fromMeta("[null]"), "null link entry");
+    assertThrows(IllegalStateException.class, () -> fromTag("[null]"), "null link entry");
   }
 
   @Test
@@ -143,6 +136,10 @@ void treatsAnExplicitlyEmptyAttributeMapAsNone() {
     assertTrue(link.getAttributes().isEmpty());
   }
 
+  private static List<DecodedSpanLink> fromTag(String tagValue) {
+    return DecodedSpanLinks.fromMeta(singletonMap(SPAN_LINKS_TAG, tagValue));
+  }
+
   @Test
   void decodedSpanExposesLinksAndKeepsTheTagVisible() {
     String tag = "[{\\\"trace_id\\\":\\\"" + TRACE_ID_128 + "\\\",\\\"span_id\\\":\\\"a\\\"}]";