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

* Add Span.Kind to the trace API.

* Add @Nullable annotation where needed.

* Add changes to changelog.

9 files changed, 89 insertions, 2 deletions

diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/SpanBuilderImpl.java b/impl_core/src/main/java/io/opencensus/implcore/trace/SpanBuilderImpl.java
index 45cf4261..f5d74393 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/trace/SpanBuilderImpl.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/SpanBuilderImpl.java
@@ -25,6 +25,7 @@ import io.opencensus.trace.Link;
 import io.opencensus.trace.Link.Type;
 import io.opencensus.trace.Sampler;
 import io.opencensus.trace.Span;
+import io.opencensus.trace.Span.Kind;
 import io.opencensus.trace.SpanBuilder;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -48,6 +49,7 @@ final class SpanBuilderImpl extends SpanBuilder {
   @Nullable private Sampler sampler;
   private List<Span> parentLinks = Collections.<Span>emptyList();
   @Nullable private Boolean recordEvents;
+  @Nullable private Kind kind;
 
   private SpanImpl startSpanInternal(
       @Nullable SpanContext parent,
@@ -56,6 +58,7 @@ final class SpanBuilderImpl extends SpanBuilder {
       @Nullable Sampler sampler,
       List<Span> parentLinks,
       @Nullable Boolean recordEvents,
+      @Nullable Kind kind,
       @Nullable TimestampConverter timestampConverter) {
     TraceParams activeTraceParams = options.traceConfig.getActiveTraceParams();
     Random random = options.randomHandler.current();
@@ -95,6 +98,7 @@ final class SpanBuilderImpl extends SpanBuilder {
             SpanContext.create(traceId, spanId, traceOptions),
             spanOptions,
             name,
+            kind,
             parentSpanId,
             hasRemoteParent,
             activeTraceParams,
@@ -196,6 +200,7 @@ final class SpanBuilderImpl extends SpanBuilder {
         sampler,
         parentLinks,
         recordEvents,
+        kind,
         timestampConverter);
   }
 
@@ -234,4 +239,10 @@ final class SpanBuilderImpl extends SpanBuilder {
     this.recordEvents = recordEvents;
     return this;
   }
+
+  @Override
+  public SpanBuilderImpl setSpanKind(Kind kind) {
+    this.kind = kind;
+    return this;
+  }
 }
diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java b/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java
index 59291685..75509a7f 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java
@@ -66,6 +66,8 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
   private final StartEndHandler startEndHandler;
   // The displayed name of the span.
   private final String name;
+  // The kind of the span.
+  @Nullable private final Kind kind;
   // The clock used to get the time.
   private final Clock clock;
   // The time converter used to convert nano time to Timestamp. This is needed because Java has
@@ -132,6 +134,7 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
       SpanContext context,
       @Nullable EnumSet<Options> options,
       String name,
+      @Nullable Kind kind,
       @Nullable SpanId parentSpanId,
       @Nullable Boolean hasRemoteParent,
       TraceParams traceParams,
@@ -143,6 +146,7 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
             context,
             options,
             name,
+            kind,
             parentSpanId,
             hasRemoteParent,
             traceParams,
@@ -214,6 +218,16 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
   }
 
   /**
+   * Returns the kind of this {@code Span}.
+   *
+   * @return the kind of this {@code Span}.
+   */
+  @Nullable
+  public Kind getKind() {
+    return kind;
+  }
+
+  /**
    * Returns the {@code TimestampConverter} used by this {@code Span}.
    *
    * @return the {@code TimestampConverter} used by this {@code Span}.
@@ -253,6 +267,7 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
           parentSpanId,
           hasRemoteParent,
           name,
+          kind,
           CheckerFrameworkUtils.castNonNull(timestampConverter).convertNanoTime(startNanoTime),
           attributesSpanData,
           annotationsSpanData,
@@ -575,6 +590,7 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
       SpanContext context,
       @Nullable EnumSet<Options> options,
       String name,
+      @Nullable Kind kind,
       @Nullable SpanId parentSpanId,
       @Nullable Boolean hasRemoteParent,
       TraceParams traceParams,
@@ -585,6 +601,7 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
     this.parentSpanId = parentSpanId;
     this.hasRemoteParent = hasRemoteParent;
     this.name = name;
+    this.kind = kind;
     this.traceParams = traceParams;
     this.startEndHandler = startEndHandler;
     this.clock = clock;
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/SpanBuilderImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/SpanBuilderImplTest.java
index 219d3a45..a7cdb553 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/SpanBuilderImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/SpanBuilderImplTest.java
@@ -23,6 +23,7 @@ import io.opencensus.implcore.trace.SpanImpl.StartEndHandler;
 import io.opencensus.implcore.trace.internal.RandomHandler;
 import io.opencensus.testing.common.TestClock;
 import io.opencensus.trace.Span;
+import io.opencensus.trace.Span.Kind;
 import io.opencensus.trace.Span.Options;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -62,6 +63,24 @@ public class SpanBuilderImplTest {
   }
 
   @Test
+  public void setSpanKind_NotNull() {
+    SpanImpl span =
+        SpanBuilderImpl.createWithParent(SPAN_NAME, null, spanBuilderOptions)
+            .setSpanKind(Kind.CLIENT)
+            .startSpan();
+    assertThat(span.getKind()).isEqualTo(Kind.CLIENT);
+    assertThat(span.toSpanData().getKind()).isEqualTo(Kind.CLIENT);
+  }
+
+  @Test
+  public void setSpanKind_DefaultNull() {
+    SpanImpl span =
+        SpanBuilderImpl.createWithParent(SPAN_NAME, null, spanBuilderOptions).startSpan();
+    assertThat(span.getKind()).isNull();
+    assertThat(span.toSpanData().getKind()).isNull();
+  }
+
+  @Test
   public void startSpanNullParent() {
     SpanImpl span =
         SpanBuilderImpl.createWithParent(SPAN_NAME, null, spanBuilderOptions).startSpan();
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/SpanImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/SpanImplTest.java
index 355ace51..57818eea 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/SpanImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/SpanImplTest.java
@@ -28,6 +28,7 @@ import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.EndSpanOptions;
 import io.opencensus.trace.Link;
 import io.opencensus.trace.NetworkEvent;
+import io.opencensus.trace.Span.Kind;
 import io.opencensus.trace.Span.Options;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -91,6 +92,7 @@ public class SpanImplTest {
             spanContext,
             noRecordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -116,6 +118,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -151,6 +154,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -170,6 +174,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             true,
             TraceParams.DEFAULT,
@@ -229,6 +234,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -290,6 +296,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -312,6 +319,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -337,6 +345,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             traceParams,
@@ -385,6 +394,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             traceParams,
@@ -443,6 +453,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             traceParams,
@@ -486,6 +497,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             traceParams,
@@ -529,6 +541,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             traceParams,
@@ -561,6 +574,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -575,6 +589,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -593,6 +608,7 @@ public class SpanImplTest {
             spanContext,
             recordSpanOptions,
             SPAN_NAME,
+            null,
             parentSpanId,
             false,
             TraceParams.DEFAULT,
@@ -603,4 +619,21 @@ public class SpanImplTest {
     exception.expectMessage("Running span does not have the SampleToLocalSpanStore set.");
     span.getSampleToLocalSpanStore();
   }
+
+  @Test
+  public void getSpanKind() {
+    SpanImpl span =
+        SpanImpl.startSpan(
+            spanContext,
+            recordSpanOptions,
+            SPAN_NAME,
+            Kind.SERVER,
+            parentSpanId,
+            false,
+            TraceParams.DEFAULT,
+            startEndHandler,
+            timestampConverter,
+            testClock);
+    assertThat(span.getKind()).isEqualTo(Kind.SERVER);
+  }
 }
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessRunningSpanStoreImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessRunningSpanStoreImplTest.java
index 993b714b..e81df48e 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessRunningSpanStoreImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessRunningSpanStoreImplTest.java
@@ -63,6 +63,7 @@ public class InProcessRunningSpanStoreImplTest {
         spanContext,
         recordSpanOptions,
         spanName,
+        null,
         SpanId.generateRandomId(random),
         false,
         TraceParams.DEFAULT,
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessSampledSpanStoreImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessSampledSpanStoreImplTest.java
index 83aa8164..e1d2c4bb 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessSampledSpanStoreImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/export/InProcessSampledSpanStoreImplTest.java
@@ -93,6 +93,7 @@ public class InProcessSampledSpanStoreImplTest {
         sampledSpanContext,
         recordSpanOptions,
         spanName,
+        null,
         parentSpanId,
         false,
         TraceParams.DEFAULT,
@@ -106,6 +107,7 @@ public class InProcessSampledSpanStoreImplTest {
         notSampledSpanContext,
         recordSpanOptions,
         spanName,
+        null,
         parentSpanId,
         false,
         TraceParams.DEFAULT,
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopRunningSpanStoreImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopRunningSpanStoreImplTest.java
index c0a4ff21..2877bb33 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopRunningSpanStoreImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopRunningSpanStoreImplTest.java
@@ -41,7 +41,7 @@ import org.junit.runners.JUnit4;
 import org.mockito.Mock;
 import org.mockito.MockitoAnnotations;
 
-/** Unit tests for {@link NoopRunningSpanStoreImpl}. */
+/** Unit tests for {@link RunningSpanStoreImpl.NoopRunningSpanStoreImpl}. */
 @RunWith(JUnit4.class)
 public class NoopRunningSpanStoreImplTest {
 
@@ -72,6 +72,7 @@ public class NoopRunningSpanStoreImplTest {
             recordSpanOptions,
             SPAN_NAME,
             null,
+            null,
             false,
             TraceParams.DEFAULT,
             startEndHandler,
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopSampledSpanStoreImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopSampledSpanStoreImplTest.java
index b3355c69..3ba33fd1 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopSampledSpanStoreImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/export/NoopSampledSpanStoreImplTest.java
@@ -44,7 +44,7 @@ import org.junit.runners.JUnit4;
 import org.mockito.Mock;
 import org.mockito.MockitoAnnotations;
 
-/** Unit tests for {@link NoopSampledSpanStoreImpl}. */
+/** Unit tests for {@link SampledSpanStoreImpl.NoopSampledSpanStoreImpl}. */
 @RunWith(JUnit4.class)
 public final class NoopSampledSpanStoreImplTest {
 
@@ -105,6 +105,7 @@ public final class NoopSampledSpanStoreImplTest {
             recordSpanOptions,
             SPAN_NAME,
             null,
+            null,
             false,
             TraceParams.DEFAULT,
             startEndHandler,
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/export/SpanExporterImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/export/SpanExporterImplTest.java
index 9de9c67c..9b471352 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/export/SpanExporterImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/export/SpanExporterImplTest.java
@@ -76,6 +76,7 @@ public class SpanExporterImplTest {
             recordSpanOptions,
             spanName,
             null,
+            null,
             false,
             TraceParams.DEFAULT,
             startEndHandler,
@@ -92,6 +93,7 @@ public class SpanExporterImplTest {
             recordSpanOptions,
             spanName,
             null,
+            null,
             false,
             TraceParams.DEFAULT,
             startEndHandler,