feat: introduces ability to suppress tracing via context

packages/opentelemetry-core/src/context/context.ts

@@ -26,6 +26,13 @@ export const ACTIVE_SPAN_KEY = Context.createKey(
 const EXTRACTED_SPAN_CONTEXT_KEY = Context.createKey(
   'OpenTelemetry Context Key EXTRACTED_SPAN_CONTEXT'
 );
+/**
+ * Shared key for indicating if instrumentation should be suppressed beyond
+ * this current scope.
+ */
+export const SUPPRESS_INSTRUMENTATION_KEY = Context.createKey(
+  'OpenTelemetry Context Key SUPPRESS_INSTRUMENTATION'
+);
 
 /**
  * Return the active span if one exists
@@ -84,3 +91,28 @@ export function getParentSpanContext(
 ): SpanContext | undefined {
   return getActiveSpan(context)?.context() || getExtractedSpanContext(context);
 }
+
+/**
+ * Set whether or not instrumentation should be suppressed beyond
+ * this current scope.
+ *
+ * @param context context to set the suppress instrumentation value on.
+ * @param shouldSuppress value to set.
+ */
+export function suppressInstrumentation(
+  context: Context,
+  suppress = true
+): Context {
+  return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, suppress);
+}
+
+/**
+ * Return current suppress instrumentation value for the given context,
+ * if it exists.
+ *
+ * @param context context check for the suppress instrumentation value.
+ */
+export function isInstrumentationSuppressed(context: Context): boolean {
+  const value = context.getValue(SUPPRESS_INSTRUMENTATION_KEY) as boolean;
+  return !!value;
+}

packages/opentelemetry-core/test/context/context.test.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as assert from 'assert';
+
+import {
+  SUPPRESS_INSTRUMENTATION_KEY,
+  suppressInstrumentation,
+  isInstrumentationSuppressed,
+} from '../../src/context/context';
+import { Context } from '@opentelemetry/api';
+
+describe('Context Helpers', () => {
+  describe('suppressInstrumentation', () => {
+    it('should set suppress to true by default', () => {
+      const expectedValue = true;
+      const context = suppressInstrumentation(Context.ROOT_CONTEXT);
+
+      const value = context.getValue(SUPPRESS_INSTRUMENTATION_KEY);
+      const boolValue = value as boolean;
+
+      assert.equal(boolValue, expectedValue);
+    });
+
+    it('should set suppress instrumentation value', () => {
+      const expectedValue = false;
+      const context = suppressInstrumentation(
+        Context.ROOT_CONTEXT,
+        expectedValue
+      );
+
+      const value = context.getValue(SUPPRESS_INSTRUMENTATION_KEY);
+      const boolValue = value as boolean;
+
+      assert.equal(boolValue, expectedValue);
+    });
+  });
+
+  describe('isInstrumentationSuppressed', () => {
+    it('should get value as bool', () => {
+      const expectedValue = true;
+      const context = Context.ROOT_CONTEXT.setValue(
+        SUPPRESS_INSTRUMENTATION_KEY,
+        expectedValue
+      );
+
+      const value = isInstrumentationSuppressed(context);
+
+      assert.equal(value, expectedValue);
+    });
+
+    it('should return false if set to null', () => {
+      const context = Context.ROOT_CONTEXT.setValue(
+        SUPPRESS_INSTRUMENTATION_KEY,
+        null
+      );
+
+      const value = isInstrumentationSuppressed(context);
+
+      assert.equal(value, false);
+    });
+
+    it('should return false if set to undefined', () => {
+      const context = Context.ROOT_CONTEXT.setValue(
+        SUPPRESS_INSTRUMENTATION_KEY,
+        undefined
+      );
+
+      const value = isInstrumentationSuppressed(context);
+
+      assert.equal(value, false);
+    });
+  });
+});

packages/opentelemetry-tracing/src/Tracer.ts

@@ -25,6 +25,7 @@ import {
   IdGenerator,
   RandomIdGenerator,
   setActiveSpan,
+  isInstrumentationSuppressed,
 } from '@opentelemetry/core';
 import { Resource } from '@opentelemetry/resources';
 import { BasicTracerProvider } from './BasicTracerProvider';
