feat(tracer): expose bind method from scope manager (open-telemetry#201)

packages/opentelemetry-basic-tracer/src/BasicTracer.ts

@@ -103,10 +103,17 @@ export class BasicTracer implements types.Tracer {
 
   /**
    * Returns the current Span from the current context.
+   *
+   * If there is no Span associated with the current context, null is returned.
    */
-  getCurrentSpan(): types.Span {
-    // Get the current Span from the context.
-    return this._scopeManager.active() as types.Span;
+  getCurrentSpan(): types.Span | null {
+    // Get the current Span from the context or null if none found.
+    const current = this._scopeManager.active();
+    if (current === null || current === undefined) {
+      return null;
+    } else {
+      return current as types.Span;
+    }
   }
 
   /**
@@ -120,6 +127,13 @@ export class BasicTracer implements types.Tracer {
     return this._scopeManager.with(span, fn);
   }
 
+  /**
+   * Bind a span (or the current one) to the target's scope
+   */
+  bind<T>(target: T, span?: types.Span): T {
+    return this._scopeManager.bind(target, span);
+  }
+
   /**
    * Records a SpanData.
    */

packages/opentelemetry-basic-tracer/test/BasicTracer.test.ts

@@ -240,11 +240,27 @@ describe('BasicTracer', () => {
       });
       const span = tracer.startSpan('my-span');
       tracer.withSpan(span, () => {
+        assert.deepStrictEqual(tracer.getCurrentSpan(), null);
         return done();
       });
     });
   });
 
+  describe('.bind()', () => {
+    it('should bind scope with NoopScopeManager scope manager', done => {
+      const tracer = new BasicTracer({
+        scopeManager: new NoopScopeManager(),
+      });
+      const span = tracer.startSpan('my-span');
+      const fn = () => {
+        assert.deepStrictEqual(tracer.getCurrentSpan(), null);
+        return done();
+      };
+      const patchedFn = tracer.bind(fn, span);
+      return patchedFn();
+    });
+  });
+
   describe('.recordSpanData()', () => {
     // @todo: implement
     it('should call exporters with span data');

packages/opentelemetry-core/src/trace/NoopTracer.ts

@@ -45,6 +45,10 @@ export class NoopTracer implements Tracer {
     return fn();
   }
 
+  bind<T>(target: T, span?: Span): T {
+    return target;
+  }
+
   // By default does nothing
   recordSpanData(span: Span): void {}
 

packages/opentelemetry-core/src/trace/TracerDelegate.ts

@@ -47,14 +47,22 @@ export class TracerDelegate implements types.Tracer {
 
   // -- Tracer interface implementation below -- //
 
-  getCurrentSpan(): types.Span {
+  getCurrentSpan(): types.Span | null {
     return this._currentTracer.getCurrentSpan.apply(
       this._currentTracer,
       // tslint:disable-next-line:no-any
       arguments as any
     );
   }
 
+  bind<T>(target: T, span?: types.Span): T {
+    return (this._currentTracer.bind.apply(
+      this._currentTracer,
+      // tslint:disable-next-line:no-any
+      arguments as any
+    ) as unknown) as T;
+  }
+
   startSpan(name: string, options?: types.SpanOptions): types.Span {
     return this._currentTracer.startSpan.apply(
       this._currentTracer,

packages/opentelemetry-core/test/trace/NoopTracer.test.ts

@@ -57,4 +57,13 @@ describe('NoopTracer', () => {
       return done();
     });
   });
+
+  it('should not crash when .bind()', done => {
+    const tracer = new NoopTracer();
+    const fn = () => {
+      return done();
+    };
+    const patchedFn = tracer.bind(fn, NOOP_SPAN);
+    return patchedFn();
+  });
 });

packages/opentelemetry-core/test/trace/TracerDelegate.test.ts

@@ -25,6 +25,7 @@ describe('TracerDelegate', () => {
     'getCurrentSpan',
     'startSpan',
     'withSpan',
+    'bind',
     'recordSpanData',
     'getBinaryFormat',
     'getHttpTextFormat',

packages/opentelemetry-node-tracer/test/NodeTracer.test.ts

@@ -158,6 +158,21 @@ describe('NodeTracer', () => {
     });
   });
 
+  describe('.bind()', () => {
+    it('should bind scope with AsyncHooksScopeManager scope manager', done => {
+      const tracer = new NodeTracer({
+        scopeManager: new AsyncHooksScopeManager(),
+      });
+      const span = tracer.startSpan('my-span');
+      const fn = () => {
+        assert.deepStrictEqual(tracer.getCurrentSpan(), span);
+        return done();
+      };
+      const patchedFn = tracer.bind(fn, span);
+      return patchedFn();
+    });
+  });
+
   describe('.recordSpanData()', () => {
     // @todo: implement
     it('should call exporters with span data');

packages/opentelemetry-types/src/trace/tracer.ts

@@ -30,12 +30,11 @@ export interface Tracer {
   /**
    * Returns the current Span from the current context if available.
    *
-   * If there is no Span associated with the current context, a default Span
-   * with invalid SpanContext is returned.
+   * If there is no Span associated with the current context, null is returned.
    *
    * @returns Span The currently active Span
    */
-  getCurrentSpan(): Span;
+  getCurrentSpan(): Span | null;
 
   /**
    * Starts a new {@link Span}.
@@ -58,6 +57,14 @@ export interface Tracer {
     fn: T
   ): ReturnType<T>;
 
+  /**
+   * Bind a span as the target's scope or propagate the current one.
+   *
+   * @param target Any object to which a scope need to be set
+   * @param [span] Optionally specify the span which you want to assign
+   */
+  bind<T>(target: T, span?: Span): T;
+
   /**
    * Send a pre-populated span object to the exporter.
    * Sampling and recording decisions as well as other collection optimizations