feat: Add support for SENTRY_SPOTLIGHT env var in Node

.vscode/settings.json

@@ -42,5 +42,5 @@
   "[typescript]": {
     "editor.defaultFormatter": "biomejs.biome"
   },
-  "cSpell.words": ["arrayify"]
+  "cSpell.words": ["arrayify", "OTEL"]
 }

packages/node/src/preload.ts

@@ -1,13 +1,14 @@
 import { preloadOpenTelemetry } from './sdk/initOtel';
+import { envToBool } from './utils/envToBool';
 
-const debug = !!process.env.SENTRY_DEBUG;
+const debug = envToBool(process.env.SENTRY_DEBUG);
 const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
 
 const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;
 
 /**
- * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL instrumentation,
- * without initializing the Sentry SDK.
+ * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
+ * instrumentation, without initializing the Sentry SDK.
  *
  * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
  * e.g. if you have to load the DSN from somewhere else.

packages/node/src/sdk/index.ts

@@ -41,6 +41,7 @@ import { getAutoPerformanceIntegrations } from '../integrations/tracing';
 import { makeNodeTransport } from '../transports';
 import type { NodeClientOptions, NodeOptions } from '../types';
 import { isCjs } from '../utils/commonjs';
+import { envToBool } from '../utils/envToBool';
 import { defaultStackParser, getSentryRelease } from './api';
 import { NodeClient } from './client';
 import { initOpenTelemetry, maybeInitializeEsmLoader } from './initOtel';
@@ -221,6 +222,15 @@ function getClientOptions(
         ? true
         : options.autoSessionTracking;
 
+  if (options.spotlight == null) {
+    const spotlightEnv = envToBool(process.env.SENTRY_SPOTLIGHT, { strict: true });
+    if (spotlightEnv == null) {
+      options.spotlight = process.env.SENTRY_SPOTLIGHT;
+    } else {
+      options.spotlight = spotlightEnv;
+    }
+  }
+
   const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
 
   const baseOptions = dropUndefinedKeys({
@@ -292,8 +302,7 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  * for more details.
  */
 function updateScopeFromEnvVariables(): void {
-  const sentryUseEnvironment = (process.env.SENTRY_USE_ENVIRONMENT || '').toLowerCase();
-  if (!['false', 'n', 'no', 'off', '0'].includes(sentryUseEnvironment)) {
+  if (envToBool(process.env.SENTRY_USE_ENVIRONMENT) !== false) {
     const sentryTraceEnv = process.env.SENTRY_TRACE;
     const baggageEnv = process.env.SENTRY_BAGGAGE;
     const propagationContext = propagationContextFromHeaders(sentryTraceEnv, baggageEnv);

packages/node/src/utils/envToBool.ts

@@ -0,0 +1,37 @@
+export const FALSY_ENV_VALUES = new Set(['false', 'n', 'no', 'off', '0']);
+export const TRUTHY_ENV_VALUES = new Set(['true', 'y', 'yes', 'on', '1']);
+
+export type StrictBoolCast = {
+  strict: true;
+};
+
+export type LooseBoolCast = {
+  strict?: false;
+};
+
+export type BoolCastOptions = StrictBoolCast | LooseBoolCast;
+
+export function envToBool(value: unknown, options?: LooseBoolCast): boolean;
+export function envToBool(value: unknown, options: StrictBoolCast): boolean | null;
+/**
+ * A helper function which casts an ENV variable value to `true` or `false` using the constants defined above.
+ * In strict mode, it may return `null` if the value doesn't match any of the predefined values.
+ *
+ * @param value The value of the env variable
+ * @param options -- Only has `strict` key for now, which requires a strict match for `true` in TRUTHY_ENV_VALUES
+ * @returns true/false if the lowercase value matches the predefined values above. If not, null in strict mode,
+ *          and Boolean(value) in loose mode.
+ */
+export function envToBool(value: unknown, options?: BoolCastOptions): boolean | null {
+  const normalized = String(value).toLowerCase();
+
+  if (FALSY_ENV_VALUES.has(normalized)) {
+    return false;
+  }
+
+  if (TRUTHY_ENV_VALUES.has(normalized)) {
+    return true;
+  }
+
+  return options && options.strict ? null : Boolean(value);
+}