@@ -69,6 +70,11 @@ export class Tracer implements api.Tracer {
     options: api.SpanOptions = {},
     context = api.context.active()
   ): api.Span {
+    if (isInstrumentationSuppressed(context)) {
+      this.logger.debug('Instrumentation suppressed, returning NoOp Span');
+      return api.NOOP_SPAN;
+    }
+
     const parentContext = getParent(options, context);
     const spanId = this._idGenerator.generateSpanId();
     let traceId;
@@ -81,6 +87,7 @@ export class Tracer implements api.Tracer {
       traceId = parentContext.traceId;
       traceState = parentContext.traceState;
     }
+
     const spanKind = options.kind ?? api.SpanKind.INTERNAL;
     const links = options.links ?? [];
     const attributes = options.attributes ?? {};

packages/opentelemetry-tracing/src/export/BatchSpanProcessor.ts

@@ -14,7 +14,8 @@
  * limitations under the License.
  */
 
-import { unrefTimer } from '@opentelemetry/core';
+import { context } from '@opentelemetry/api';
+import { unrefTimer, suppressInstrumentation } from '@opentelemetry/core';
 import { SpanProcessor } from '../SpanProcessor';
 import { BufferConfig } from '../types';
 import { ReadableSpan } from './ReadableSpan';
@@ -88,7 +89,12 @@ export class BatchSpanProcessor implements SpanProcessor {
       setTimeout(cb, 0);
       return;
     }
-    this._exporter.export(this._finishedSpans, cb);
+
+    // prevent downstream exporter calls from generating spans
+    context.with(suppressInstrumentation(context.active()), () => {
+      this._exporter.export(this._finishedSpans, cb);
+    });
+
     this._finishedSpans = [];
   }
 

packages/opentelemetry-tracing/src/export/InMemorySpanExporter.ts

