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,33 @@ export function getParentSpanContext(
 ): SpanContext | undefined {
   return getActiveSpan(context)?.context() || getExtractedSpanContext(context);
 }
+
+/**
+ * Sets value on context to indicate that instrumentation should
+ * be suppressed beyond this current scope.
+ *
+ * @param context context to set the suppress instrumentation value on.
+ */
+export function suppressInstrumentation(context: Context): Context {
+  return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, true);
+}
+
+/**
+ * Sets value on context to indicate that instrumentation should
+ * no-longer be suppressed beyond this current scope.
+ *
+ * @param context context to set the suppress instrumentation value on.
+ */
+export function unsuppressInstrumentation(context: Context): Context {
+  return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, false);
+}
+
+/**
+ * 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 {
+  return Boolean(context.getValue(SUPPRESS_INSTRUMENTATION_KEY));
+}

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

@@ -0,0 +1,91 @@
+/*
+ * 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,
+  unsuppressInstrumentation,
+  isInstrumentationSuppressed,
+} from '../../src/context/context';
+import { Context } from '@opentelemetry/api';
+
+describe('Context Helpers', () => {
+  describe('suppressInstrumentation', () => {
+    it('should set suppress to true', () => {
+      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);
+    });
+  });
+
+  describe('unsuppressInstrumentation', () => {
+    it('should set suppress to false', () => {
+      const expectedValue = false;
+      const context = unsuppressInstrumentation(Context.ROOT_CONTEXT);
+
+      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);
+    });
+
+    describe('when suppress instrumentation set to null', () => {
+      const context = Context.ROOT_CONTEXT.setValue(
+        SUPPRESS_INSTRUMENTATION_KEY,
+        null
+      );
+
+      it('should return false', () => {
+        const value = isInstrumentationSuppressed(context);
+
+        assert.equal(value, false);
+      });
+    });
+
+    describe('when suppress instrumentation set to undefined', () => {
+      const context = Context.ROOT_CONTEXT.setValue(
+        SUPPRESS_INSTRUMENTATION_KEY,
+        undefined
+      );
+
+      it('should return false', () => {
+        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

@@ -20,20 +20,25 @@ import { ExportResult } from '@opentelemetry/core';
 
 /**
  * This class can be used for testing purposes. It stores the exported spans
- * in a list in memory that can be retrieve using the `getFinishedSpans()`
+ * in a list in memory that can be retrieved using the `getFinishedSpans()`
  * method.
  */
 export class InMemorySpanExporter implements SpanExporter {
   private _finishedSpans: ReadableSpan[] = [];
-  private _stopped = false;
+  /**
+   * Indicates if the exporter has been "shutdown."
+   * When false, exported spans will not be stored in-memory.
+   */
+  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,25 @@ describe('Tracer', () => {
     assert.strictEqual(lib.version, '0.0.1');
   });
 
+  describe('when suppressInstrumentation true', () => {
+    const context = suppressInstrumentation(Context.ROOT_CONTEXT);
+
+    it('should return cached no-op span ', done => {
+      const tracer = new Tracer(
+        { name: 'default', version: '0.0.1' },
+        { sampler: new TestSampler() },
+        tracerProvider
+      );
+
+      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({
@@ -226,5 +229,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();
+        });
+      });
+    });
   });
 });