WIP

PerfectSlayer · PerfectSlayer · commit d42ded1fda83 · 2026-07-28T10:47:36.000+02:00
diff --git a/dd-smoke-tests/spring-boot-rabbit/src/test/java/datadog/smoketest/SpringBootRabbitSmokeTest.java b/dd-smoke-tests/spring-boot-rabbit/src/test/java/datadog/smoketest/SpringBootRabbitSmokeTest.java
@@ -1,6 +1,5 @@
 package datadog.smoketest;
 
-import static datadog.smoketest.trace.SmokeTraceAssertions.IGNORE_ADDITIONAL_TRACES;
 import static datadog.smoketest.trace.SpanMatcher.span;
 import static datadog.smoketest.trace.TraceMatcher.SORT_BY_PARENT_CHAIN;
 import static datadog.smoketest.trace.TraceMatcher.trace;
@@ -55,14 +54,15 @@
  *                       spring-rabbit-0 spring.consume Receiver.receiveMessage (sender consumes reply)
  * </pre>
  *
- * <p>The whole collection is asserted with the standard {@link Traces#assertTraces} DSL in {@link
- * SmokeTraceAssertions#IGNORE_ADDITIONAL_TRACES order-independent subset} mode: each matcher
- * matches a distinct received trace and extras are ignored. This is stronger than the Groovy
- * set-membership check — each round-trip trace is matched count-exact (all 12 spans, in {@link
- * TraceMatcher#SORT_BY_PARENT_CHAIN parent-chain order}), verifying every AMQP operation
- * (publish/deliver/consume, both directions) <em>and</em> its cross-service linkage — while staying
- * robust to the timing-dependent extras (the broker emits its connection-setup commands and per-ack
- * traces as their own single-span traces, in non-deterministic count and order).
+ * <p>The whole collection is asserted with the standard {@link Traces#assertTraces} DSL in
+ * {@linkplain SmokeTraceAssertions order-independent subset} mode ({@code
+ * unordered().ignoreAdditionalTraces()}): each matcher matches a distinct received trace and extras
+ * are ignored. This is stronger than the Groovy set-membership check — each round-trip trace is
+ * matched count-exact (all 12 spans, in {@link TraceMatcher#SORT_BY_PARENT_CHAIN parent-chain
+ * order}), verifying every AMQP operation (publish/deliver/consume, both directions) <em>and</em>
+ * its cross-service linkage — while staying robust to the timing-dependent extras (the broker emits
+ * its connection-setup commands and per-ack traces as their own single-span traces, in
+ * non-deterministic count and order).
  *
  * <p>Two design points, informed by inspecting the live trace collection:
  *
@@ -123,10 +123,10 @@ void roundtripsProduceFullAmqpTraceStructure() throws IOException {
       }
     }
 
-    // One order-independent assertion over the whole collection (IGNORE_ADDITIONAL_TRACES): each
-    // matcher must match a distinct received trace; unrelated/duplicate traces (extra acks, etc.)
-    // are ignored. Assert one full round-trip trace per message plus each service's
-    // connection-setup/ack commands.
+    // One order-independent subset assertion over the whole collection (unordered +
+    // ignoreAdditionalTraces): each matcher must match a distinct received trace, and
+    // unrelated/duplicate traces (extra acks, etc.) are ignored. Assert one full round-trip trace
+    // per message plus each service's connection-setup/ack commands.
     List<TraceMatcher> expected = new ArrayList<>();
     for (int i = 0; i < MESSAGES.length; i++) {
       expected.add(roundTrip()); // one full round-trip trace per message => all are verified
@@ -139,7 +139,9 @@ void roundtripsProduceFullAmqpTraceStructure() throws IOException {
     agent
         .traces()
         .assertTraces(
-            TIMEOUT_SECONDS, IGNORE_ADDITIONAL_TRACES, expected.toArray(new TraceMatcher[0]));
+            TIMEOUT_SECONDS,
+            o -> o.unordered().ignoreAdditionalTraces(),
+            expected.toArray(new TraceMatcher[0]));
   }
 
   // The full distributed round-trip as one strict parent->child chain across both services and the
diff --git a/dd-smoke-tests/src/main/java/datadog/smoketest/trace/SmokeTraceAssertions.java b/dd-smoke-tests/src/main/java/datadog/smoketest/trace/SmokeTraceAssertions.java
@@ -6,7 +6,6 @@
 import datadog.trace.test.agent.decoder.DecodedTrace;
 import java.util.ArrayList;
 import java.util.Comparator;
-import java.util.Iterator;
 import java.util.List;
 import java.util.function.UnaryOperator;
 
@@ -22,15 +21,26 @@
  * assertTraces(traces, trace(span().operationName("servlet.request").resourceName("GET /greeting")));
  * }</pre>
  *
- * <p>By default traces are matched <em>positionally</em> (matcher <i>i</i> ↔ trace <i>i</i>), in
- * the order received — pass {@link #SORT_BY_START_TIME} / {@link #SORT_BY_ROOT_SPAN_ID} for a
- * stable order, and the count must match exactly. Pass {@link #IGNORE_ADDITIONAL_TRACES} to switch
- * to <em>order-independent subset</em> matching instead: each matcher must match a
- * <em>distinct</em> received trace, and any extra traces are ignored — the right mode when the
- * collection contains unrelated or non-deterministically-ordered traces (e.g. a distributed test
- * where connection-setup commands land as their own traces alongside the request traces you care
- * about). The traces come from a {@code TraceBackend} (mock or test-agent), both decoded to {@link
- * DecodedTrace}.
+ * <p>A single matching algorithm is tuned by three orthogonal, combinable {@link Options}:
+ *
+ * <ul>
+ *   <li>{@link #SORT_BY_START_TIME} / {@link #SORT_BY_ROOT_SPAN_ID} (the {@code sorter}) — sort the
+ *       received traces before matching.
+ *   <li>{@link #UNORDERED} — a matcher may match <em>any</em> distinct (unconsumed) trace rather
+ *       than the one at its position. Without a sorter this is fully order-independent;
+ *       <em>with</em> a sorter it is forward-only (once a matcher takes the trace at sorted
+ *       position <i>p</i>, the next matcher can only look at positions after <i>p</i>) — i.e. match
+ *       as a subsequence in sorted order.
+ *   <li>{@link #IGNORE_ADDITIONAL_TRACES} — don't require every received trace to be matched; extra
+ *       traces are ignored (a subset assertion). Without it, the counts must be equal.
+ * </ul>
+ *
+ * <p>The default (no options) is thus count-exact positional matching (matcher <i>i</i> ↔ trace
+ * <i>i</i>, received order). Combine flags with the fluent {@link Options} — e.g. {@code o ->
+ * o.unordered().ignoreAdditionalTraces()} — to assert only the traces you care about in a
+ * collection that also holds unrelated or non-deterministically-ordered ones (e.g. a distributed
+ * test where connection-setup commands land as their own traces). The traces come from a {@code
+ * TraceBackend} (mock or test-agent), both decoded to {@link DecodedTrace}.
  */
 public final class SmokeTraceAssertions {
   /** Sorts traces by the earliest span start time. */
@@ -41,13 +51,13 @@ public final class SmokeTraceAssertions {
   public static final Comparator<List<DecodedSpan>> TRACE_ROOT_SPAN_ID_COMPARATOR =
       Comparator.comparingLong(SmokeTraceAssertions::rootSpanId);
 
-  /**
-   * Switch to order-independent subset matching: each matcher must match a distinct received trace,
-   * and extra traces are ignored (instead of the default count-exact positional matching).
-   */
+  /** Don't require every received trace to be matched — ignore the extras (a subset assertion). */
   public static final UnaryOperator<Options> IGNORE_ADDITIONAL_TRACES =
       Options::ignoreAdditionalTraces;
 
+  /** Let each matcher match any distinct trace rather than the one at its position. */
+  public static final UnaryOperator<Options> UNORDERED = Options::unordered;
+
   /** Sorts traces by earliest span start time before matching. */
   public static final UnaryOperator<Options> SORT_BY_START_TIME =
       options -> options.sorter(TRACE_START_TIME_COMPARATOR);
@@ -63,73 +73,76 @@ public static void assertTraces(List<DecodedTrace> traces, TraceMatcher... match
     assertTraces(traces, identity(), matchers);
   }
 
-  /** As {@link #assertTraces(List, TraceMatcher...)} with the given options. */
+  /**
+   * As {@link #assertTraces(List, TraceMatcher...)} with the given options. One matching pass,
+   * tuned by {@code sorter} / {@link Options#unordered() unordered} / {@link
+   * Options#ignoreAdditionalTraces() ignoreAdditionalTraces} — see the class doc for the flag
+   * semantics.
+   */
   public static void assertTraces(
       List<DecodedTrace> traces, UnaryOperator<Options> options, TraceMatcher... matchers) {
     Options opts = options.apply(new Options());
     // Copy each trace's spans to a mutable list so the matcher can sort/inspect them.
-    List<List<DecodedSpan>> spanLists = new ArrayList<>(traces.size());
+    List<List<DecodedSpan>> pool = new ArrayList<>(traces.size());
     for (DecodedTrace trace : traces) {
-      spanLists.add(new ArrayList<>(trace.getSpans()));
+      pool.add(new ArrayList<>(trace.getSpans()));
     }
-    if (opts.ignoreAdditionalTraces) {
-      assertContainsEach(spanLists, matchers);
-    } else {
-      assertPositionally(spanLists, opts, matchers);
-    }
-  }
-
-  // Order-independent subset: each matcher must match a distinct received trace; extras are
-  // ignored.
-  private static void assertContainsEach(
-      List<List<DecodedSpan>> spanLists, TraceMatcher[] matchers) {
-    if (matchers.length > spanLists.size()) {
-      throw new AssertionError(
-          "Expected at least "
-              + matchers.length
-              + " traces but got "
-              + spanLists.size()
-              + ": "
-              + spanLists);
+    if (opts.sorter != null) {
+      pool.sort(opts.sorter);
     }
-    // Greedily assign each matcher to a distinct, not-yet-consumed trace. Adequate for smoke tests;
-    // overlapping matchers (one strictly more general than another) could mis-assign — write them
-    // specific enough to be unambiguous.
-    List<List<DecodedSpan>> remaining = new ArrayList<>(spanLists);
+    // Walk the matchers, each consuming a distinct trace. `floor` is the lowest pool index a match
+    // may use: it advances past each match to enforce order, except in fully-unordered mode (no
+    // sorter) where it stays 0 so any remaining trace is a candidate. `consumed` keeps matches
+    // distinct when the floor doesn't advance.
+    boolean[] consumed = new boolean[pool.size()];
+    int matched = 0;
+    int floor = 0;
     for (int i = 0; i < matchers.length; i++) {
-      boolean matched = false;
-      for (Iterator<List<DecodedSpan>> it = remaining.iterator(); it.hasNext(); ) {
-        if (matchers[i].matches(it.next(), i)) {
-          it.remove();
-          matched = true;
-          break;
-        }
-      }
-      if (!matched) {
-        throw new AssertionError(
-            "No received trace matched trace matcher #"
-                + i
-                + " among "
-                + spanLists.size()
-                + " received trace(s): "
-                + spanLists);
+      int idx = findMatch(pool, consumed, floor, opts, matchers[i], i);
+      consumed[idx] = true;
+      matched++;
+      if (!opts.unordered || opts.sorter != null) {
+        floor = idx + 1;
       }
     }
-  }
-
-  // Count-exact positional: matcher i ↔ trace i, after the optional trace sort.
-  private static void assertPositionally(
-      List<List<DecodedSpan>> spanLists, Options opts, TraceMatcher[] matchers) {
-    if (spanLists.size() != matchers.length) {
+    if (!opts.ignoreAdditionalTraces && matched != pool.size()) {
       throw new AssertionError(
-          "Expected " + matchers.length + " traces but got " + spanLists.size());
+          "Expected " + matchers.length + " traces but got " + pool.size() + ": " + pool);
     }
-    if (opts.sorter != null) {
-      spanLists.sort(opts.sorter);
+  }
+
+  // Finds the trace this matcher consumes, or throws. Scans from `floor`, skipping consumed traces
+  // and (unless matching strictly positionally) non-matching ones. A strictly-positional matcher
+  // that fails is re-run with the throwing assertion so the failure names the offending span.
+  private static int findMatch(
+      List<List<DecodedSpan>> pool,
+      boolean[] consumed,
+      int floor,
+      Options opts,
+      TraceMatcher matcher,
+      int i) {
+    boolean strictPositional = !opts.unordered && !opts.ignoreAdditionalTraces;
+    for (int j = floor; j < pool.size(); j++) {
+      if (consumed[j]) {
+        continue;
+      }
+      if (matcher.matches(pool.get(j), i)) {
+        return j;
+      }
+      if (strictPositional) {
+        break; // the trace at this position must match; no skipping ahead
+      }
     }
-    for (int i = 0; i < matchers.length; i++) {
-      matchers[i].assertTrace(spanLists.get(i), i);
+    if (strictPositional && floor < pool.size() && !consumed[floor]) {
+      matcher.assertTrace(pool.get(floor), i); // throws with the per-span reason
     }
+    throw new AssertionError(
+        "No received trace matched trace matcher #"
+            + i
+            + " among "
+            + pool.size()
+            + " received trace(s): "
+            + pool);
   }
 
   private static long earliestStart(List<DecodedSpan> spans) {
@@ -149,16 +162,24 @@ private static long rootSpanId(List<DecodedSpan> spans) {
     return spans.isEmpty() ? 0L : spans.get(0).getSpanId();
   }
 
-  /** Trace-collection matching options. */
+  /** Trace-collection matching options; see the class doc for how they combine. */
   public static final class Options {
     boolean ignoreAdditionalTraces = false;
+    boolean unordered = false;
     Comparator<List<DecodedSpan>> sorter = null; // null => keep received order
 
+    /** Ignore received traces beyond those the matchers consume (a subset assertion). */
     public Options ignoreAdditionalTraces() {
       this.ignoreAdditionalTraces = true;
       return this;
     }
 
+    /** Let each matcher match any distinct trace (forward-only when a {@link #sorter} is set). */
+    public Options unordered() {
+      this.unordered = true;
+      return this;
+    }
+
     public Options sorter(Comparator<List<DecodedSpan>> sorter) {
       this.sorter = sorter;
       return this;
diff --git a/dd-smoke-tests/src/test/java/datadog/smoketest/trace/SmokeMatcherTest.java b/dd-smoke-tests/src/test/java/datadog/smoketest/trace/SmokeMatcherTest.java
@@ -132,30 +132,53 @@ void parentChainRejectsNonLinearTrace() {
   }
 
   @Test
-  void ignoreAdditionalTracesMatchesAnyOrder() {
+  void unorderedMatchesAnyOrder() {
     List<DecodedTrace> traces = TestAgentTraceDecoder.decode(TWO_TRACES);
-    // Matchers in the opposite order of receipt still each find their trace (order-independent).
+    // Matchers in the opposite order of receipt still each find their trace (no sorter => any
+    // order).
     assertTraces(
         traces,
-        SmokeTraceAssertions.IGNORE_ADDITIONAL_TRACES,
+        options -> options.unordered().ignoreAdditionalTraces(),
         trace(span().operationName("root-b").root()),
         trace(span().operationName("root-a").root()));
   }
 
   @Test
-  void ignoreAdditionalTracesRequiresDistinctTraces() {
+  void unorderedRequiresDistinctTraces() {
     List<DecodedTrace> traces = TestAgentTraceDecoder.decode(TWO_TRACES);
     // Two matchers for the same trace can't both match: only one root-a trace exists.
     assertThrows(
         AssertionError.class,
         () ->
             assertTraces(
                 traces,
-                SmokeTraceAssertions.IGNORE_ADDITIONAL_TRACES,
+                options -> options.unordered().ignoreAdditionalTraces(),
                 trace(span().operationName("root-a").root()),
                 trace(span().operationName("root-a").root())));
   }
 
+  @Test
+  void unorderedWithSorterIsForwardOnly() {
+    List<DecodedTrace> traces = TestAgentTraceDecoder.decode(TWO_TRACES);
+    // Sorted by root span id => [root-b (400), root-a (500)]. With a sorter, an unordered match is
+    // forward-only: matchers in sorted order match...
+    assertTraces(
+        traces,
+        options -> options.unordered().sorter(SmokeTraceAssertions.TRACE_ROOT_SPAN_ID_COMPARATOR),
+        trace(span().operationName("root-b").root()),
+        trace(span().operationName("root-a").root()));
+    // ...but reversed they don't (root-a is matched at position 1, leaving nothing after it).
+    assertThrows(
+        AssertionError.class,
+        () ->
+            assertTraces(
+                traces,
+                options ->
+                    options.unordered().sorter(SmokeTraceAssertions.TRACE_ROOT_SPAN_ID_COMPARATOR),
+                trace(span().operationName("root-a").root()),
+                trace(span().operationName("root-b").root())));
+  }
+
   private static String spanJson(String name, long id, long parent, long start) {
     return "{\"service\":\"s\",\"name\":\""
         + name
