feat(node): Allow to configure skipOpenTelemetrySetup (#10907)

Also warn if there is an incomplete setup, to ensure users notice if
stuff is breaking.

I do this by just keeping a set of things that were created, which is
not perfect but IMHO good enough to notify users if they forgot to setup
a specific thing...

Author: mydea

packages/node-experimental/src/sdk/init.ts

@@ -11,7 +11,7 @@ import {
   requestDataIntegration,
   startSession,
 } from '@sentry/core';
-import { setOpenTelemetryContextAsyncContextStrategy } from '@sentry/opentelemetry';
+import { openTelemetrySetupCheck, setOpenTelemetryContextAsyncContextStrategy } from '@sentry/opentelemetry';
 import type { Client, Integration, Options } from '@sentry/types';
 import {
   consoleSandbox,
@@ -117,8 +117,36 @@ export function init(options: NodeOptions | undefined = {}): void {
     );
   }
 
-  // Always init Otel, even if tracing is disabled, because we need it for trace propagation & the HTTP integration
-  initOtel();
+  // If users opt-out of this, they _have_ to set up OpenTelemetry themselves
+  // There is no way to use this SDK without OpenTelemetry!
+  if (!options.skipOpenTelemetrySetup) {
+    initOtel();
+  }
+
+  validateOpenTelemetrySetup();
+}
+
+function validateOpenTelemetrySetup(): void {
+  if (!DEBUG_BUILD) {
+    return;
+  }
+
+  const setup = openTelemetrySetupCheck();
+
+  const required = ['SentrySpanProcessor', 'SentryContextManager', 'SentryPropagator'] as const;
+  for (const k of required) {
+    if (!setup.includes(k)) {
+      logger.error(
+        `You have to set up the ${k}. Without this, the OpenTelemetry & Sentry integration will not work properly.`,
+      );
+    }
+  }
+
+  if (!setup.includes('SentrySampler')) {
+    logger.warn(
+      'You have to set up the SentrySampler. Without this, the OpenTelemetry & Sentry integration may still work, but sample rates set for the Sentry SDK will not be respected.',
+    );
+  }
 }
 
 function getClientOptions(options: NodeOptions): NodeClientOptions {

packages/node-experimental/src/types.ts

@@ -64,6 +64,16 @@ export interface BaseNodeOptions {
    */
   spotlight?: boolean | string;
 
+  /**
+   * If this is set to true, the SDK will not set up OpenTelemetry automatically.
+   * In this case, you _have_ to ensure to set it up correctly yourself, including:
+   * * The `SentrySpanProcessor`
+   * * The `SentryPropagator`
+   * * The `SentryContextManager`
+   * * The `SentrySampler`
+   */
+  skipOpenTelemetrySetup?: boolean;
+
   /** Callback that is executed when a fatal global error occurs. */
   onFatalError?(this: void, error: Error): void;
 }

packages/node-experimental/test/sdk/init.test.ts

@@ -2,6 +2,7 @@ import type { Integration } from '@sentry/types';
 
 import * as auto from '../../src/integrations/tracing';
 import { getClient } from '../../src/sdk/api';
+import type { NodeClient } from '../../src/sdk/client';
 import { init } from '../../src/sdk/init';
 import { cleanupOtel } from '../helpers/mockSdkInit';
 
@@ -119,4 +120,20 @@ describe('init()', () => {
       }),
     );
   });
+
+  it('sets up OpenTelemetry by default', () => {
+    init({ dsn: PUBLIC_DSN });
+
+    const client = getClient<NodeClient>();
+
+    expect(client.traceProvider).toBeDefined();
+  });
+
+  it('allows to opt-out of OpenTelemetry setup', () => {
+    init({ dsn: PUBLIC_DSN, skipOpenTelemetrySetup: true });
+
+    const client = getClient<NodeClient>();
+
+    expect(client.traceProvider).not.toBeDefined();
+  });
 });

packages/opentelemetry/src/contextManager.ts

@@ -9,6 +9,7 @@ import {
 } from './constants';
 import { getCurrentHub } from './custom/getCurrentHub';
 import { getScopesFromContext, setContextOnScope, setHubOnContext, setScopesOnContext } from './utils/contextData';
