Add an optional number of child spans that were generated while this span was running. (#426)

Author: Bogdan Drutu

api/src/main/java/io/opencensus/trace/export/SpanData.java

@@ -51,6 +51,7 @@ public abstract class SpanData {
    * @param annotations the annotations associated with the {@code Span}.
    * @param networkEvents the network events associated with the {@code Span}.
    * @param links the links associated with the {@code Span}.
+   * @param childSpanCount the number of child spans that were generated while the span was active.
    * @param status the {@code Status} of the {@code Span}. {@code null} if the {@code Span} is still
    *     active.
    * @param endTimestamp the end {@code Timestamp} of the {@code Span}. {@code null} if the {@code
@@ -67,6 +68,7 @@ public static SpanData create(
       TimedEvents<Annotation> annotations,
       TimedEvents<NetworkEvent> networkEvents,
       Links links,
+      @Nullable Integer childSpanCount,
       @Nullable Status status,
       @Nullable Timestamp endTimestamp) {
     return new AutoValue_SpanData(
@@ -79,6 +81,7 @@ public static SpanData create(
         annotations,
         networkEvents,
         links,
+        childSpanCount,
         status,
         endTimestamp);
   }
@@ -147,6 +150,17 @@ public static SpanData create(
    */
   public abstract Links getLinks();
 
+  /**
+   * Returns the number of child spans that were generated while the {@code Span} was running. If
+   * not {@code null} allows service implementations to detect missing child spans.
+   *
+   * <p>This information is not always available.
+   *
+   * @return the number of child spans that were generated while the {@code Span} was running.
+   */
+  @Nullable
+  public abstract Integer getChildSpanCount();
+
   /**
    * Returns the {@code Status} or {@code null} if {@code Span} is still active.
    *

api/src/test/java/io/opencensus/trace/export/SpanDataTest.java

@@ -58,6 +58,7 @@ public class SpanDataTest {
   private static final NetworkEvent sentNetworkEvent =
       NetworkEvent.builder(NetworkEvent.Type.SENT, 1).build();
   private static final Status status = Status.DEADLINE_EXCEEDED.withDescription("TooSlow");
+  private static final int CHILD_SPAN_COUNT = 13;
   private final Random random = new Random(1234);
   private final SpanContext spanContext =
       SpanContext.create(
@@ -102,6 +103,7 @@ public void spanData_AllValues() {
             annotations,
             networkEvents,
             links,
+            CHILD_SPAN_COUNT,
             status,
             endTimestamp);
     assertThat(spanData.getContext()).isEqualTo(spanContext);
@@ -113,6 +115,7 @@ public void spanData_AllValues() {
     assertThat(spanData.getAnnotations()).isEqualTo(annotations);
     assertThat(spanData.getNetworkEvents()).isEqualTo(networkEvents);
     assertThat(spanData.getLinks()).isEqualTo(links);
+    assertThat(spanData.getChildSpanCount()).isEqualTo(CHILD_SPAN_COUNT);
     assertThat(spanData.getStatus()).isEqualTo(status);
     assertThat(spanData.getEndTimestamp()).isEqualTo(endTimestamp);
   }
@@ -131,6 +134,7 @@ public void spanData_RootActiveSpan() {
             networkEvents,
             links,
             null,
+            null,
             null);
     assertThat(spanData.getContext()).isEqualTo(spanContext);
     assertThat(spanData.getParentSpanId()).isNull();
@@ -141,6 +145,7 @@ public void spanData_RootActiveSpan() {
     assertThat(spanData.getAnnotations()).isEqualTo(annotations);
     assertThat(spanData.getNetworkEvents()).isEqualTo(networkEvents);
     assertThat(spanData.getLinks()).isEqualTo(links);
+    assertThat(spanData.getChildSpanCount()).isNull();
     assertThat(spanData.getStatus()).isNull();
     assertThat(spanData.getEndTimestamp()).isNull();
   }
@@ -158,6 +163,7 @@ public void spanData_AllDataEmpty() {
             TimedEvents.create(Collections.<SpanData.TimedEvent<Annotation>>emptyList(), 0),
             TimedEvents.create(Collections.<SpanData.TimedEvent<NetworkEvent>>emptyList(), 0),
             Links.create(Collections.<Link>emptyList(), 0),
+            0,
             status,
             endTimestamp);
     assertThat(spanData.getContext()).isEqualTo(spanContext);
@@ -169,6 +175,7 @@ public void spanData_AllDataEmpty() {
     assertThat(spanData.getAnnotations().getEvents().isEmpty()).isTrue();
     assertThat(spanData.getNetworkEvents().getEvents().isEmpty()).isTrue();
     assertThat(spanData.getLinks().getLinks().isEmpty()).isTrue();
+    assertThat(spanData.getChildSpanCount()).isEqualTo(0);
     assertThat(spanData.getStatus()).isEqualTo(status);
     assertThat(spanData.getEndTimestamp()).isEqualTo(endTimestamp);
   }
@@ -186,6 +193,7 @@ public void spanDataEquals() {
             annotations,
             networkEvents,
             links,
+            CHILD_SPAN_COUNT,
             status,
             endTimestamp);
     SpanData allSpanData2 =
@@ -199,6 +207,7 @@ public void spanDataEquals() {
             annotations,
             networkEvents,
             links,
+            CHILD_SPAN_COUNT,
             status,
             endTimestamp);
     SpanData emptySpanData =
@@ -212,6 +221,7 @@ public void spanDataEquals() {
             TimedEvents.create(Collections.<SpanData.TimedEvent<Annotation>>emptyList(), 0),
             TimedEvents.create(Collections.<SpanData.TimedEvent<NetworkEvent>>emptyList(), 0),
             Links.create(Collections.<Link>emptyList(), 0),
+            0,
             status,
             endTimestamp);
     new EqualsTester()
@@ -227,12 +237,13 @@ public void spanData_ToString() {
                 spanContext,
                 parentSpanId,
                 false,
-            SPAN_NAME,
+                SPAN_NAME,
                 startTimestamp,
                 attributes,
                 annotations,
                 networkEvents,
                 links,
+                CHILD_SPAN_COUNT,
                 status,
                 endTimestamp)
             .toString();

impl_core/src/main/java/io/opencensus/trace/SpanImpl.java

@@ -220,6 +220,7 @@ public SpanData toSpanData() {
           annotationsSpanData,
           networkEventsSpanData,
           linksSpanData,
+          null,  // Not supported yet.
           hasBeenEnded ? status : null,
           hasBeenEnded ? timestampConverter.convertNanoTime(endNanoTime) : null);
     }