Add Span.Kind to the trace API. (#1223)

* Add Span.Kind to the trace API.

* Add @Nullable annotation where needed.

* Add changes to changelog.

5 files changed, 112 insertions, 5 deletions

diff --git a/api/src/main/java/io/opencensus/trace/Span.java b/api/src/main/java/io/opencensus/trace/Span.java
index cb82038d..4ec532e9 100644
--- a/api/src/main/java/io/opencensus/trace/Span.java
+++ b/api/src/main/java/io/opencensus/trace/Span.java
@@ -259,4 +259,23 @@ public abstract class Span {
   public final Set<Options> getOptions() {
     return options;
   }
+
+  /**
+   * Type of span. Can be used to specify additional relationships between spans in addition to a
+   * parent/child relationship.
+   *
+   * @since 0.14
+   */
+  public enum Kind {
+    /**
+     * Indicates that the span covers server-side handling of an RPC or other remote network
+     * request.
+     */
+    SERVER,
+
+    /**
+     * Indicates that the span covers the client-side wrapper around an RPC or other remote request.
+     */
+    CLIENT
+  }
 }
diff --git a/api/src/main/java/io/opencensus/trace/SpanBuilder.java b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
index f10cb7c0..e66adf57 100644
--- a/api/src/main/java/io/opencensus/trace/SpanBuilder.java
+++ b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
@@ -111,7 +111,7 @@ public abstract class SpanBuilder {
   /**
    * Sets the {@link Sampler} to use. If not set, the implementation will provide a default.
    *
-   * @param sampler The {@code Sampler} to use when determining sampling for a {@code Span}.
+   * @param sampler the {@code Sampler} to use when determining sampling for a {@code Span}.
    * @return this.
    * @since 0.5
    */
@@ -122,7 +122,7 @@ public abstract class SpanBuilder {
    * traces. Used (for example) in batching operations, where a single batch handler processes
    * multiple requests from different traces.
    *
-   * @param parentLinks New links to be added.
+   * @param parentLinks new links to be added.
    * @return this.
    * @throws NullPointerException if {@code parentLinks} is {@code null}.
    * @since 0.5
@@ -133,13 +133,23 @@ public abstract class SpanBuilder {
    * Sets the option {@link Span.Options#RECORD_EVENTS} for the newly created {@code Span}. If not
    * called, the implementation will provide a default.
    *
-   * @param recordEvents New value determining if this {@code Span} should have events recorded.
+   * @param recordEvents new value determining if this {@code Span} should have events recorded.
    * @return this.
    * @since 0.5
    */
   public abstract SpanBuilder setRecordEvents(boolean recordEvents);
 
   /**
+   * Sets the {@link Span.Kind} for the newly created {@code Span}. If not called, the
+   * implementation will provide a default.
+   *
+   * @param spanKind the kind of the newly created {@code Span}.
+   * @return this.
+   * @since 0.14
+   */
+  public abstract SpanBuilder setSpanKind(Span.Kind spanKind);
+
+  /**
    * Starts a new {@link Span}.
    *
    * <p>Users <b>must</b> manually call {@link Span#end()} or {@link Span#end(EndSpanOptions)} to
@@ -322,6 +332,11 @@ public abstract class SpanBuilder {
       return this;
     }
 
+    @Override
+    public SpanBuilder setSpanKind(Span.Kind spanKind) {
+      return this;
+    }
+
     private NoopSpanBuilder(String name) {
       Utils.checkNotNull(name, "name");
     }
diff --git a/api/src/main/java/io/opencensus/trace/export/SpanData.java b/api/src/main/java/io/opencensus/trace/export/SpanData.java
index 7b1daf42..f0a51bf3 100644
--- a/api/src/main/java/io/opencensus/trace/export/SpanData.java
+++ b/api/src/main/java/io/opencensus/trace/export/SpanData.java
@@ -24,6 +24,7 @@ import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.Link;
 import io.opencensus.trace.MessageEvent;
 import io.opencensus.trace.Span;
+import io.opencensus.trace.Span.Kind;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
 import io.opencensus.trace.Status;
@@ -52,12 +53,49 @@ public abstract class SpanData {
   /**
    * Returns a new immutable {@code SpanData}.
    *
+   * @deprecated Use {@link #create(SpanContext, SpanId, Boolean, String, Kind, Timestamp,
+   *     Attributes, TimedEvents, TimedEvents, Links, Integer, Status, Timestamp)}.
+   */
+  @Deprecated
+  public static SpanData create(
+      SpanContext context,
+      @Nullable SpanId parentSpanId,
+      @Nullable Boolean hasRemoteParent,
+      String name,
+      Timestamp startTimestamp,
+      Attributes attributes,
+      TimedEvents<Annotation> annotations,
+      TimedEvents<? extends io.opencensus.trace.BaseMessageEvent> messageOrNetworkEvents,
+      Links links,
+      @Nullable Integer childSpanCount,
+      @Nullable Status status,
+      @Nullable Timestamp endTimestamp) {
+    return create(
+        context,
+        parentSpanId,
+        hasRemoteParent,
+        name,
+        null,
+        startTimestamp,
+        attributes,
+        annotations,
+        messageOrNetworkEvents,
+        links,
+        childSpanCount,
+        status,
+        endTimestamp);
+  }
+
+  /**
+   * Returns a new immutable {@code SpanData}.
+   *
    * @param context the {@code SpanContext} of the {@code Span}.
    * @param parentSpanId the parent {@code SpanId} of the {@code Span}. {@code null} if the {@code
    *     Span} is a root.
    * @param hasRemoteParent {@code true} if the parent {@code Span} is remote. {@code null} if this
    *     is a root span.
    * @param name the name of the {@code Span}.
+   * @param kind the kind of the {@code Span}.
    * @param startTimestamp the start {@code Timestamp} of the {@code Span}.
    * @param attributes the attributes associated with the {@code Span}.
    * @param annotations the annotations associated with the {@code Span}.
@@ -70,14 +108,15 @@ public abstract class SpanData {
    * @param endTimestamp the end {@code Timestamp} of the {@code Span}. {@code null} if the {@code
    *     Span} is still active.
    * @return a new immutable {@code SpanData}.
-   * @since 0.5
+   * @since 0.14
    */
-  @SuppressWarnings("deprecation")
+  @SuppressWarnings({"deprecation", "InconsistentOverloads"})
   public static SpanData create(
       SpanContext context,
       @Nullable SpanId parentSpanId,
       @Nullable Boolean hasRemoteParent,
       String name,
+      @Nullable Kind kind,
       Timestamp startTimestamp,
       Attributes attributes,
       TimedEvents<Annotation> annotations,
@@ -111,6 +150,7 @@ public abstract class SpanData {
         parentSpanId,
         hasRemoteParent,
         name,
+        kind,
         startTimestamp,
         attributes,
         annotations,
@@ -159,6 +199,15 @@ public abstract class SpanData {
   public abstract String getName();
 
   /**
+   * Returns the kind of this {@code Span}.
+   *
+   * @return the kind of this {@code Span}.
+   * @since 0.14
+   */
+  @Nullable
+  public abstract Kind getKind();
+
+  /**
    * Returns the start {@code Timestamp} of this {@code Span}.
    *
    * @return the start {@code Timestamp} of this {@code Span}.
diff --git a/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java b/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java
index 1403db15..a929ad97 100644
--- a/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java
+++ b/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java
@@ -21,6 +21,9 @@ import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
 import io.opencensus.common.Scope;
+import io.opencensus.trace.Span.Kind;
+import io.opencensus.trace.samplers.Samplers;
+import java.util.Collections;
 import java.util.concurrent.Callable;
 import org.junit.Before;
 import org.junit.Test;
@@ -88,4 +91,14 @@ public class SpanBuilderTest {
     verify(span).end(EndSpanOptions.DEFAULT);
     assertThat(tracer.getCurrentSpan()).isSameAs(BlankSpan.INSTANCE);
   }
+
+  @Test
+  public void doNotCrash_NoopImplementation() throws Exception {
+    SpanBuilder spanBuilder = tracer.spanBuilder("MySpanName");
+    spanBuilder.setParentLinks(Collections.<Span>emptyList());
+    spanBuilder.setRecordEvents(true);
+    spanBuilder.setSampler(Samplers.alwaysSample());
+    spanBuilder.setSpanKind(Kind.SERVER);
+    assertThat(spanBuilder.startSpan()).isSameAs(BlankSpan.INSTANCE);
+  }
 }
diff --git a/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java b/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java
index 399b35e0..b991d145 100644
--- a/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java
+++ b/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java
@@ -26,6 +26,7 @@ import io.opencensus.trace.Link;
 import io.opencensus.trace.Link.Type;
 import io.opencensus.trace.MessageEvent;
 import io.opencensus.trace.NetworkEvent;
+import io.opencensus.trace.Span.Kind;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
 import io.opencensus.trace.Status;
@@ -113,6 +114,7 @@ public class SpanDataTest {
             parentSpanId,
             true,
             SPAN_NAME,
+            Kind.SERVER,
             startTimestamp,
             attributes,
             annotations,
@@ -125,6 +127,7 @@ public class SpanDataTest {
     assertThat(spanData.getParentSpanId()).isEqualTo(parentSpanId);
     assertThat(spanData.getHasRemoteParent()).isTrue();
     assertThat(spanData.getName()).isEqualTo(SPAN_NAME);
+    assertThat(spanData.getKind()).isEqualTo(Kind.SERVER);
     assertThat(spanData.getStartTimestamp()).isEqualTo(startTimestamp);
     assertThat(spanData.getAttributes()).isEqualTo(attributes);
     assertThat(spanData.getAnnotations()).isEqualTo(annotations);
@@ -144,6 +147,7 @@ public class SpanDataTest {
             parentSpanId,
             true,
             SPAN_NAME,
+            null,
             startTimestamp,
             attributes,
             annotations,
@@ -175,6 +179,7 @@ public class SpanDataTest {
             null,
             null,
             SPAN_NAME,
+            null,
             startTimestamp,
             attributes,
             annotations,
@@ -206,6 +211,7 @@ public class SpanDataTest {
             parentSpanId,
             false,
             SPAN_NAME,
+            null,
             startTimestamp,
             Attributes.create(Collections.<String, AttributeValue>emptyMap(), 0),
             TimedEvents.create(Collections.<SpanData.TimedEvent<Annotation>>emptyList(), 0),
@@ -237,6 +243,7 @@ public class SpanDataTest {
             parentSpanId,
             false,
             SPAN_NAME,
+            Kind.CLIENT,
             startTimestamp,
             attributes,
             annotations,
@@ -251,6 +258,7 @@ public class SpanDataTest {
             parentSpanId,
             false,
             SPAN_NAME,
+            Kind.CLIENT,
             startTimestamp,
             attributes,
             annotations,
@@ -265,6 +273,7 @@ public class SpanDataTest {
             parentSpanId,
             false,
             SPAN_NAME,
+            null,
             startTimestamp,
             Attributes.create(Collections.<String, AttributeValue>emptyMap(), 0),
             TimedEvents.create(Collections.<SpanData.TimedEvent<Annotation>>emptyList(), 0),
@@ -287,6 +296,7 @@ public class SpanDataTest {
                 parentSpanId,
                 false,
                 SPAN_NAME,
+                Kind.CLIENT,
                 startTimestamp,
                 attributes,
                 annotations,
@@ -299,6 +309,7 @@ public class SpanDataTest {
     assertThat(spanDataString).contains(spanContext.toString());
     assertThat(spanDataString).contains(parentSpanId.toString());
     assertThat(spanDataString).contains(SPAN_NAME);
+    assertThat(spanDataString).contains(Kind.CLIENT.toString());
     assertThat(spanDataString).contains(startTimestamp.toString());
     assertThat(spanDataString).contains(attributes.toString());
     assertThat(spanDataString).contains(annotations.toString());