Add span event assertions to smoke tests (#12934)

feat(testing): Add span event decoding

feat(testing): Add span event smoke test API

feat(otel): Improve span event testing

Co-authored-by: bruce.bujon <bruce.bujon@datadoghq.com>

Author: PerfectSlayer

dd-smoke-tests/opentelemetry/src/test/java/datadog/smoketest/OpenTelemetrySmokeTest.java

@@ -2,6 +2,7 @@
 
 import static datadog.smoketest.backend.AgentBackend.testAgent;
 import static datadog.smoketest.trace.SmokeTraceAssertions.UNORDERED;
+import static datadog.smoketest.trace.SpanEventMatcher.event;
 import static datadog.smoketest.trace.SpanLinkMatcher.toIndex;
 import static datadog.smoketest.trace.SpanMatcher.span;
 import static datadog.smoketest.trace.TraceMatcher.trace;
@@ -46,7 +47,7 @@ void receivesTraces() {
                 span()
                     .root()
                     .operationName("Application.loadConfiguration")
-                    .tag("events", validates(events -> events.contains("configuration-loaded")))),
+                    .events(event("configuration-loaded"))),
             // The batch trace:
             //   batch-job                        (tracer, server, root)
             //   ├─ Application.splitBatch        (annotated, main thread)

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

@@ -0,0 +1,99 @@
+package datadog.smoketest.trace;
+
+import static datadog.trace.test.junit.utils.assertions.Matchers.assertValue;
+import static datadog.trace.test.junit.utils.assertions.Matchers.is;
+import static datadog.trace.test.junit.utils.assertions.Matchers.validates;
+import static java.util.Collections.emptyMap;
+
+import datadog.trace.test.agent.decoder.DecodedSpan;
+import datadog.trace.test.agent.decoder.DecodedSpanEvent;
+import datadog.trace.test.junit.utils.assertions.Matcher;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Provides matchers for decoded span events based on their properties such as name, time, and
+ * attributes.
+ */
+public final class SpanEventMatcher {
+  private final Matcher<String> nameMatcher;
+  private Matcher<Long> timeMatcher;
+  private Matcher<Map<String, Object>> attributesMatcher;
+
+  private SpanEventMatcher(Matcher<String> nameMatcher) {
+    this.nameMatcher = nameMatcher;
+    this.attributesMatcher = is(emptyMap());
+  }
+
+  /**
+   * Creates a {@code SpanEventMatcher} that matches a span event with the given name. By default,
+   * the event must have no attribute and its time must be within the span start and end times.
+   *
+   * @param name The span event name to match against.
+   * @return A {@code SpanEventMatcher} that matches a span event with the given name.
+   */
+  public static SpanEventMatcher event(String name) {
+    return new SpanEventMatcher(is(name));
+  }
+
+  /**
+   * Checks the event time matches the given value.
+   *
+   * @param timestamp The event time to match against.
+   * @param unit The event time unit.
+   * @return The current {@link SpanEventMatcher} instance with the time constraint applied.
+   */
+  public SpanEventMatcher time(long timestamp, TimeUnit unit) {
+    this.timeMatcher = is(unit.toNanos(timestamp));
+    return this;
+  }
+
+  /**
+   * Checks the event time matches the given matcher.
+   *
+   * @param matcher The matcher to check the event time, in nanoseconds since the Unix epoch.
+   * @return The current {@link SpanEventMatcher} instance with the time constraint applied.
+   */
+  public SpanEventMatcher time(Matcher<Long> matcher) {
+    this.timeMatcher = matcher;
+    return this;
+  }
+
+  /**
+   * Checks the event attributes match the given values.
+   *
+   * @param attributes The event attributes to match against, with values being {@link String},
+   *     {@link Boolean}, {@link Long}, {@link Double}, or a {@link List} of them.
+   * @return The current {@link SpanEventMatcher} instance with the attributes constraint applied.
+   */
+  public SpanEventMatcher attributes(Map<String, Object> attributes) {
+    this.attributesMatcher = is(attributes);
+    return this;
+  }
+
+  /**
+   * Checks the event attributes match the given matcher.
+   *
+   * @param matcher The matcher to check the event attributes.
+   * @return The current {@link SpanEventMatcher} instance with the attributes constraint applied.
+   */
+  public SpanEventMatcher attributes(Matcher<Map<String, Object>> matcher) {
+    this.attributesMatcher = matcher;
+    return this;
+  }
+
+  void assertEvent(DecodedSpan span, DecodedSpanEvent event, int eventIndex) {
+    String at = " (event #" + eventIndex + ")";
+    Matcher<Long> timeMatcher = this.timeMatcher;
+    if (timeMatcher == null) {
+      long startTime = span.getStart();
+      long endTime = startTime + span.getDuration();
+      timeMatcher = validates(time -> startTime <= time && time <= endTime);
+    }
+    assertValue(this.nameMatcher, event.getName(), "Unexpected span event name" + at);
+    assertValue(timeMatcher, event.getTimeUnixNano(), "Unexpected span event time" + at);
+    assertValue(
+        this.attributesMatcher, event.getAttributes(), "Unexpected span event attributes" + at);
+  }
+}

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

