Use enum for MessageEvent Type, Link Type and SpanKind

CHANGELOG.md

@@ -19,6 +19,7 @@ All notable changes to this project will be documented in this file.
 - The ```new Stats()``` has been deprecated on Stats class. The global singleton ```globalStats``` object should be used instead. Also, ```registerView()``` is separated out from ```createView()```.
 - Use ```TagKey```, ```TagValue``` and ```TagMap``` to create the tag keys, tag values.
 - The `status` field on `Span` is no longer a number, use `CanonicalCode` instead.
+- Add enum type for `MessageEvent`, `Link` and `SpanKind`, instead of string.
 
 ##### Old code
 ```js

packages/opencensus-core/src/trace/model/root-span.ts

@@ -52,7 +52,8 @@ export class RootSpan extends SpanBase implements types.RootSpan {
       this.traceStateLocal = context.spanContext.traceState;
     }
     this.spansLocal = [];
-    this.kind = context && context.kind ? context.kind : null;
+    this.kind =
+        context && context.kind ? context.kind : types.SpanKind.UNSPECIFIED;
     this.logger = tracer.logger || logger.logger();
     this.activeTraceParams = tracer.activeTraceParams;
   }
@@ -105,7 +106,7 @@ export class RootSpan extends SpanBase implements types.RootSpan {
    * @param kind Span kind.
    * @param parentSpanId Span parent ID.
    */
-  startChildSpan(name: string, kind: string, parentSpanId?: string):
+  startChildSpan(name: string, kind: types.SpanKind, parentSpanId?: string):
       types.Span {
     if (this.ended) {
       this.logger.debug(

packages/opencensus-core/src/trace/model/span-base.ts

@@ -54,7 +54,7 @@ export abstract class SpanBase implements types.Span {
   /** The resource name of the span */
   name: string = null;
   /** Kind of span. */
-  kind: string = null;
+  kind: types.SpanKind = types.SpanKind.UNSPECIFIED;
   /** A final status for this span */
   status: types.Status = STATUS_OK;
   /** set isRootSpan  */
@@ -189,7 +189,7 @@ export abstract class SpanBase implements types.Span {
    * @param attributes A set of attributes on the link.
    */
   addLink(
-      traceId: string, spanId: string, type: string,
+      traceId: string, spanId: string, type: types.LinkType,
       attributes?: types.Attributes) {
     if (this.links.length >= this.activeTraceParams.numberOfLinksPerSpan) {
       this.links.shift();
@@ -210,12 +210,13 @@ export abstract class SpanBase implements types.Span {
    * @param id An identifier for the message event.
    * @param timestamp A time in milliseconds. Defaults to Date.now()
    */
-  addMessageEvent(type: string, id: string, timestamp = 0) {
+  addMessageEvent(type: types.MessageEventType, id: string, timestamp = 0) {
     if (this.messageEvents.length >=
         this.activeTraceParams.numberOfMessageEventsPerSpan) {
       this.messageEvents.shift();
       this.droppedMessageEventsCount++;
     }
+
     this.messageEvents.push({
       'type': type,
       'id': id,

packages/opencensus-core/src/trace/model/tracer.ts

@@ -236,16 +236,16 @@ export class CoreTracer implements types.Tracer {
   /**
    * Starts a span.
    * @param name The span name.
-   * @param type The span type.
+   * @param kind optional The span kind.
    * @param parentSpanId The parent span ID.
    */
-  startChildSpan(name?: string, type?: string): types.Span {
+  startChildSpan(name?: string, kind?: types.SpanKind): types.Span {
     let newSpan: types.Span = null;
     if (!this.currentRootSpan) {
       this.logger.debug(
           'no current trace found - must start a new root span first');
     } else {
-      newSpan = this.currentRootSpan.startChildSpan(name, type);
+      newSpan = this.currentRootSpan.startChildSpan(name, kind);
     }
     return newSpan;
   }

packages/opencensus-core/src/trace/model/types.ts

@@ -191,7 +191,7 @@ export interface MessageEvent {
   /** A timestamp for the event. */
   timestamp: number;
   /** Indicates whether the message was sent or received. */
-  type: string;
+  type: MessageEventType;
   /** An identifier for the MessageEvent's message. */
   id: string;
   /** The number of uncompressed bytes sent or received. */
@@ -213,7 +213,7 @@ export interface Link {
   /** The span ID for a span within a trace. */
   spanId: string;
   /** The relationship of the current span relative to the linked. */
-  type: string;
+  type: LinkType;
   /** A set of attributes on the link. */
   attributes: Attributes;
 }
@@ -225,7 +225,7 @@ export interface TraceOptions {
   /** Trace context */
   spanContext?: SpanContext;
   /** Span kind */
-  kind?: string;
+  kind?: SpanKind;
 }
 
 export type TraceState = string;
@@ -249,6 +249,51 @@ export interface SpanEventListener {
   onEndSpan(span: RootSpan): void;
 }
 
+/** An event describing a message sent/received between Spans. */
+export enum MessageEventType {
+  /** Unknown event type. */
+  UNSPECIFIED = 0,
+  /** Indicates a sent message. */
+  SENT = 1,
+  /** Indicates a received message. */
+  RECEIVED = 2
+}
+
+/**
+ * Type of span. Can be used to specify additional relationships between spans
+ * in addition to a parent/child relationship.
+ */
+export enum SpanKind {
+  /** Unspecified */
+  UNSPECIFIED = 0,
+  /**
+   * Indicates that the span covers server-side handling of an RPC or other
+   * remote network request.
+   */
+  SERVER = 1,
+  /**
+   * Indicates that the span covers the client-side wrapper around an RPC or
+   * other remote request.
+   */
+  CLIENT = 2
+}
+
+/**
+ * Type of link. The relationship of the current span relative to the linked
+ * span.
+ */
+export enum LinkType {
+  /**
+   * The relationship of the two spans is unknown, or known but other
+   * than parent-child.
+   */
+  UNSPECIFIED = 0,
+  /** The linked span is a child of the current span. */
+  CHILD_LINKED_SPAN = 1,
+  /** The linked span is a parent of the current span. */
+  PARENT_LINKED_SPAN = 2
+}
+
 /** Interface for Span */
 export interface Span {
   /** The Span ID of this span */
@@ -264,7 +309,7 @@ export interface Span {
   name: string;
 
   /** Kind of span. */
-  kind: string;
+  kind: SpanKind;
 
   /** An object to log information to */
   logger: loggerTypes.Logger;
@@ -359,7 +404,7 @@ export interface Span {
    * @param attributes A set of attributes on the link.
    */
   addLink(
-      traceId: string, spanId: string, type: string,
+      traceId: string, spanId: string, type: LinkType,
       attributes?: Attributes): void;
 
   /**
@@ -368,7 +413,7 @@ export interface Span {
    * @param id An identifier for the message event.
    * @param timestamp A timestamp for this event.
    */
-  addMessageEvent(type: string, id: string, timestamp?: number): void;
+  addMessageEvent(type: MessageEventType, id: string, timestamp?: number): void;
 
   /**
    * Sets a status to the span.
@@ -393,7 +438,7 @@ export interface RootSpan extends Span {
   readonly spans: Span[];
 
   /** Starts a new Span instance in the RootSpan instance */
-  startChildSpan(name: string, type: string): Span;
+  startChildSpan(name: string, kind: SpanKind): Span;
 }
 
 
@@ -460,7 +505,7 @@ export interface Tracer extends SpanEventListener {
    * @param parentSpanId Parent SpanId
    * @returns The new Span instance started
    */
-  startChildSpan(name?: string, type?: string, parentSpanId?: string): Span;
+  startChildSpan(name?: string, type?: SpanKind, parentSpanId?: string): Span;
 
   /**
    * Binds the trace context to the given function.

packages/opencensus-core/test/test-console-exporter.ts

@@ -15,6 +15,7 @@
  */
 
 import * as assert from 'assert';
+import {SpanKind} from '../src';
 import {ConsoleExporter, NoopExporter} from '../src/exporters/console-exporter';
 import {RootSpan} from '../src/trace/model/root-span';
 import {CoreTracer} from '../src/trace/model/tracer';
@@ -86,7 +87,7 @@ describe('ConsoleLogExporter', () => {
       const exporter = new ConsoleExporter(defaultBufferConfig);
       const rootSpan = new RootSpan(tracer);
       rootSpan.start();
-      rootSpan.startChildSpan('name', 'type', rootSpan.traceId);
+      rootSpan.startChildSpan('name', SpanKind.UNSPECIFIED, rootSpan.traceId);
       const queue: RootSpan[] = [rootSpan];
 
       return exporter.publish(queue).then(() => {
@@ -98,4 +99,4 @@ describe('ConsoleLogExporter', () => {
       });
     });
   });
-});
+});

packages/opencensus-core/test/test-exporter-buffer.ts

@@ -15,6 +15,7 @@
  */
 
 import * as assert from 'assert';
+import {SpanKind} from '../src';
 import * as logger from '../src/common/console-logger';
 import {NoopExporter} from '../src/exporters/console-exporter';
 import {ExporterBuffer} from '../src/exporters/exporter-buffer';
@@ -40,7 +41,7 @@ const createRootSpans = (num: number): RootSpan[] => {
     const rootSpan = new RootSpan(tracer, {name: `rootSpan.${i}`});
     rootSpan.start();
     for (let j = 0; j < 10; j++) {
-      rootSpan.startChildSpan(`childSpan.${i}.${j}`, 'client');
+      rootSpan.startChildSpan(`childSpan.${i}.${j}`, SpanKind.CLIENT);
     }
     rootSpans.push(rootSpan);
   }

packages/opencensus-core/test/test-root-span.ts

@@ -56,9 +56,10 @@ describe('RootSpan', () => {
       // TODO: Suggetion: make sure that root.spans.length is 1,
       // and that it's the same as the earlier (shadowed) span object
       root.start();
-      const span = root.startChildSpan('spanName', 'spanType');
+      const span = root.startChildSpan('spanName', types.SpanKind.CLIENT);
       assert.strictEqual(root.spans.length, 1);
       assert.strictEqual(span, root.spans[0]);
+      assert.strictEqual(span.kind, types.SpanKind.CLIENT);
       assert.strictEqual(root.parentSpanId, null);
 
       for (const span of root.spans) {
@@ -97,7 +98,7 @@ describe('RootSpan', () => {
     before(() => {
       root = new RootSpan(tracer);
       root.start();
-      span = root.startChildSpan('spanName', 'spanType');
+      span = root.startChildSpan('spanName', types.SpanKind.UNSPECIFIED);
     });
 
     it('should create span instance', () => {
@@ -115,7 +116,7 @@ describe('RootSpan', () => {
   describe('startSpan() before start rootspan', () => {
     it('should not create span', () => {
       const root = new RootSpan(tracer);
-      const span = root.startChildSpan('spanName', 'spanType');
+      const span = root.startChildSpan('spanName', types.SpanKind.UNSPECIFIED);
       assert.strictEqual(span, null);
     });
   });
@@ -128,7 +129,7 @@ describe('RootSpan', () => {
       const root = new RootSpan(tracer);
       root.start();
       root.end();
-      const span = root.startChildSpan('spanName', 'spanType');
+      const span = root.startChildSpan('spanName', types.SpanKind.UNSPECIFIED);
       assert.strictEqual(span, null);
     });
   });
@@ -163,7 +164,7 @@ describe('RootSpan', () => {
     it('should end all spans inside rootspan', () => {
       const root = new RootSpan(tracer);
       root.start();
-      root.startChildSpan('spanName', 'spanType');
+      root.startChildSpan('spanName', types.SpanKind.UNSPECIFIED);
       root.end();
 
       for (const span of root.spans) {
@@ -227,8 +228,8 @@ describe('RootSpan', () => {
       const span = new Span(rootSpan);
       span.start();
 
-      const LINK_TYPE = 'CHILD_LINKED_SPAN';
-      rootSpan.addLink(rootSpan.traceId, span.id, LINK_TYPE);
+      rootSpan.addLink(
+          rootSpan.traceId, span.id, types.LinkType.CHILD_LINKED_SPAN);
 
       assert.ok(rootSpan.links.length > 0);
       assert.equal(rootSpan.droppedLinksCount, 0);
@@ -249,7 +250,8 @@ describe('RootSpan', () => {
       const rootSpan = new RootSpan(tracer);
       rootSpan.start();
 
-      rootSpan.addMessageEvent('TYPE_UNSPECIFIED', 'message_event_test_id');
+      rootSpan.addMessageEvent(
+          types.MessageEventType.UNSPECIFIED, 'message_event_test_id');
 
       assert.ok(rootSpan.messageEvents.length > 0);
       assert.equal(rootSpan.droppedMessageEventsCount, 0);

packages/opencensus-core/test/test-span.ts

@@ -263,8 +263,8 @@ describe('Span', () => {
       const span = new Span(rootSpan);
       span.start();
 
-      const LINK_TYPE = 'PARENT_LINKED_SPAN';
-      span.addLink(span.traceId, rootSpan.id, LINK_TYPE);
+      span.addLink(
+          span.traceId, rootSpan.id, types.LinkType.PARENT_LINKED_SPAN);
 
       assert.ok(span.links.length > 0);
       assert.equal(span.droppedLinksCount, 0);
@@ -277,9 +277,9 @@ describe('Span', () => {
       const span = new Span(rootSpan);
       span.start();
 
-      const LINK_TYPE = 'PARENT_LINKED_SPAN';
       for (let i = 0; i < 35; i++) {
-        span.addLink(span.traceId, rootSpan.id, LINK_TYPE);
+        span.addLink(
+            span.traceId, rootSpan.id, types.LinkType.PARENT_LINKED_SPAN);
       }
 
       assert.equal(span.links.length, 32);
@@ -303,7 +303,8 @@ describe('Span', () => {
       const span = new Span(rootSpan);
       span.start();
 
-      span.addMessageEvent('TYPE_UNSPECIFIED', 'message_event_test_id');
+      span.addMessageEvent(
+          types.MessageEventType.UNSPECIFIED, 'message_event_test_id');
 
       assert.ok(span.messageEvents.length > 0);
       assert.equal(span.droppedMessageEventsCount, 0);
@@ -317,7 +318,8 @@ describe('Span', () => {
       const span = new Span(rootSpan);
       span.start();
       for (let i = 0; i < 35; i++) {
-        span.addMessageEvent('TYPE_UNSPECIFIED', 'message_event_test_id');
+        span.addMessageEvent(
+            types.MessageEventType.UNSPECIFIED, 'message_event_test_id');
       }
 
       assert.equal(span.messageEvents.length, 32);

packages/opencensus-core/test/test-tracer.ts

@@ -194,7 +194,7 @@ describe('Tracer', () => {
   });
 
   describe('startRootSpan() with context propagation', () => {
-    const traceOptions = {name: 'rootName', kind: 'spanType'} as
+    const traceOptions = {name: 'rootName', kind: types.SpanKind.UNSPECIFIED} as
         types.TraceOptions;
 
     it('should create new RootSpan instance, no propagation', () => {
@@ -295,7 +295,7 @@ describe('Tracer', () => {
       const tracer = new CoreTracer();
       tracer.start(defaultConfig);
       tracer.startRootSpan(options, (rootSpan) => {
-        span = tracer.startChildSpan('spanName', 'spanType');
+        span = tracer.startChildSpan('spanName', types.SpanKind.CLIENT);
       });
     });
     it('should create a Span instance', () => {
@@ -304,7 +304,7 @@ describe('Tracer', () => {
     it('should start a span', () => {
       assert.ok(span.started);
       assert.strictEqual(span.name, 'spanName');
-      assert.strictEqual(span.kind, 'spanType');
+      assert.strictEqual(span.kind, types.SpanKind.CLIENT);
     });
   });
 
@@ -313,7 +313,8 @@ describe('Tracer', () => {
     it('should not create a Span instance, without a rootspan', () => {
       const tracer = new CoreTracer();
       tracer.start(defaultConfig);
-      const span = tracer.startChildSpan('spanName', 'spanType');
+      const span =
+          tracer.startChildSpan('spanName', types.SpanKind.UNSPECIFIED);
       assert.equal(span, null);
     });
   });