WIP

Author: PerfectSlayer

dd-java-agent/instrumentation-testing/src/main/java/datadog/trace/agent/test/assertions/SpanMatcher.java

@@ -451,6 +451,7 @@ private void assertSpanLinks(List<AgentSpanLink> links) {
           .expected(expectedLinkCount)
           .actual(linkCount)
           .buildAndThrow();
+      return;
     }
     for (int i = 0; i < expectedLinkCount; i++) {
       SpanLinkMatcher linkMatcher = this.linkMatchers[i];

dd-smoke-tests/src/main/java/datadog/smoketest/trace/SpanMatcher.java

@@ -13,6 +13,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Map.Entry;
 import java.util.function.Predicate;
 import java.util.regex.Pattern;
 
@@ -24,7 +25,8 @@
  * datadog.trace.agent.test.assertions}, which matches on {@code DDSpan}); the two share only the
  * generic value matchers in {@code datadog.trace.junit.utils.assertions}. Only what a span carries
  * once serialized is matchable here: name/service/resource/type, error status, {@code meta} (string
- * tags), {@code metrics} (numeric tags), and parent linkage.
+ * tags), {@code metrics} (numeric tags), {@code meta_struct} (nested structured data), and parent
+ * linkage.
  *
  * <p>Parent linkage can be expressed by {@link #root()}, {@link #childOf(long) explicit id}, or —
  * for structural assertions within a sorted trace — by position with {@link #childOfIndex(int)} /
@@ -40,8 +42,10 @@ public final class SpanMatcher {
   private Long parentId; // explicit expected parent id (childOf/root); null => not checked by id
   private int parentSpanIndex = -1; // >= 0 => parent is the span at this index in the sorted trace
   private boolean childOfPrevious; // parent is the preceding span in the sorted trace
-  private final Map<String, Matcher<?>> metaMatchers = new HashMap<>();
-  private final Map<String, Matcher<?>> metricMatchers = new HashMap<>();
+  private final Map<String, Matcher<String>> metaMatchers = new HashMap<>();
+  private final Map<String, Matcher<Number>> metricMatchers = new HashMap<>();
+  // meta_struct values are nested (map/list/scalar), so matched as Object.
+  private final Map<String, Matcher<?>> metaStructMatchers = new HashMap<>();
 
   private SpanMatcher() {}
 
@@ -124,7 +128,7 @@ public SpanMatcher childOfPrevious() {
   }
 
   /** Matches a {@code meta} (string) tag against the given matcher. */
-  public SpanMatcher tag(String name, Matcher<?> matcher) {
+  public SpanMatcher tag(String name, Matcher<String> matcher) {
     this.metaMatchers.put(name, matcher);
     return this;
   }
@@ -136,43 +140,54 @@ public SpanMatcher tag(String name, String value) {
   }
 
   /** Matches a {@code metrics} (numeric) tag against the given matcher. */
-  public SpanMatcher metric(String name, Matcher<?> matcher) {
+  public SpanMatcher metric(String name, Matcher<Number> matcher) {
     this.metricMatchers.put(name, matcher);
     return this;
   }
 
-  // TODO thin: exhaustive tag coverage (fail on unexpected meta/metrics) and span-links.
+  public SpanMatcher metaStruct(String name, Matcher<?> matcher) {
+    this.metaStructMatchers.put(name, matcher);
+    return this;
+  }
 
-  /** Positional (count-exact) assertion: the span at {@code spanIndex} matches this matcher. */
   void assertSpan(List<DecodedSpan> trace, int spanIndex) {
     assertValue(
         parentIdMatcher(trace, spanIndex),
         trace.get(spanIndex).getParentId(),
         "Unexpected parent id");
-    assertFields(trace.get(spanIndex));
-  }
-
-  /** Asserts a span's own fields (service/operation/resource/type/error/tags), ignoring linkage. */
-  @SuppressWarnings("unchecked")
-  private void assertFields(DecodedSpan span) {
+    DecodedSpan span = trace.get(spanIndex);
     assertValue(this.serviceMatcher, span.getService(), "Unexpected service name");
     assertValue(this.operationNameMatcher, span.getName(), "Unexpected operation name");
     assertValue(this.resourceNameMatcher, span.getResource(), "Unexpected resource name");
     assertValue(this.typeMatcher, span.getType(), "Unexpected span type");
     assertValue(this.errorMatcher, span.getError() != 0, "Unexpected error status");
-    Map<String, String> meta = span.getMeta();
-    for (Map.Entry<String, Matcher<?>> entry : this.metaMatchers.entrySet()) {
-      Object value = meta == null ? null : meta.get(entry.getKey());
+    assertSpanTags(span.getMeta());
+    assertSpanMetrics(span.getMetrics());
+    assertSpanMetaStruct(span.getMetaStruct());
+  }
+
+  private void assertSpanTags(Map<String, String> meta) {
+    for (Entry<String, Matcher<String>> entry : this.metaMatchers.entrySet()) {
+      String key = entry.getKey();
+      assertValue(entry.getValue(), meta.get(key), "Unexpected meta tag '" + key + "'");
+    }
+  }
+
+  private void assertSpanMetrics(Map<String, Number> metrics) {
+    for (Entry<String, Matcher<Number>> entry : this.metricMatchers.entrySet()) {
       assertValue(
-          (Matcher<Object>) entry.getValue(),
-          value,
-          "Unexpected meta tag '" + entry.getKey() + "'");
+          entry.getValue(),
+          metrics.get(entry.getKey()),
+          "Unexpected metric '" + entry.getKey() + "'");
     }
-    Map<String, Number> metrics = span.getMetrics();
-    for (Map.Entry<String, Matcher<?>> entry : this.metricMatchers.entrySet()) {
-      Object value = metrics == null ? null : metrics.get(entry.getKey());
+  }
+
+  @SuppressWarnings("unchecked")
+  private void assertSpanMetaStruct(Map<String, Object> metaStruct) {
+    for (Entry<String, Matcher<?>> entry : this.metaStructMatchers.entrySet()) {
+      String key = entry.getKey();
       assertValue(
-          (Matcher<Object>) entry.getValue(), value, "Unexpected metric '" + entry.getKey() + "'");
+          (Matcher<Object>) entry.getValue(), metaStruct.get(key), "Unexpected meta_struct '" + key + "'");
     }
   }
 

dd-smoke-tests/src/test/java/datadog/smoketest/backend/TestAgentTraceDecoderTest.java

@@ -5,7 +5,6 @@
 import static datadog.smoketest.trace.TraceMatcher.trace;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
-import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -120,7 +119,7 @@ void metaStructIsNullWhenAbsentAndAMapWhenPresent() {
     // Absent meta_struct decodes to null (matching the msgpack Decoder's plain-span shape).
     DecodedSpan withoutMetaStruct =
         TestAgentTraceDecoder.decode(TWO_TRACES).get(0).getSpans().get(0);
-    assertNull(withoutMetaStruct.getMetaStruct());
+    assertTrue(withoutMetaStruct.getMetaStruct().isEmpty());
 
     String withMetaStruct =
         "[[{"

dd-smoke-tests/src/test/java/datadog/smoketest/trace/SmokeMatcherTest.java

@@ -4,11 +4,14 @@
 import static datadog.smoketest.trace.SpanMatcher.span;
 import static datadog.smoketest.trace.TraceMatcher.SORT_BY_ANCESTRY;
 import static datadog.smoketest.trace.TraceMatcher.trace;
+import static datadog.trace.test.junit.utils.assertions.Matchers.isNonNull;
+import static datadog.trace.test.junit.utils.assertions.Matchers.validates;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import datadog.smoketest.backend.TestAgentTraceDecoder;
 import datadog.trace.test.agent.decoder.DecodedTrace;
 import java.util.List;
+import java.util.Map;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -42,6 +45,17 @@ class SmokeMatcherTest {
           + spanJson("b", 300, 100, 30)
           + "]]";
 
+  // One span carrying meta_struct: an IAST-style nested "_dd.stack" plus a request-body entry.
+  private static final String META_STRUCT_TRACE =
+      "[[{"
+          + "\"service\":\"s\",\"name\":\"servlet.request\",\"resource\":\"r\",\"type\":\"web\","
+          + "\"trace_id\":1,\"span_id\":1,\"parent_id\":0,\"start\":0,\"duration\":1,\"error\":0,"
+          + "\"meta\":{},\"metrics\":{},"
+          + "\"meta_struct\":{"
+          + "\"_dd.stack\":{\"vulnerability\":[{\"type\":\"SQL_INJECTION\"},{\"type\":\"XSS\"}]},"
+          + "\"http.request.body\":{\"foo\":\"bar\"}"
+          + "}}]]";
+
   @Test
   void sortsSpansByStartTimeThenMatchesParentByPrevious() {
     List<DecodedTrace> traces = TestAgentTraceDecoder.decode(CHAIN_TRACE);
@@ -144,6 +158,47 @@ void unorderedRequiresDistinctTraces() {
                 trace(span().operationName("root-a").root())));
   }
 
+  @Test
+  void matchesMetaStructByMatcherAndPredicate() {
+    List<DecodedTrace> traces = TestAgentTraceDecoder.decode(META_STRUCT_TRACE);
+    assertTraces(
+        traces,
+        trace(
+            span()
+                .operationName("servlet.request")
+                .root()
+                // plain matcher: the entry is present (any nested value)
+                .metaStruct("http.request.body", isNonNull())
+                // predicate via validates(): navigate the nested structure
+                .metaStruct(
+                    "_dd.stack",
+                    validates(v -> ((List<?>) ((Map<?, ?>) v).get("vulnerability")).size() == 2))));
+  }
+
+  @Test
+  void metaStructMismatchFails() {
+    List<DecodedTrace> traces = TestAgentTraceDecoder.decode(META_STRUCT_TRACE);
+    // Absent entry -> null value -> matcher fails.
+    assertThrows(
+        AssertionError.class,
+        () -> assertTraces(traces, trace(span().root().metaStruct("does.not.exist", isNonNull()))));
+    // Present entry but the predicate over its nested value is not satisfied.
+    assertThrows(
+        AssertionError.class,
+        () ->
+            assertTraces(
+                traces,
+                trace(
+                    span()
+                        .root()
+                        .metaStruct(
+                            "_dd.stack",
+                            validates(
+                                v ->
+                                    ((List<?>) ((Map<?, ?>) v).get("vulnerability")).size()
+                                        == 99)))));
+  }
+
   private static String spanJson(String name, long id, long parent, long start) {
     return "{\"service\":\"s\",\"name\":\""
         + name