+import { setIsSetup } from './utils/setupCheck';
 
 /**
  * Wrap an OpenTelemetry ContextManager in a way that ensures the context is kept in sync with the Sentry Hub.
@@ -31,6 +32,10 @@ export function wrapContextManagerClass<ContextManagerInstance extends ContextMa
 
   // @ts-expect-error TS does not like this, but we know this is fine
   class SentryContextManager extends ContextManagerClass {
+    public constructor() {
+      super();
+      setIsSetup('SentryContextManager');
+    }
     /**
      * Overwrite with() of the original AsyncLocalStorageContextManager
      * to ensure we also create a new hub per context.

packages/opentelemetry/src/index.ts

@@ -43,6 +43,8 @@ export { SentryPropagator } from './propagator';
 export { SentrySpanProcessor } from './spanProcessor';
 export { SentrySampler } from './sampler';
 
+export { openTelemetrySetupCheck } from './utils/setupCheck';
+
 // Legacy
 export { getClient } from '@sentry/core';
 

packages/opentelemetry/src/propagator.ts

@@ -18,6 +18,7 @@ import {
   SENTRY_TRACE_STATE_PARENT_SPAN_ID,
 } from './constants';
 import { getScopesFromContext, setScopesOnContext } from './utils/contextData';
+import { setIsSetup } from './utils/setupCheck';
 
 /** Get the Sentry propagation context from a span context. */
 export function getPropagationContextFromSpanContext(spanContext: SpanContext): PropagationContext {
@@ -41,6 +42,11 @@ export function getPropagationContextFromSpanContext(spanContext: SpanContext):
  * Injects and extracts `sentry-trace` and `baggage` headers from carriers.
  */
 export class SentryPropagator extends W3CBaggagePropagator {
+  public constructor() {
+    super();
+    setIsSetup('SentryPropagator');
+  }
+
   /**
    * @inheritDoc
    */

packages/opentelemetry/src/sampler.ts

@@ -10,6 +10,7 @@ import { isNaN, logger } from '@sentry/utils';
 import { DEBUG_BUILD } from './debug-build';
 import { getPropagationContextFromSpanContext } from './propagator';
 import { InternalSentrySemanticAttributes } from './semanticAttributes';
+import { setIsSetup } from './utils/setupCheck';
 
 /**
  * A custom OTEL sampler that uses Sentry sampling rates to make it's decision
@@ -19,6 +20,7 @@ export class SentrySampler implements Sampler {
 
   public constructor(client: Client) {
     this._client = client;
+    setIsSetup('SentrySampler');
   }
 
   /** @inheritDoc */

packages/opentelemetry/src/spanProcessor.ts

@@ -9,6 +9,7 @@ import { DEBUG_BUILD } from './debug-build';
 import { SentrySpanExporter } from './spanExporter';
 import { maybeCaptureExceptionForTimedEvent } from './utils/captureExceptionForTimedEvent';
 import { getHubFromContext } from './utils/contextData';
+import { setIsSetup } from './utils/setupCheck';
 import { getSpanHub, setSpanHub, setSpanParent, setSpanScopes } from './utils/spanData';
 
 function onSpanStart(span: Span, parentContext: Context): void {
@@ -56,6 +57,8 @@ function onSpanEnd(span: Span): void {
 export class SentrySpanProcessor extends BatchSpanProcessor implements SpanProcessorInterface {
   public constructor() {
     super(new SentrySpanExporter());
+
+    setIsSetup('SentrySpanProcessor');
   }
 
   /**

packages/opentelemetry/src/utils/setupCheck.ts

@@ -0,0 +1,18 @@
+type OpenTelemetryElement = 'SentrySpanProcessor' | 'SentryContextManager' | 'SentryPropagator' | 'SentrySampler';
+
+const setupElements = new Set<OpenTelemetryElement>();
+
+/** Get all the OpenTelemetry elements that have been set up. */
+export function openTelemetrySetupCheck(): OpenTelemetryElement[] {
+  return Array.from(setupElements);
+}
+
+/** Mark an OpenTelemetry element as setup. */
+export function setIsSetup(element: OpenTelemetryElement): void {
+  setupElements.add(element);
+}
+
+/** Only exported for tests. */
+export function clearOpenTelemetrySetupCheck(): void {
+  setupElements.clear();
+}

packages/opentelemetry/test/helpers/mockSdkInit.ts

@@ -4,6 +4,7 @@ import type { ClientOptions, Options } from '@sentry/types';
 
 import { getCurrentScope, getGlobalScope, getIsolationScope } from '@sentry/core';
 import { setOpenTelemetryContextAsyncContextStrategy } from '../../src/asyncContextStrategy';
+import { clearOpenTelemetrySetupCheck } from '../../src/utils/setupCheck';
 import { init as initTestClient } from './TestClient';
 import { initOtel } from './initOtel';
 
@@ -32,6 +33,7 @@ export function mockSdkInit(options?: Partial<ClientOptions>) {
 }
 
 export function cleanupOtel(_provider?: BasicTracerProvider): void {
+  clearOpenTelemetrySetupCheck();
   const provider = getProvider(_provider);
 
   if (!provider) {