add option of passing in an object to the createChildSpan (#349)

Author: mayurkale22

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to this project will be documented in this file.
 - Add optional `compressedSize` and `uncompressedSize` params to `Span.addMessageEvent`
 - Add support for ```tags```, ```status``` and ```annotation``` in Zipkin exporter.
 - Add support for Binary propagation format.
+- Add support for object(```SpanOptions```) as an argument for ```startChildSpan``` function, similar to ```startRootSpan```.
 
 ## 0.0.9 - 2019-02-12
 - Add Metrics API.

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

@@ -106,8 +106,9 @@ export class RootSpan extends SpanBase implements types.RootSpan {
    * @param kind Span kind.
    * @param parentSpanId Span parent ID.
    */
-  startChildSpan(name: string, kind: types.SpanKind, parentSpanId?: string):
-      types.Span {
+  startChildSpan(
+      nameOrOptions?: string|types.SpanOptions, kind?: types.SpanKind,
+      parentSpanId?: string): types.Span {
     if (this.ended) {
       this.logger.debug(
           'calling %s.startSpan() on ended %s %o', this.className,
@@ -121,11 +122,21 @@ export class RootSpan extends SpanBase implements types.RootSpan {
       return null;
     }
     const newSpan = new Span(this);
-    if (name) {
-      newSpan.name = name;
+    let spanName;
+    let spanKind;
+    if (typeof nameOrOptions === 'object') {
+      spanName = nameOrOptions.name;
+      spanKind = nameOrOptions.kind;
+    } else {
+      spanName = nameOrOptions;
+      spanKind = kind;
     }
-    if (kind) {
-      newSpan.kind = kind;
+
+    if (spanName) {
+      newSpan.name = spanName;
+    }
+    if (spanKind) {
+      newSpan.kind = spanKind;
     }
     newSpan.start();
     this.spansLocal.push(newSpan);

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

@@ -239,13 +239,15 @@ export class CoreTracer implements types.Tracer {
    * @param kind optional The span kind.
    * @param parentSpanId The parent span ID.
    */
-  startChildSpan(name?: string, kind?: types.SpanKind): types.Span {
+  startChildSpan(
+      nameOrOptions?: string|types.SpanOptions,
+      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, kind);
+      newSpan = this.currentRootSpan.startChildSpan(nameOrOptions, kind);
     }
     return newSpan;
   }

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

@@ -234,6 +234,16 @@ export interface TraceOptions {
   kind?: SpanKind;
 }
 
+/** Defines the span options */
+export interface SpanOptions {
+  /** Span name */
+  name: string;
+  /** Span kind */
+  kind?: SpanKind;
+  /** Span parent ID */
+  parentSpanId?: string;
+}
+
 export type TraceState = string;
 
 /** Defines the span context */
@@ -449,7 +459,9 @@ export interface RootSpan extends Span {
   readonly spans: Span[];
 
   /** Starts a new Span instance in the RootSpan instance */
-  startChildSpan(name: string, kind: SpanKind): Span;
+  startChildSpan(name?: string, kind?: SpanKind, parentSpanId?: string): Span;
+  startChildSpan(options?: SpanOptions): Span;
+  startChildSpan(nameOrOptions?: string|SpanOptions, kind?: SpanKind): Span;
 }
 
 
@@ -514,9 +526,11 @@ export interface Tracer extends SpanEventListener {
    * @param name Span name
    * @param type Span type
    * @param parentSpanId Parent SpanId
+   * @param options Span Options
    * @returns The new Span instance started
    */
   startChildSpan(name?: string, type?: SpanKind, parentSpanId?: string): Span;
+  startChildSpan(options?: SpanOptions): Span;
 
   /**
    * Binds the trace context to the given function.

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

@@ -56,7 +56,9 @@ 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', types.SpanKind.CLIENT);
+      const span =
+          root.startChildSpan({name: 'spanName', kind: types.SpanKind.CLIENT});
+
       assert.strictEqual(root.spans.length, 1);
       assert.strictEqual(span, root.spans[0]);
       assert.strictEqual(span.kind, types.SpanKind.CLIENT);

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

@@ -291,8 +291,9 @@ describe('Tracer', () => {
   /** Should create and start a Span instance into a rootSpan */
   describe('startChildSpan()', () => {
     let span: types.Span;
+    let tracer: types.Tracer;
     before(() => {
-      const tracer = new CoreTracer();
+      tracer = new CoreTracer();
       tracer.start(defaultConfig);
       tracer.startRootSpan(options, (rootSpan) => {
         span = tracer.startChildSpan('spanName', types.SpanKind.CLIENT);
@@ -306,15 +307,46 @@ describe('Tracer', () => {
       assert.strictEqual(span.name, 'spanName');
       assert.strictEqual(span.kind, types.SpanKind.CLIENT);
     });
+
+    it('should start a span with SpanObject', () => {
+      let spanWithObject: types.Span;
+      tracer.startRootSpan(options, (rootSpan) => {
+        spanWithObject = tracer.startChildSpan(
+            {name: 'my-span', kind: types.SpanKind.SERVER});
+      });
+      assert.ok(spanWithObject.started);
+      assert.strictEqual(spanWithObject.name, 'my-span');
+      assert.strictEqual(spanWithObject.kind, types.SpanKind.SERVER);
+    });
+
+    it('should start a span with SpanObject-name', () => {
+      let spanWithObject: types.Span;
+      tracer.startRootSpan(options, (rootSpan) => {
+        spanWithObject = tracer.startChildSpan({name: 'my-span1'});
+      });
+      assert.ok(spanWithObject.started);
+      assert.strictEqual(spanWithObject.name, 'my-span1');
+      assert.strictEqual(spanWithObject.kind, types.SpanKind.UNSPECIFIED);
+    });
+
+    it('should start a span without params', () => {
+      let spanWithObject: types.Span;
+      tracer.startRootSpan(options, (rootSpan) => {
+        spanWithObject = tracer.startChildSpan();
+      });
+      assert.ok(spanWithObject.started);
+      assert.strictEqual(spanWithObject.name, null);
+      assert.strictEqual(spanWithObject.kind, types.SpanKind.UNSPECIFIED);
+    });
   });
 
   /** Should not create a Span instance */
   describe('startChildSpan() before startRootSpan()', () => {
     it('should not create a Span instance, without a rootspan', () => {
       const tracer = new CoreTracer();
       tracer.start(defaultConfig);
-      const span =
-          tracer.startChildSpan('spanName', types.SpanKind.UNSPECIFIED);
+      const span = tracer.startChildSpan(
+          {name: 'spanName', kind: types.SpanKind.UNSPECIFIED});
       assert.equal(span, null);
     });
   });

packages/opencensus-exporter-instana/test/test-instana.ts

@@ -60,8 +60,8 @@ describe('Instana Exporter', function() {
           .startRootSpan(
               {name: 'root-test'},
               async (rootSpan: RootSpan) => {
-                const span =
-                    rootSpan.startChildSpan('spanTest', SpanKind.CLIENT);
+                const span = rootSpan.startChildSpan(
+                    {name: 'spanTest', kind: SpanKind.CLIENT});
                 span.end();
                 rootSpan.end();
                 return exporter.publish([rootSpan, rootSpan]);

packages/opencensus-exporter-zipkin/test/test-zipkin.ts

@@ -74,7 +74,8 @@ describe('Zipkin Exporter', function() {
       tracer.start(defaultConfig);
 
       tracer.startRootSpan({name: 'root-test'}, (rootSpan: RootSpan) => {
-        const span = rootSpan.startChildSpan('spanTest', SpanKind.CLIENT);
+        const span =
+            rootSpan.startChildSpan({name: 'spanTest', kind: SpanKind.CLIENT});
         span.end();
         rootSpan.end();
         assert.ok(exporter.buffer.getQueue().length > 0);
@@ -91,7 +92,8 @@ describe('Zipkin Exporter', function() {
 
       return tracer.startRootSpan(
           {name: 'root-test'}, async (rootSpan: RootSpan) => {
-            const span = rootSpan.startChildSpan('spanTest', SpanKind.CLIENT);
+            const span = rootSpan.startChildSpan(
+                {name: 'spanTest', kind: SpanKind.CLIENT});
             span.end();
             rootSpan.end();
             return exporter.publish([rootSpan, rootSpan]).then((result) => {
@@ -108,7 +110,8 @@ describe('Zipkin Exporter', function() {
       tracer.start(defaultConfig);
 
       return tracer.startRootSpan({name: 'root-test'}, (rootSpan: RootSpan) => {
-        const span = rootSpan.startChildSpan('spanTest', SpanKind.CLIENT);
+        const span =
+            rootSpan.startChildSpan({name: 'spanTest', kind: SpanKind.CLIENT});
         span.addAttribute('my-int-attribute', 100);
         span.addAttribute('my-str-attribute', 'value');
         span.addAttribute('my-bool-attribute', true);
@@ -183,8 +186,8 @@ describe('Zipkin Exporter', function() {
 
          return tracer.startRootSpan(
              {name: 'root-test'}, async (rootSpan: RootSpan) => {
-               const span =
-                   rootSpan.startChildSpan('spanTest', SpanKind.CLIENT);
+               const span = rootSpan.startChildSpan(
+                   {name: 'spanTest', kind: SpanKind.CLIENT});
                span.end();
                rootSpan.end();
                return exporter.publish([rootSpan]).then((result) => {

packages/opencensus-exporter-zpages/test/test-zpages.ts

@@ -14,11 +14,12 @@
  * limitations under the License.
  */
 
-import {AggregationType, CountData, DistributionData, globalStats, Measure, Measurement, MeasureUnit, RootSpan, SumData, TagMap, TracerConfig} from '@opencensus/core';
+import {AggregationType, CountData, DistributionData, globalStats, Measure, Measurement, MeasureUnit, RootSpan, SpanKind, SumData, TagMap, TracerConfig} from '@opencensus/core';
 import * as assert from 'assert';
 import axios from 'axios';
 import * as http from 'http';
 import * as qs from 'querystring';
+
 import {ZpagesExporter, ZpagesExporterOptions} from '../src/zpages';
 import {RpczData} from '../src/zpages-frontend/page-handlers/rpcz.page-handler';
 import {StatsViewData, StatszParams} from '../src/zpages-frontend/page-handlers/statsz.page-handler';
@@ -133,8 +134,8 @@ describe('Zpages Exporter', () => {
 
       tracing.tracer.startRootSpan(
           {name: 'rootSpanTest'}, (rootSpan: RootSpan) => {
-            const span =
-                tracing.tracer.startChildSpan('spanNameTest', 'spanType');
+            const span = tracing.tracer.startChildSpan(
+                {name: 'spanNameTest', kind: SpanKind.CLIENT});
             span.end();
             rootSpan.end();
           });

packages/opencensus-instrumentation-grpc/src/grpc.ts

@@ -319,7 +319,7 @@ export class GrpcPlugin extends BasePlugin {
               plugin.makeGrpcClientRemoteCall(original, args, this, plugin));
         } else {
           const span = plugin.tracer.startChildSpan(
-              traceOptions.name, traceOptions.kind);
+              {name: traceOptions.name, kind: traceOptions.kind});
           return (plugin.makeGrpcClientRemoteCall(
               original, args, this, plugin))(span);
         }

packages/opencensus-instrumentation-http/src/http.ts

@@ -323,7 +323,7 @@ export class HttpPlugin extends BasePlugin {
         } else {
           plugin.logger.debug('outgoingRequest starting a child span');
           const span = plugin.tracer.startChildSpan(
-              traceOptions.name, traceOptions.kind);
+              {name: traceOptions.name, kind: traceOptions.kind});
           return (plugin.getMakeRequestTraceFunction(request, options, plugin))(
               span);
         }

packages/opencensus-instrumentation-http2/src/http2.ts

@@ -112,7 +112,7 @@ export class Http2Plugin extends HttpPlugin {
                   request, headers, authority, plugin));
         } else {
           const span = plugin.tracer.startChildSpan(
-              traceOptions.name, traceOptions.kind);
+              {name: traceOptions.name, kind: traceOptions.kind});
           return (plugin.getMakeHttp2RequestTraceFunction(
               request, headers, authority, plugin))(span);
         }

packages/opencensus-instrumentation-mongodb/src/mongodb.ts

@@ -96,8 +96,8 @@ export class MongoDBPlugin extends BasePlugin {
             type = 'command';
           }
 
-          const span =
-              plugin.tracer.startChildSpan(ns + '.' + type, SpanKind.SERVER);
+          const span = plugin.tracer.startChildSpan(
+              {name: `${ns}.${type}`, kind: SpanKind.SERVER});
           resultHandler = plugin.patchEnd(span, resultHandler);
         }
 
@@ -116,8 +116,8 @@ export class MongoDBPlugin extends BasePlugin {
             let resultHandler = args[args.length - 1];
             if (plugin.tracer.currentRootSpan && arguments.length > 0 &&
                 typeof resultHandler === 'function') {
-              const span =
-                  plugin.tracer.startChildSpan(ns + '.query', SpanKind.SERVER);
+              const span = plugin.tracer.startChildSpan(
+                  {name: `${ns}.query`, kind: SpanKind.SERVER});
               resultHandler = plugin.patchEnd(span, resultHandler);
             }
 
@@ -136,7 +136,7 @@ export class MongoDBPlugin extends BasePlugin {
         if (plugin.tracer.currentRootSpan && arguments.length > 0 &&
             typeof resultHandler === 'function') {
           const span = plugin.tracer.startChildSpan(
-              this.ns + '.cursor', SpanKind.SERVER);
+              {name: `${this.ns}.cursor`, kind: SpanKind.SERVER});
           resultHandler = plugin.patchEnd(span, resultHandler);
         }