@@ -9,6 +9,7 @@
 import static org.junit.jupiter.api.AssertionFailureBuilder.assertionFailure;
 
 import datadog.trace.test.agent.decoder.DecodedSpan;
+import datadog.trace.test.agent.decoder.DecodedSpanEvent;
 import datadog.trace.test.agent.decoder.DecodedSpanLink;
 import datadog.trace.test.junit.utils.assertions.Matcher;
 import java.util.HashMap;
@@ -40,6 +41,7 @@
  *   <li>span metrics (numeric) tags with {@link #metric(String, Matcher)}
  *   <li>span meta_struct (nested structured data) with {@link #metaStruct(String, Matcher)}
  *   <li>span links with {@link #links(SpanLinkMatcher...)}
+ *   <li>span events with {@link #events(SpanEventMatcher...)}
  * </ul>
  */
 public final class SpanMatcher {
@@ -51,6 +53,7 @@ public final class SpanMatcher {
   private Matcher<Long> parentIdMatcher;
   private int parentSpanIndex;
   private SpanLinkMatcher[] linkMatchers;
+  private SpanEventMatcher[] eventMatchers;
   private final Map<String, Matcher<String>> metaMatchers;
   private final Map<String, Matcher<Number>> metricMatchers;
   private final Map<String, Matcher<?>> metaStructMatchers;
@@ -234,6 +237,20 @@ public SpanMatcher links(SpanLinkMatcher... matchers) {
     return this;
   }
 
+  /**
+   * Checks the span events, one {@link SpanEventMatcher} per expected event, matched positionally
+   * and count-exact. Call it with no argument to assert the span carries no event at all; not
+   * calling it asserts nothing about events.
+   *
+   * @param matchers The matchers to verify the span events, one per expected event.
+   * @return The current {@link SpanMatcher} instance updated with the specified span event
+   *     constraints.
+   */
+  public SpanMatcher events(SpanEventMatcher... matchers) {
+    this.eventMatchers = matchers;
+    return this;
+  }
+
   /**
    * Checks the span meta (string) tag matches the given matcher.
    *
@@ -298,6 +315,7 @@ void assertSpan(List<DecodedSpan> trace, int spanIndex) {
     assertSpanMetrics(span.getMetrics());
     assertSpanMetaStruct(span.getMetaStruct());
     assertSpanLinks(trace, span);
+    assertSpanEvents(span);
   }
 
   private Matcher<Long> parentIdMatcher(List<DecodedSpan> trace, int spanIndex) {
@@ -330,6 +348,23 @@ private void assertSpanLinks(List<DecodedSpan> trace, DecodedSpan span) {
     }
   }
 
+  private void assertSpanEvents(DecodedSpan span) {
+    if (this.eventMatchers == null) {
+      return;
+    }
+    List<DecodedSpanEvent> events = span.getEvents();
+    if (events.size() != this.eventMatchers.length) {
+      assertionFailure()
+          .message("Unexpected span event count")
+          .expected(this.eventMatchers.length)
+          .actual(events.size())
+          .buildAndThrow();
+    }
+    for (int i = 0; i < this.eventMatchers.length; i++) {
+      this.eventMatchers[i].assertEvent(span, events.get(i), i);
+    }
+  }
+
   private void assertSpanTags(Map<String, String> meta) {
     for (Entry<String, Matcher<String>> entry : this.metaMatchers.entrySet()) {
       String key = entry.getKey();

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

@@ -2,6 +2,7 @@
 
 import static datadog.smoketest.trace.SmokeTraceAssertions.IGNORE_ADDITIONAL_TRACES;
 import static datadog.smoketest.trace.SmokeTraceAssertions.assertTraces;
+import static datadog.smoketest.trace.SpanEventMatcher.event;
 import static datadog.smoketest.trace.SpanLinkMatcher.any;
 import static datadog.smoketest.trace.SpanLinkMatcher.to;
 import static datadog.smoketest.trace.SpanLinkMatcher.toIndex;
@@ -12,10 +13,12 @@
 import static datadog.trace.test.junit.utils.assertions.Matchers.isNonNull;
 import static datadog.trace.test.junit.utils.assertions.Matchers.validates;
 import static java.util.Collections.singletonMap;
+import static java.util.concurrent.TimeUnit.NANOSECONDS;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import datadog.trace.test.agent.decoder.DecodedTrace;
 import datadog.trace.test.agent.decoder.Decoder;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
@@ -54,7 +57,7 @@ class SmokeMatcherTest {
   // 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\","
+          + "\"service\":\"test-service\",\"name\":\"servlet.request\",\"resource\":\"r\","
           + "\"trace_id\":1,\"span_id\":1,\"parent_id\":0,\"start\":0,\"duration\":1,\"error\":0,"
           + "\"meta\":{},\"metrics\":{},"
           + "\"meta_struct\":{"
@@ -242,12 +245,14 @@ void defaultConstraintsRequireDefinedServiceNoTypeAndNoError() {
         trace(span().root()));
 
     // A non-null span type fails the default unless acknowledged with type(...).
-    List<DecodedTrace> typed = Decoder.decodeJson(spanTraceJson("s", "web", 0)).getTraces();
+    List<DecodedTrace> typed =
+        Decoder.decodeJson(spanTraceJson("test-service", "web", 0)).getTraces();
     assertThrows(AssertionError.class, () -> assertTraces(typed, trace(span().root())));
     assertTraces(typed, trace(span().root().type("web")));
 
     // An errored span fails the default unless acknowledged with error(true).
-    List<DecodedTrace> errored = Decoder.decodeJson(spanTraceJson("s", null, 1)).getTraces();
+    List<DecodedTrace> errored =
+        Decoder.decodeJson(spanTraceJson("test-service", null, 1)).getTraces();
     assertThrows(AssertionError.class, () -> assertTraces(errored, trace(span().root())));
     assertTraces(errored, trace(span().root().error(true)));
 
@@ -410,6 +415,77 @@ void linkTargetsDoNotLeakAcrossCandidates() {
             span().operationName("root").root(), span().operationName("merge").links(toIndex(0))));
   }
 
+  // --- Span events ---
+
+  @Test
+  void matchesEventsPositionally() {
+    List<DecodedTrace> traces =
+        Decoder.decodeJson(
+                eventTraceJson(
+                    "[{\"time_unix_nano\":110,\"name\":\"first\"},"
+                        + "{\"time_unix_nano\":120,\"name\":\"second\","
+                        + "\"attributes\":{\"key\":\"value\",\"count\":3}}]"))
+            .getTraces();
+    Map<String, Object> attributes = new LinkedHashMap<>();
+    attributes.put("key", "value");
+    attributes.put("count", 3L);
+
+    assertTraces(
+        traces,
+        trace(
+            span()
+                .operationName("event")
+                .events(event("first"), event("second").attributes(attributes))));
+    assertThrows(
+        AssertionError.class,
+        () -> assertTraces(traces, trace(span().events(event("second"), event("first")))),
+        "events are matched positionally");
+    assertThrows(
+        AssertionError.class,
+        () -> assertTraces(traces, trace(span().events(event("first"), event("second")))),
+        "missing attributes");
+  }
+
+  @Test
+  void eventTimeDefaultsToSpanBounds() {
+    List<DecodedTrace> traces =
+        Decoder.decodeJson(eventTraceJson("[{\"time_unix_nano\":42,\"name\":\"early\"}]"))
+            .getTraces();
+
+    assertThrows(
+        AssertionError.class,
+        () -> assertTraces(traces, trace(span().events(event("early")))),
+        "event time outside the span bounds");
+    assertTraces(traces, trace(span().events(event("early").time(42, NANOSECONDS))));
+  }
+
+  @Test
+  void emptyEventsAssertsNoEventAndAbsentEventsAssertNothing() {
+    List<DecodedTrace> withEvents =
+        Decoder.decodeJson(eventTraceJson("[{\"time_unix_nano\":110,\"name\":\"event\"}]"))
+            .getTraces();
+
+    assertThrows(
+        AssertionError.class,
+        () -> assertTraces(withEvents, trace(span().events())),
+        "events() requires zero events");
+    // Not calling events(...) asserts nothing, even though the span does carry events.
+    assertTraces(withEvents, trace(span().operationName("event")));
+    // A span with no event satisfies events().
+    List<DecodedTrace> withoutEvents =
+        Decoder.decodeJson("[[" + spanJson("plain", 10, 0, 10) + "]]").getTraces();
+    assertTraces(withoutEvents, trace(span().operationName("plain").events()));
+  }
+
+  /** A single-span trace, from 100 to 200 ns, carrying the given events meta tag. */
+  private static String eventTraceJson(String eventsTag) {
+    return "[[{\"service\":\"test-service\",\"name\":\"event\",\"resource\":\"event\","
+        + "\"trace_id\":1,\"span_id\":1,\"parent_id\":0,\"start\":100,\"duration\":100,"
+        + "\"error\":0,\"metrics\":{},\"meta\":{\"events\":\""
+        + eventsTag.replace("\"", "\\\"")
+        + "\"}}]]";
+  }
+
   /** A single-span trace whose root {@code merge} span links to the given span ids. */
   private static String mergeOnlyTraceJson(long... linkedSpanIds) {
     return "[[" + linkingSpanJson(40, 0, linkedSpanIds) + "]]";
@@ -430,7 +506,7 @@ private static String linkedTraceJson(long shardA, long shardB) {
 
   /** A single-span trace whose link carries flags, a trace state and attributes. */
   private static String refinedLinkTraceJson() {
-    return "[[{\"service\":\"s\",\"name\":\"merge\",\"resource\":\"merge\","
+    return "[[{\"service\":\"test-service\",\"name\":\"merge\",\"resource\":\"merge\","
         + "\"trace_id\":1,\"span_id\":40,\"parent_id\":0,\"start\":40,\"duration\":1,"
         + "\"error\":0,\"metrics\":{},\"meta\":{\"_dd.span_links\":\""
         + "[{\\\"trace_id\\\":\\\"00000000000000000000000000000063\\\","
@@ -455,7 +531,7 @@ private static String linkingSpanJson(long id, long parent, long... linkedSpanId
           .append("\\\"}");
     }
     links.append(']');
-    return "{\"service\":\"s\",\"name\":\"merge\",\"resource\":\"merge\","
+    return "{\"service\":\"test-service\",\"name\":\"merge\",\"resource\":\"merge\","
         + "\"trace_id\":1,\"span_id\":"
         + id
         + ",\"parent_id\":"
@@ -467,7 +543,7 @@ private static String linkingSpanJson(long id, long parent, long... linkedSpanId
   }
 
   private static String spanJson(String name, long id, long parent, long start) {
-    return "{\"service\":\"s\",\"name\":\""
+    return "{\"service\":\"test-service\",\"name\":\""
         + name
         + "\",\"resource\":\""
         + name

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

@@ -41,4 +41,11 @@ public interface DecodedSpan {
    * @return The span links, empty when the span carries none.
    */
   List<DecodedSpanLink> getLinks();
+
+  /**
+   * Returns the events.
+   *
+   * @return The span events, empty when the span carries none.
+   */
+  List<DecodedSpanEvent> getEvents();
 }

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

@@ -0,0 +1,34 @@
+package datadog.trace.test.agent.decoder;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * This interface describes an event a decoded span carries, as the tracer serialized it. It is the
+ * wire-side counterpart of the tracer's {@code DDSpanEvent}.
+ *
+ * <p>Every accessor is non-null: absent attributes decode to an empty map.
+ */
+public interface DecodedSpanEvent {
+  /**
+   * Returns the event name.
+   *
+   * @return The event name.
+   */
+  String getName();
+
+  /**
+   * Returns the event time.
+   *
+   * @return The event time, in nanoseconds since the Unix epoch.
+   */
+  long getTimeUnixNano();
+
+  /**
+   * Returns the attributes attached to this event.
+   *
+   * @return The event attributes, with values being {@link String}, {@link Boolean}, {@link Long},
+   *     {@link Double}, or a {@link List} of them; empty if the tracer sent none.
+   */
+  Map<String, Object> getAttributes();
+}