feat: added spans optional parameters

Author: eduardoemery

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

@@ -17,7 +17,8 @@
 import { Clock } from '../../internal/clock';
 import { debug, randomSpanId } from '../../internal/util';
 import { Sampler } from '../config/types';
-import { TraceContext, Span, MapLabels, MapObjects } from './types';
+import { TraceContext, Span, Annotation, Attributes,
+    Link, MessageEvent } from './types';
 
 
 export abstract class SpanBaseModel implements Span {
@@ -28,16 +29,20 @@ export abstract class SpanBaseModel implements Span {
     private startedLocal = false;
     /** Indicates if this span was ended */
     private endedLocal = false;
-    /** A set of attributes, each in the format [KEY]:[VALUE] */
-    private attributes: MapLabels = {};
-    /** A set of attributes on the annotation describing an event */
-    private annotations: MapObjects = {};
     /** Indicates if this span was forced to end */
     private truncated = false;
     /** The Span ID of this span */
     readonly id: string;
-
-    remoteParent: string;
+    /** A set of attributes, each in the format [KEY]:[VALUE] */
+    attributes: Attributes = {};
+    /** A text annotation with a set of attributes. */
+    annotations: Annotation[] = [];
+    /** An event describing a message sent/received between Spans. */
+    messageEvents: MessageEvent[] = [];
+    /** Pointers from the current span to another span */
+    links: Link[] = [];
+    /** If the parent span is in another process. */
+    remoteParent: boolean;
     /** The span ID of this span's parent. If it's a root span, must be empty */
     parentSpanId: string = null;
     /** The resource name of the span */
@@ -56,7 +61,8 @@ export abstract class SpanBaseModel implements Span {
     }
 
     abstract get traceId(): string;
-  
+
+      
     /** Indicates if span was started. */
     get started(): boolean {
       return this.startedLocal;
@@ -120,19 +126,52 @@ export abstract class SpanBaseModel implements Span {
      * @param key Describes the value added.
      * @param value The result of an operation.
      */
-    addAtribute(key: string, value: string) {
-      // TODO: maybe key and values must be truncate
+    addAtribute(key: string, value: string | number | boolean) {
       this.attributes[key] = value;
     }
 
     /**
      * Adds an annotation to the span.
-     * @param key Describes the value added.
-     * @param value The result of an operation.
+     * @param description Describes the event.
+     * @param timestamp A timestamp that maks the event.
+     * @param attributes A set of attributes on the annotation.
+     */
+    addAnnotation(description: string, timestamp: number,
+        attributes?: Attributes) {
+      this.annotations.push({
+        description: description,
+        timestamp: timestamp,
+        attributes: attributes,
+      } as Annotation)
+    }
+
+    /**
+     * Adds a link to the span.
+     * @param traceId The trace ID for a trace within a project.
+     * @param spanId The span ID for a span within a trace.
+     * @param type The relationship of the current span relative to the linked.
+     * @param attributes A set of attributes on the link.
+     */
+    addLink(traceId: string, spanId: string, type: string,
+        attributes?: Attributes) {
+      this.links.push({
+        traceId: traceId,
+        SpanId: spanId,
+        type: type,
+        attributes: attributes
+      } as Link)
+    }
+
+    /**
+     * Adds a message event to the span.
+     * @param type The type of message event.
+     * @param id An identifier for the message event.
      */
-    addAnotation(key: string, value: string|number|boolean) {
-      // TODO: maybe keys and values must be truncate
-      this.annotations[key] = value;
+    addMessageEvent(type: string, id: string) {
+      this.messageEvents.push({
+        type: type,
+        id: id,
+      } as MessageEvent)
     }
 
     /** Starts a span. */

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

@@ -19,11 +19,41 @@ import { Sampler } from '../config/types';
 /** Default type for functions */
 export type Func<T> = (...args: any[]) => T;
 
-/** Maps a label to a string. Used in spans' attributes. */
-export interface MapLabels { [propName: string]: string; }
+/** Maps a label to a string, number or boolean. */
+export interface Attributes { [attributeKey: string]: string|number|boolean; }
 
-/** Maps a label to a string, number or boolean. Used in spans' annotations. */
-export interface MapObjects { [propName: string]: string|number|boolean; }
+/** A text annotation with a set of attributes. */
+export interface Annotation {
+  /** A user-supplied message describing the event. */
+  description: string,
+  /** A timestamp that maks the event. */
+  timestamp: number,
+  /** A set of attributes on the annotation. */
+  attributes: Attributes
+}
+
+/** An event describing a message sent/received between Spans. */
+export interface MessageEvent {
+  /** Indicates whether the message was sent or received. */
+  type: string,
+  /** An identifier for the MessageEvent's message. */
+  id: string,
+}
+
+/**
+ * A pointer from the current span to another span in the same trace or in a
+ * different trace.
+ */
+export interface Link {
+  /** The trace ID for a trace within a project. */
+  traceId: string,
+  /** The span ID for a span within a trace. */
+  SpanId: string,
+  /** The relationship of the current span relative to the linked. */
+  type: string,
+  /** A set of attributes on the link. */
+  attributes: Attributes
+}
 
 /** Defines tracer configuration parameters */
 export interface TracerConfig {
@@ -76,7 +106,8 @@ export interface Span  {
 
     /** The Span ID of this span */
     readonly id: string;
-    remoteParent: string;
+    /** If the parent span is in another process. */
+    remoteParent: boolean;
     /** The span ID of this span's parent. If it's a root span, must be empty */
     parentSpanId: string;
     /** The resource name of the span */
@@ -85,6 +116,14 @@ export interface Span  {
     type: string;
     /** A final status for this span */
     status: number;
+    /** A set of attributes, each in the format [KEY]:[VALUE] */
+    attributes: Attributes;
+    /** A text annotation with a set of attributes. */
+    annotations: Annotation[];
+    /** An event describing a message sent/received between Spans. */
+    messageEvents: MessageEvent[];
+    /** Pointers from the current span to another span */
+    links: Link[];
     /** A sampler that will decide if the span will be sampled or not */
     sampler: Sampler;
     /** Constructs a new SpanBaseModel instance. */
@@ -118,10 +157,27 @@ export interface Span  {
     addAtribute(key: string, value: string): void;
     /**
      * Adds an annotation to the span.
-     * @param key Describes the value added.
-     * @param value The result of an operation.
+     * @param description Describes the event.
+     * @param timestamp A timestamp that maks the event.
+     * @param attributes A set of attributes on the annotation.
+     */
+    addAnnotation(description: string, timestamp: number,
+        attributes?: Attributes): void;
+    /**
+     * Adds a link to the span.
+     * @param traceId The trace ID for a trace within a project.
+     * @param spanId The span ID for a span within a trace.
+     * @param type The relationship of the current span relative to the linked.
+     * @param attributes A set of attributes on the link.
+     */
+    addLink(traceId: string, spanId: string, type: string,
+      attributes?: Attributes): void;
+    /**
+     * Adds a message event to the span.
+     * @param type The type of message event.
+     * @param id An identifier for the message event.
      */
-    addAnotation(key: string, value: string | number | boolean): void;
+    addMessageEvent(type: string, id: string): void;
     /** Starts a span. */
     start(): void;
     /** Ends a span. */

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

@@ -20,7 +20,8 @@ import * as mocha from 'mocha';
 import {RootSpanImpl} from '../src/trace/model/rootspan';
 import {SpanImpl} from '../src/trace/model/span';
 import {TracerImpl} from '../src/trace/model/tracer';
-import {RootSpan, Span, TraceOptions, Tracer} from '../src/trace/model/types';
+import {RootSpan, Span, TraceOptions, Tracer, Link, Annotation, Attributes, MessageEvent}
+    from '../src/trace/model/types';
 
 const tracer = new TracerImpl();
 
@@ -167,4 +168,90 @@ describe('RootSpan', () => {
       }
     });
   });
+
+
+  /**
+   * Should add an attrinbutes
+   */
+  describe('addAtribute()', function() {
+    it('should add an attribute', function() {
+      const rootSpan = new RootSpanImpl(tracer);
+      rootSpan.start();
+
+      ['String', 'Number', 'Boolean'].map(attType => {
+        rootSpan.addAtribute('testKey'+attType, 'testValue'+attType) 
+        assert.equal(rootSpan.attributes['testKey'+attType], 'testValue'+attType);
+      })
+    });
+  });
+
+  /**
+   * Should add an annotation
+   */
+  describe('addAnnotation()', function() {
+    it('should add an annotation', function() {
+
+      function instanceOfAnnotation(object: any): object is Annotation {
+        return 'description' in object
+            && 'timestamp' in object
+            && 'attributes' in object
+      }
+
+      const rootSpan = new RootSpanImpl(tracer);
+      rootSpan.start();
+
+      rootSpan.addAnnotation('description test', Date.now(), {} as Attributes);
+      
+      assert.ok(rootSpan.annotations.length > 0)
+      assert.ok(instanceOfAnnotation(rootSpan.annotations[0]))
+    });
+  });
+
+  /**
+   * Should add a Link.
+   */
+  describe('addLink()', function() {
+    it('should add a Link', function() {
+
+      function instanceOfLink(object: any): object is Link {
+        return 'traceId' in object
+            && 'SpanId' in object
+            && 'type' in object
+      }
+
+      const rootSpan = new RootSpanImpl(tracer);
+      rootSpan.start();
+      
+      const span = new SpanImpl(rootSpan);
+      span.start();
+
+      const LINK_TYPE = 'CHILD_LINKED_SPAN'
+      rootSpan.addLink(rootSpan.traceId, span.id, LINK_TYPE)
+      
+      assert.ok(rootSpan.links.length > 0)
+      assert.ok(instanceOfLink(rootSpan.links[0]))
+    });
+  });
+
+  /**
+   * Should add a Message Event.
+   */
+  describe('addMessageEvent()', function() {
+    it('should add a Message Event', function() {
+
+      function instanceOfLink(object: any): object is Link {
+        return 'type' in object
+            && 'id' in object
+      }
+
+      const rootSpan = new RootSpanImpl(tracer);
+      rootSpan.start();
+
+      rootSpan.addMessageEvent('TYPE_UNSPECIFIED', 'message_event_test_id')
+      
+      assert.ok(rootSpan.messageEvents.length > 0)
+      assert.ok(instanceOfLink(rootSpan.messageEvents[0]))
+    });
+  });
+
 });