@@ -25,15 +25,16 @@ import { ExportResult } from '@opentelemetry/core';
  */
 export class InMemorySpanExporter implements SpanExporter {
   private _finishedSpans: ReadableSpan[] = [];
-  private _stopped = false;
+  protected _stopped = false;
 
   export(
     spans: ReadableSpan[],
     resultCallback: (result: ExportResult) => void
   ): void {
     if (this._stopped) return resultCallback(ExportResult.FAILED_NOT_RETRYABLE);
     this._finishedSpans.push(...spans);
-    return resultCallback(ExportResult.SUCCESS);
+
+    setTimeout(() => resultCallback(ExportResult.SUCCESS), 0);
   }
 
   shutdown(): void {

packages/opentelemetry-tracing/src/export/SimpleSpanProcessor.ts

@@ -17,6 +17,8 @@
 import { SpanProcessor } from '../SpanProcessor';
 import { SpanExporter } from './SpanExporter';
 import { ReadableSpan } from './ReadableSpan';
+import { context } from '@opentelemetry/api';
+import { suppressInstrumentation } from '@opentelemetry/core';
 
 /**
  * An implementation of the {@link SpanProcessor} that converts the {@link Span}
@@ -40,7 +42,11 @@ export class SimpleSpanProcessor implements SpanProcessor {
     if (this._isShutdown) {
       return;
     }
-    this._exporter.export([span], () => {});
+
+    // prevent downstream exporter calls from generating spans
+    context.with(suppressInstrumentation(context.active()), () => {
+      this._exporter.export([span], () => {});
+    });
   }
 
   shutdown(cb: () => void = () => {}): void {

packages/opentelemetry-tracing/test/Tracer.test.ts

@@ -19,6 +19,8 @@ import {
   NoopSpan,
   Sampler,
   SamplingDecision,
+  Context,
+  NOOP_SPAN,
   TraceFlags,
 } from '@opentelemetry/api';
 import { BasicTracerProvider, Tracer, Span } from '../src';
@@ -27,6 +29,7 @@ import {
   NoopLogger,
   AlwaysOnSampler,
   AlwaysOffSampler,
+  suppressInstrumentation,
 } from '@opentelemetry/core';
 
 describe('Tracer', () => {
@@ -115,6 +118,22 @@ describe('Tracer', () => {
     assert.strictEqual(lib.version, '0.0.1');
   });
 
+  it('should return cached no-op span when suppressInstrumentation true', done => {
+    const tracer = new Tracer(
+      { name: 'default', version: '0.0.1' },
+      { sampler: new TestSampler() },
+      tracerProvider
+    );
+
+    const context = suppressInstrumentation(Context.ROOT_CONTEXT);
+    const span = tracer.startSpan('span3', undefined, context);
+
+    assert.equal(span, NOOP_SPAN);
+    span.end();
+
+    done();
+  });
+
   if (typeof process !== 'undefined' && process.release.name === 'node') {
     it('should sample a trace when OTEL_SAMPLING_PROBABILITY is invalid', () => {
       process.env.OTEL_SAMPLING_PROBABILITY = 'invalid value';

packages/opentelemetry-tracing/test/export/BatchSpanProcessor.test.ts

@@ -23,6 +23,9 @@ import {
   InMemorySpanExporter,
   Span,
 } from '../../src';
+import { context } from '@opentelemetry/api';
+import { TestTracingSpanExporter } from './TestTracingSpanExporter';
+import { TestStackContextManager } from './TestStackContextManager';
 
 function createSampledSpan(spanName: string): Span {
   const tracer = new BasicTracerProvider({
@@ -227,5 +230,32 @@ describe('BatchSpanProcessor', () => {
         });
       });
     });
+
+    describe('flushing spans with exporter triggering instrumentation', () => {
+      beforeEach(() => {
+        const contextManager = new TestStackContextManager().enable();
+        context.setGlobalContextManager(contextManager);
+      });
+
+      afterEach(() => {
+        context.disable();
+      });
+
+      it('should prevent instrumentation prior to export', done => {
+        const testTracingExporter = new TestTracingSpanExporter();
+        const processor = new BatchSpanProcessor(testTracingExporter);
+
+        const span = createSampledSpan('test');
+        processor.onStart(span);
+        processor.onEnd(span);
+
+        processor.forceFlush(() => {
+          const exporterCreatedSpans = testTracingExporter.getExporterCreatedSpans();
+          assert.equal(exporterCreatedSpans.length, 0);
+
+          done();
+        });
+      });
+    });
   });
 });

packages/opentelemetry-tracing/test/export/SimpleSpanProcessor.test.ts

@@ -21,7 +21,9 @@ import {
   InMemorySpanExporter,
   SimpleSpanProcessor,
 } from '../../src';
-import { SpanContext, SpanKind, TraceFlags } from '@opentelemetry/api';
+import { SpanContext, SpanKind, TraceFlags, context } from '@opentelemetry/api';
+import { TestTracingSpanExporter } from './TestTracingSpanExporter';
+import { TestStackContextManager } from './TestStackContextManager';
 
 describe('SimpleSpanProcessor', () => {
   const provider = new BasicTracerProvider();
@@ -80,21 +82,54 @@ describe('SimpleSpanProcessor', () => {
       processor.shutdown();
       assert.strictEqual(exporter.getFinishedSpans().length, 0);
     });
+  });
 
-    describe('force flush', () => {
-      it('should call an async callback when flushing is complete', done => {
-        const processor = new SimpleSpanProcessor(exporter);
-        processor.forceFlush(() => {
-          done();
-        });
+  describe('force flush', () => {
+    it('should call an async callback when flushing is complete', done => {
+      const processor = new SimpleSpanProcessor(exporter);
+      processor.forceFlush(() => {
+        done();
       });
+    });
 
-      it('should call an async callback when shutdown is complete', done => {
-        const processor = new SimpleSpanProcessor(exporter);
-        processor.shutdown(() => {
-          done();
-        });
+    it('should call an async callback when shutdown is complete', done => {
+      const processor = new SimpleSpanProcessor(exporter);
+      processor.shutdown(() => {
+        done();
       });
     });
   });
+
+  describe('onEnd', () => {
+    beforeEach(() => {
+      const contextManager = new TestStackContextManager().enable();
+      context.setGlobalContextManager(contextManager);
+    });
+
+    afterEach(() => {
+      context.disable();
+    });
+
+    it('should prevent instrumentation prior to export', () => {
+      const testTracingExporter = new TestTracingSpanExporter();
+      const processor = new SimpleSpanProcessor(testTracingExporter);
+
+      const spanContext: SpanContext = {
+        traceId: 'a3cda95b652f4a1592b449d5929fda1b',
+        spanId: '5e0c63257de34c92',
+        traceFlags: TraceFlags.SAMPLED,
+      };
+      const span = new Span(
+        provider.getTracer('default'),
+        'span-name',
+        spanContext,
+        SpanKind.CLIENT
+      );
+
+      processor.onEnd(span);
+
+      const exporterCreatedSpans = testTracingExporter.getExporterCreatedSpans();
+      assert.equal(exporterCreatedSpans.length, 0);
+    });
+  });
 });