[PROPOSAL] feat(tracer): separate cls out of tracer

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

@@ -105,10 +105,9 @@ export class CoreTracerBase implements types.TracerBase {
   /**
    * Starts a root span.
    * @param options A TraceOptions object to start a root span.
-   * @param fn A callback function to run after starting a root span.
+   * @returns {Span} A new root span.
    */
-  startRootSpan<T>(options: types.TraceOptions, fn: (root: types.Span) => T):
-      T {
+  startRootSpan(options: types.TraceOptions): types.Span {
     const spanContext: types.SpanContext = options.spanContext ||
         {spanId: '', traceId: uuid.v4().split('-').join('')};
     const parentSpanId = spanContext.spanId;
@@ -125,21 +124,21 @@ export class CoreTracerBase implements types.TracerBase {
         const rootSpan =
             new RootSpan(this, name, kind, traceId, parentSpanId, traceState);
         rootSpan.start();
-        return fn(rootSpan);
+        return rootSpan;
       }
 
       // Sampling is off
       this.logger.debug('Sampling is off, starting new no record root span');
       const noRecordRootSpan = new NoRecordRootSpan(
           this, name, kind, traceId, parentSpanId, traceState);
-      return fn(noRecordRootSpan);
+      return noRecordRootSpan;
     }
 
     // Tracer is inactive
     this.logger.debug('Tracer is inactive, starting new no record root span');
     const noRecordRootSpan = new NoRecordRootSpan(
         this, name, kind, traceId, parentSpanId, traceState);
-    return fn(noRecordRootSpan);
+    return noRecordRootSpan;
   }
 
   /** Notifies listeners of the span start. */

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

@@ -51,48 +51,29 @@ export class CoreTracer extends CoreTracerBase implements types.Tracer {
       this.contextManager.set('rootspan', root);
     }
   }
-
   /**
-   * Starts a root span.
-   * @param options A TraceOptions object to start a root span.
-   * @param fn A callback function to run after starting a root span.
+   * Sets span to CLS
+   * @param span Span to setup in context.
+   * @param fn A callback function that runs after context setup.
    */
-  startRootSpan<T>(options: types.TraceOptions, fn: (root: types.Span) => T):
-      T {
+  withSpan<T>(span: types.Span, fn: () => T): T {
     const self = this;
     return self.contextManager.runAndReturn(() => {
-      return super.startRootSpan(options, (root) => {
-        self.currentRootSpan = root;
-        return fn(root);
-      });
+      self.currentRootSpan = span;
+      return fn();
     });
   }
-
-  /** Notifies listeners of the span start. */
-  onStartSpan(root: types.Span): void {
-    if (!this.active) return;
-    if (!root) {
-      return this.logger.debug('cannot start trace - no active trace found');
-    }
-    if (this.currentRootSpan !== root) {
-      this.logger.debug(
-          'currentRootSpan != root on notifyStart. Need more investigation.');
-    }
-    return super.onStartSpan(root);
-  }
-
-  /** Notifies listeners of the span end. */
-  onEndSpan(root: types.Span): void {
-    if (!this.active) return;
-    if (!root) {
-      this.logger.debug('cannot end trace - no active trace found');
-      return;
-    }
-    if (this.currentRootSpan !== root) {
-      this.logger.debug(
-          'currentRootSpan != root on notifyEnd. Need more investigation.');
-    }
-    super.onEndSpan(root);
+  /**
+   * Starts a root span and sets it to context.
+   * @param options A TraceOptions object to start a root span.
+   * @returns {Span} A new root span.
+   */
+  startWithRootSpan<T>(
+      options: types.TraceOptions, fn: (root: types.Span) => T): T {
+    const rootSpan = this.startRootSpan(options);
+    return this.withSpan(rootSpan, () => {
+      return fn(rootSpan);
+    });
   }
 
   /** Clears the current root span. */
@@ -113,7 +94,11 @@ export class CoreTracer extends CoreTracerBase implements types.Tracer {
     }
 
     return super.startChildSpan(Object.assign(
-        {childOf: this.currentRootSpan || new NoRecordSpan()}, options));
+        {
+          childOf: (options && options.childOf) || this.currentRootSpan ||
+              new NoRecordSpan()
+        },
+        options));
   }
 
   /**

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

@@ -497,9 +497,17 @@ export interface TracerBase extends SpanEventListener {
    * Start a new RootSpan to currentRootSpan
    * @param options Options for tracer instance
    * @param fn Callback function
-   * @returns The callback return
+   * @returns {Span} A root span
    */
-  startRootSpan<T>(options: TraceOptions, fn: (root: Span) => T): T;
+  startRootSpan(options: TraceOptions): Span;
+
+  /**
+   * Start a new Span instance to the currentRootSpan
+   * @param childOf Span
+   * @param [options] A TraceOptions object to start a root span.
+   * @returns The new Span instance started
+   */
+  startChildSpan(options?: SpanOptions): Span;
 
   /**
    * Register a OnEndSpanEventListener on the tracer instance
@@ -512,14 +520,6 @@ export interface TracerBase extends SpanEventListener {
    * @param listener The listener to unregister.
    */
   unregisterSpanEventListener(listener: SpanEventListener): void;
-
-  /**
-   * Start a new Span instance to the currentRootSpan
-   * @param childOf Span
-   * @param [options] A TraceOptions object to start a root span.
-   * @returns The new Span instance started
-   */
-  startChildSpan(options?: SpanOptions): Span;
 }
 
 /** Interface for Tracer */
@@ -530,6 +530,20 @@ export interface Tracer extends TracerBase {
   /** Clear the currentRootSpan from tracer instance */
   clearCurrentTrace(): void;
 
+  /**
+   * Sets span to CLS
+   * @param span Span to setup in context.
+   * @param fn A callback function that runs after context setup.
+   */
+  withSpan<T>(span: Span, fn: () => T): T;
+
+  /**
+   * Starts a root span and sets it to context.
+   * @param options Options for tracer instance
+   * @param fn A callback function to run after starting a root span.
+   */
+  startWithRootSpan<T>(options: TraceOptions, fn: (root: Span) => T): T;
+
   /**
    * Binds the trace context to the given function.
    * This is necessary in order to create child spans correctly in functions

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

@@ -19,7 +19,7 @@ import * as configTypes from './config/types';
 import * as modelTypes from './model/types';
 
 /** Main interface for tracing. */
-export interface Tracing {
+export interface TracingBase {
   /** Object responsible for managing a trace. */
   readonly tracer: modelTypes.TracerBase;
 
@@ -52,3 +52,9 @@ export interface Tracing {
    */
   unregisterExporter(exporter: exportersTypes.Exporter): Tracing;
 }
+
+/** Main interface for tracing. */
+export interface Tracing extends TracingBase {
+  /** Object responsible for managing a trace. */
+  readonly tracer: modelTypes.Tracer;
+}