feat(core): Rename hasTracingEnabled to hasSpansEnabled (#15309)

Lms24 · web-flow · commit 447911af2b6b · 2025-02-05T16:35:16.000+01:00
Rename the `hasTracingEnabled` utility function to
`hasSpansEnabled`. The original name is causing confusion and doesn't
represent what the function actually does: determining if the SDK is
configured to record spans. This function does not check if trace
propagation without span recording (or "Tracing without Performance") is
enabled (which it basically always is).
diff --git a/packages/browser/src/tracing/request.ts b/packages/browser/src/tracing/request.ts
@@ -15,7 +15,7 @@ import {
   getActiveSpan,
   getLocationHref,
   getTraceData,
-  hasTracingEnabled,
+  hasSpansEnabled,
   instrumentFetchRequest,
   parseUrl,
   setHttpStatus,
@@ -322,7 +322,7 @@ export function xhrCallback(
     return undefined;
   }
 
-  const shouldCreateSpanResult = hasTracingEnabled() && shouldCreateSpan(sentryXhrData.url);
+  const shouldCreateSpanResult = hasSpansEnabled() && shouldCreateSpan(sentryXhrData.url);
 
   // check first if the request has finished and is tracked by an existing span which should now end
   if (handlerData.endTimestamp && shouldCreateSpanResult) {
@@ -370,7 +370,7 @@ export function xhrCallback(
       // If performance is disabled (TWP) or there's no active root span (pageload/navigation/interaction),
       // we do not want to use the span as base for the trace headers,
       // which means that the headers will be generated from the scope and the sampling decision is deferred
-      hasTracingEnabled() && hasParent ? span : undefined,
+      hasSpansEnabled() && hasParent ? span : undefined,
     );
   }
 
diff --git a/packages/core/src/fetch.ts b/packages/core/src/fetch.ts
@@ -5,7 +5,7 @@ import type { HandlerDataFetch, Span, SpanOrigin } from './types-hoist';
 import { SENTRY_BAGGAGE_KEY_PREFIX } from './utils-hoist/baggage';
 import { isInstanceOf } from './utils-hoist/is';
 import { parseUrl } from './utils-hoist/url';
-import { hasTracingEnabled } from './utils/hasTracingEnabled';
+import { hasSpansEnabled } from './utils/hasSpansEnabled';
 import { getActiveSpan } from './utils/spanUtils';
 import { getTraceData } from './utils/traceData';
 
@@ -34,7 +34,7 @@ export function instrumentFetchRequest(
     return undefined;
   }
 
-  const shouldCreateSpanResult = hasTracingEnabled() && shouldCreateSpan(handlerData.fetchData.url);
+  const shouldCreateSpanResult = hasSpansEnabled() && shouldCreateSpan(handlerData.fetchData.url);
 
   if (handlerData.endTimestamp && shouldCreateSpanResult) {
     const spanId = handlerData.fetchData.__span;
@@ -87,7 +87,7 @@ export function instrumentFetchRequest(
       // If performance is disabled (TWP) or there's no active root span (pageload/navigation/interaction),
       // we do not want to use the span as base for the trace headers,
       // which means that the headers will be generated from the scope and the sampling decision is deferred
-      hasTracingEnabled() && hasParent ? span : undefined,
+      hasSpansEnabled() && hasParent ? span : undefined,
     );
     if (headers) {
       // Ensure this is actually set, if no options have been passed previously
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -68,7 +68,9 @@ export {
 export { applyScopeDataToEvent, mergeScopeData } from './utils/applyScopeDataToEvent';
 export { prepareEvent } from './utils/prepareEvent';
 export { createCheckInEnvelope } from './checkin';
-export { hasTracingEnabled } from './utils/hasTracingEnabled';
+// eslint-disable-next-line deprecation/deprecation
+export { hasTracingEnabled } from './utils/hasSpansEnabled';
+export { hasSpansEnabled } from './utils/hasSpansEnabled';
 export { isSentryRequestUrl } from './utils/isSentryRequestUrl';
 export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
diff --git a/packages/core/src/tracing/dynamicSamplingContext.ts b/packages/core/src/tracing/dynamicSamplingContext.ts
@@ -9,7 +9,7 @@ import {
   dynamicSamplingContextToSentryBaggageHeader,
 } from '../utils-hoist/baggage';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
-import { hasTracingEnabled } from '../utils/hasTracingEnabled';
+import { hasSpansEnabled } from '../utils/hasSpansEnabled';
 import { getRootSpan, spanIsSampled, spanToJSON } from '../utils/spanUtils';
 import { getCapturedScopesOnSpan } from './utils';
 
@@ -118,10 +118,10 @@ export function getDynamicSamplingContextFromSpan(span: Span): Readonly<Partial<
     dsc.transaction = name;
   }
 
-  // How can we even land here with hasTracingEnabled() returning false?
+  // How can we even land here with hasSpansEnabled() returning false?
   // Otel creates a Non-recording span in Tracing Without Performance mode when handling incoming requests
   // So we end up with an active span that is not sampled (neither positively nor negatively)
-  if (hasTracingEnabled()) {
+  if (hasSpansEnabled()) {
     dsc.sampled = String(spanIsSampled(rootSpan));
     dsc.sample_rand =
       // In OTEL we store the sample rand on the trace state because we cannot access scopes for NonRecordingSpans
diff --git a/packages/core/src/tracing/idleSpan.ts b/packages/core/src/tracing/idleSpan.ts
@@ -5,7 +5,7 @@ import { DEBUG_BUILD } from '../debug-build';
 import { SEMANTIC_ATTRIBUTE_SENTRY_IDLE_SPAN_FINISH_REASON } from '../semanticAttributes';
 import { logger } from '../utils-hoist/logger';
 import { timestampInSeconds } from '../utils-hoist/time';
-import { hasTracingEnabled } from '../utils/hasTracingEnabled';
+import { hasSpansEnabled } from '../utils/hasSpansEnabled';
 import { _setSpanForScope } from '../utils/spanOnScope';
 import {
   getActiveSpan,
@@ -109,7 +109,7 @@ export function startIdleSpan(startSpanOptions: StartSpanOptions, options: Parti
 
   const client = getClient();
 
-  if (!client || !hasTracingEnabled()) {
+  if (!client || !hasSpansEnabled()) {
     const span = new SentryNonRecordingSpan();
 
     const dsc = {
diff --git a/packages/core/src/tracing/sampling.ts b/packages/core/src/tracing/sampling.ts
@@ -2,7 +2,7 @@ import type { Options, SamplingContext } from '../types-hoist';
 
 import { DEBUG_BUILD } from '../debug-build';
 import { logger } from '../utils-hoist/logger';
-import { hasTracingEnabled } from '../utils/hasTracingEnabled';
+import { hasSpansEnabled } from '../utils/hasSpansEnabled';
 import { parseSampleRate } from '../utils/parseSampleRate';
 
 /**
@@ -16,8 +16,8 @@ export function sampleSpan(
   samplingContext: SamplingContext,
   sampleRand: number,
 ): [sampled: boolean, sampleRate?: number, localSampleRateWasApplied?: boolean] {
-  // nothing to do if tracing is not enabled
-  if (!hasTracingEnabled(options)) {
+  // nothing to do if span recording is not enabled
+  if (!hasSpansEnabled(options)) {
     return [false];
   }
 
diff --git a/packages/core/src/tracing/trace.ts b/packages/core/src/tracing/trace.ts
@@ -21,7 +21,7 @@ import { logger } from '../utils-hoist/logger';
 import { generateTraceId } from '../utils-hoist/propagationContext';
 import { propagationContextFromHeaders } from '../utils-hoist/tracing';
 import { handleCallbackErrors } from '../utils/handleCallbackErrors';
-import { hasTracingEnabled } from '../utils/hasTracingEnabled';
+import { hasSpansEnabled } from '../utils/hasSpansEnabled';
 import { parseSampleRate } from '../utils/parseSampleRate';
 import { _getSpanForScope, _setSpanForScope } from '../utils/spanOnScope';
 import { addChildSpanToSpan, getRootSpan, spanIsSampled, spanTimeInputToSeconds, spanToJSON } from '../utils/spanUtils';
@@ -302,7 +302,7 @@ function createChildOrRootSpan({
   forceTransaction?: boolean;
   scope: Scope;
 }): Span {
-  if (!hasTracingEnabled()) {
+  if (!hasSpansEnabled()) {
     const span = new SentryNonRecordingSpan();
 
     // If this is a root span, we ensure to freeze a DSC
diff --git a/packages/core/src/utils/hasSpansEnabled.ts b/packages/core/src/utils/hasSpansEnabled.ts
@@ -0,0 +1,44 @@
+import { getClient } from '../currentScopes';
+import type { Options } from '../types-hoist';
+
+// Treeshakable guard to remove all code related to tracing
+declare const __SENTRY_TRACING__: boolean | undefined;
+
+/**
+ * Determines if span recording is currently enabled.
+ *
+ * Spans are recorded when at least one of `tracesSampleRate` and `tracesSampler`
+ * is defined in the SDK config. This function does not make any assumption about
+ * sampling decisions, it only checks if the SDK is configured to record spans.
+ *
+ * Important: This function only determines if span recording is enabled. Trace
+ * continuation and propagation is separately controlled and not covered by this function.
+ * If this function returns `false`, traces can still be propagated (which is what
+ * we refer to by "Tracing without Performance")
+ * @see https://develop.sentry.dev/sdk/telemetry/traces/tracing-without-performance/
+ *
+ * @param maybeOptions An SDK options object to be passed to this function.
+ * If this option is not provided, the function will use the current client's options.
+ */
+export function hasSpansEnabled(
+  maybeOptions?: Pick<Options, 'tracesSampleRate' | 'tracesSampler'> | undefined,
+): boolean {
+  if (typeof __SENTRY_TRACING__ === 'boolean' && !__SENTRY_TRACING__) {
+    return false;
+  }
+
+  const options = maybeOptions || getClient()?.getOptions();
+  return (
+    !!options &&
+    // Note: This check is `!= null`, meaning "nullish". `0` is not "nullish", `undefined` and `null` are. (This comment was brought to you by 15 minutes of questioning life)
+    (options.tracesSampleRate != null || !!options.tracesSampler)
+  );
+}
+
+/**
+ * @see JSDoc of `hasSpansEnabled`
+ * @deprecated Use `hasSpansEnabled` instead, which is a more accurately named version of this function.
+ * This function will be removed in the next major version of the SDK.
+ */
+// TODO(v10): Remove this export
+export const hasTracingEnabled = hasSpansEnabled;
diff --git a/packages/core/src/utils/hasTracingEnabled.ts b/packages/core/src/utils/hasTracingEnabled.ts
diff --git a/packages/core/test/lib/utils/hasTracingEnabled.test.ts b/packages/core/test/lib/utils/hasTracingEnabled.test.ts
@@ -1,6 +1,7 @@
+import { hasSpansEnabled } from '../../../src';
 import { hasTracingEnabled } from '../../../src';
 
-describe('hasTracingEnabled', () => {
+describe('hasSpansEnabled', () => {
   const tracesSampler = () => 1;
   const tracesSampleRate = 1;
   it.each([
@@ -12,10 +13,9 @@ describe('hasTracingEnabled', () => {
     ['With tracesSampleRate=0', { tracesSampleRate: 0 }, true],
     ['With tracesSampler=undefined', { tracesSampler: undefined }, false],
     ['With tracesSampler and tracesSampleRate', { tracesSampler, tracesSampleRate }, true],
-  ])(
-    '%s',
-    (_: string, input: Parameters<typeof hasTracingEnabled>[0], output: ReturnType<typeof hasTracingEnabled>) => {
-      expect(hasTracingEnabled(input)).toBe(output);
-    },
-  );
+  ])('%s', (_: string, input: Parameters<typeof hasSpansEnabled>[0], output: ReturnType<typeof hasSpansEnabled>) => {
+    expect(hasSpansEnabled(input)).toBe(output);
+    // eslint-disable-next-line deprecation/deprecation
+    expect(hasTracingEnabled(input)).toBe(output);
+  });
 });
diff --git a/packages/nextjs/test/config/wrappers.test.ts b/packages/nextjs/test/config/wrappers.test.ts
@@ -15,7 +15,7 @@ describe('data-fetching function wrappers should not create manual spans', () =>
     req = { headers: {}, url: 'http://dogs.are.great/tricks/kangaroo' } as IncomingMessage;
     res = { end: jest.fn() } as unknown as ServerResponse;
 
-    jest.spyOn(SentryCore, 'hasTracingEnabled').mockReturnValue(true);
+    jest.spyOn(SentryCore, 'hasSpansEnabled').mockReturnValue(true);
     jest.spyOn(SentryCore, 'getClient').mockImplementation(() => {
       return {
         getOptions: () => ({}),
diff --git a/packages/node/src/integrations/node-fetch.ts b/packages/node/src/integrations/node-fetch.ts
@@ -11,7 +11,7 @@ import {
   getClient,
   getSanitizedUrlString,
   getTraceData,
-  hasTracingEnabled,
+  hasSpansEnabled,
   parseUrl,
 } from '@sentry/core';
 import { shouldPropagateTraceForUrl } from '@sentry/opentelemetry';
@@ -49,9 +49,9 @@ const _nativeNodeFetchIntegration = ((options: NodeFetchOptions = {}) => {
             return true;
           }
 
-          // If tracing is disabled, we still want to propagate traces
+          // If span recording is disabled, we still want to propagate traces
           // So we do that manually here, matching what the instrumentation does otherwise
-          if (!hasTracingEnabled()) {
+          if (!hasSpansEnabled()) {
             const tracePropagationTargets = getClient()?.getOptions().tracePropagationTargets;
             const addedHeaders = shouldPropagateTraceForUrl(url, tracePropagationTargets, propagationDecisionMap)
               ? getTraceData()
diff --git a/packages/node/src/sdk/index.ts b/packages/node/src/sdk/index.ts
@@ -5,7 +5,7 @@ import {
   functionToStringIntegration,
   getCurrentScope,
   getIntegrationsToSetup,
-  hasTracingEnabled,
+  hasSpansEnabled,
   inboundFiltersIntegration,
   linkedErrorsIntegration,
   logger,
@@ -80,7 +80,7 @@ export function getDefaultIntegrations(options: Options): Integration[] {
     // Note that this means that without tracing enabled, e.g. `expressIntegration()` will not be added
     // This means that generally request isolation will work (because that is done by httpIntegration)
     // But `transactionName` will not be set automatically
-    ...(hasTracingEnabled(options) ? getAutoPerformanceIntegrations() : []),
+    ...(hasSpansEnabled(options) ? getAutoPerformanceIntegrations() : []),
   ];
 }
 
@@ -175,7 +175,7 @@ export function validateOpenTelemetrySetup(): void {
 
   const required: ReturnType<typeof openTelemetrySetupCheck> = ['SentryContextManager', 'SentryPropagator'];
 
-  if (hasTracingEnabled()) {
+  if (hasSpansEnabled()) {
     required.push('SentrySpanProcessor');
   }
 
diff --git a/packages/node/src/utils/ensureIsWrapped.ts b/packages/node/src/utils/ensureIsWrapped.ts
@@ -1,5 +1,5 @@
 import { isWrapped } from '@opentelemetry/core';
-import { consoleSandbox, getClient, getGlobalScope, hasTracingEnabled, isEnabled } from '@sentry/core';
+import { consoleSandbox, getClient, getGlobalScope, hasSpansEnabled, isEnabled } from '@sentry/core';
 import type { NodeClient } from '../sdk/client';
 import { isCjs } from './commonjs';
 import { createMissingInstrumentationContext } from './createMissingInstrumentationContext';
@@ -11,12 +11,12 @@ export function ensureIsWrapped(
   maybeWrappedFunction: unknown,
   name: 'express' | 'connect' | 'fastify' | 'hapi' | 'koa',
 ): void {
-  const client = getClient<NodeClient>();
+  const clientOptions = getClient<NodeClient>()?.getOptions();
   if (
-    !client?.getOptions().disableInstrumentationWarnings &&
+    !clientOptions?.disableInstrumentationWarnings &&
     !isWrapped(maybeWrappedFunction) &&
     isEnabled() &&
-    hasTracingEnabled()
+    hasSpansEnabled(clientOptions)
   ) {
     consoleSandbox(() => {
       if (isCjs()) {
diff --git a/packages/opentelemetry/src/sampler.ts b/packages/opentelemetry/src/sampler.ts
@@ -13,7 +13,7 @@ import {
 import type { Client, SpanAttributes } from '@sentry/core';
 import { SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE } from '@sentry/core';
 import { baggageHeaderToDynamicSamplingContext } from '@sentry/core';
-import { SEMANTIC_ATTRIBUTE_SENTRY_OP, hasTracingEnabled, logger, parseSampleRate, sampleSpan } from '@sentry/core';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, hasSpansEnabled, logger, parseSampleRate, sampleSpan } from '@sentry/core';
 import {
   SENTRY_TRACE_STATE_DSC,
   SENTRY_TRACE_STATE_SAMPLED_NOT_RECORDING,
@@ -52,7 +52,7 @@ export class SentrySampler implements Sampler {
     const parentSpan = getValidSpan(context);
     const parentContext = parentSpan?.spanContext();
 
-    if (!hasTracingEnabled(options)) {
+    if (!hasSpansEnabled(options)) {
       return wrapSamplingDecision({ decision: undefined, context, spanAttributes });
     }
 
diff --git a/packages/opentelemetry/src/utils/enhanceDscWithOpenTelemetryRootSpanName.ts b/packages/opentelemetry/src/utils/enhanceDscWithOpenTelemetryRootSpanName.ts
@@ -1,4 +1,4 @@
-import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, hasTracingEnabled, spanToJSON } from '@sentry/core';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, hasSpansEnabled, spanToJSON } from '@sentry/core';
 import type { Client } from '@sentry/core';
 import { getSamplingDecision } from './getSamplingDecision';
 import { parseSpanDescription } from './parseSpanDescription';
@@ -32,7 +32,7 @@ export function enhanceDscWithOpenTelemetryRootSpanName(client: Client): void {
     // Also ensure sampling decision is correctly inferred
     // In core, we use `spanIsSampled`, which just looks at the trace flags
     // but in OTEL, we use a slightly more complex logic to be able to differntiate between unsampled and deferred sampling
-    if (hasTracingEnabled()) {
+    if (hasSpansEnabled()) {
       const sampled = getSamplingDecision(rootSpan.spanContext());
       dsc.sampled = sampled == undefined ? undefined : String(sampled);
     }
diff --git a/packages/remix/src/utils/instrumentServer.ts b/packages/remix/src/utils/instrumentServer.ts
@@ -4,7 +4,7 @@ import {
   fill,
   getClient,
   getTraceData,
-  hasTracingEnabled,
+  hasSpansEnabled,
   isNodeEnv,
   loadModule,
   logger,
@@ -197,7 +197,7 @@ function wrapRequestHandler(origRequestHandler: RequestHandler): RequestHandler
 
       isolationScope.setSDKProcessingMetadata({ normalizedRequest });
 
-      if (!options || !hasTracingEnabled(options)) {
+      if (!options || !hasSpansEnabled(options)) {
         return origRequestHandler.call(this, request, loadContext);
       }
 
diff --git a/packages/vercel-edge/src/sdk.ts b/packages/vercel-edge/src/sdk.ts
@@ -15,7 +15,7 @@ import {
   functionToStringIntegration,
   getCurrentScope,
   getIntegrationsToSetup,
-  hasTracingEnabled,
+  hasSpansEnabled,
   inboundFiltersIntegration,
   linkedErrorsIntegration,
   logger,
@@ -124,7 +124,7 @@ function validateOpenTelemetrySetup(): void {
 
   const required: ReturnType<typeof openTelemetrySetupCheck> = ['SentryContextManager', 'SentryPropagator'];
 
-  if (hasTracingEnabled()) {
+  if (hasSpansEnabled()) {
     required.push('SentrySpanProcessor');
   }
 
diff --git a/packages/vue/src/integration.ts b/packages/vue/src/integration.ts
