feat(flags): add node support for generic featureFlagsIntegration and move utils to core (#16585)

The `featureFlagsIntegration` is an integration to manually buffer
feature flags on evaluation, and capture them in event contexts and span
attributes. This PR moves it from browser to core, as well as the shared
functionality/utils of all FF integrations (no browser specific logic).

Browser exports and functionality is unchanged. Per @AbhiPrasad 's
recommendation I've manually exported the integration in all the
packages `zodErrorsIntegration` is exported. Note many backend pkgs use
a wildcard (*) export from node.

TODO:
- [x] add node-integration-tests
- [ ] update platform docs

Part of
- getsentry/team-replay#510

Author: aliu39

dev-packages/browser-integration-tests/suites/integrations/featureFlags/constants.ts

@@ -1,11 +1,11 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
 import { sentryTest } from '../../../../../../utils/fixtures';
 import {
   envelopeRequestParser,
   shouldSkipFeatureFlagsTest,
   waitForErrorRequest,
 } from '../../../../../../utils/helpers';
-import { FLAG_BUFFER_SIZE } from '../../../constants';
 
 sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/featureFlags/onError/basic/test.ts

@@ -1,4 +1,5 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
 import { sentryTest } from '../../../../../utils/fixtures';
 import {
   type EventAndTraceHeader,
@@ -7,7 +8,6 @@ import {
   shouldSkipFeatureFlagsTest,
   shouldSkipTracingTest,
 } from '../../../../../utils/helpers';
-import { MAX_FLAGS_PER_SPAN } from '../../constants';
 
 sentryTest("Feature flags are added to active span's attributes on span end.", async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest() || shouldSkipTracingTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/featureFlags/onSpan/test.ts

@@ -1,11 +1,11 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
 import { sentryTest } from '../../../../../../utils/fixtures';
 import {
   envelopeRequestParser,
   shouldSkipFeatureFlagsTest,
   waitForErrorRequest,
 } from '../../../../../../utils/helpers';
-import { FLAG_BUFFER_SIZE } from '../../../constants';
 
 sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/onError/basic/test.ts

@@ -1,4 +1,5 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
 import { sentryTest } from '../../../../../utils/fixtures';
 import {
   type EventAndTraceHeader,
@@ -7,7 +8,6 @@ import {
   shouldSkipFeatureFlagsTest,
   shouldSkipTracingTest,
 } from '../../../../../utils/helpers';
-import { MAX_FLAGS_PER_SPAN } from '../../constants';
 
 sentryTest("Feature flags are added to active span's attributes on span end.", async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest() || shouldSkipTracingTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/onSpan/test.ts

@@ -1,11 +1,11 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
 import { sentryTest } from '../../../../../../utils/fixtures';
 import {
   envelopeRequestParser,
   shouldSkipFeatureFlagsTest,
   waitForErrorRequest,
 } from '../../../../../../utils/helpers';
-import { FLAG_BUFFER_SIZE } from '../../../constants';
 
 sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/openfeature/onError/basic/test.ts

@@ -1,11 +1,11 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
 import { sentryTest } from '../../../../../../utils/fixtures';
 import {
   envelopeRequestParser,
   shouldSkipFeatureFlagsTest,
   waitForErrorRequest,
 } from '../../../../../../utils/helpers';
-import { FLAG_BUFFER_SIZE } from '../../../constants';
 
 sentryTest('Flag evaluation error hook', async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/openfeature/onError/errorHook/test.ts

@@ -1,4 +1,5 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
 import { sentryTest } from '../../../../../utils/fixtures';
 import {
   type EventAndTraceHeader,
@@ -7,7 +8,6 @@ import {
   shouldSkipFeatureFlagsTest,
   shouldSkipTracingTest,
 } from '../../../../../utils/helpers';
-import { MAX_FLAGS_PER_SPAN } from '../../constants';
 
 sentryTest("Feature flags are added to active span's attributes on span end.", async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest() || shouldSkipTracingTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/openfeature/onSpan/test.ts

@@ -1,11 +1,11 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
 import { sentryTest } from '../../../../../../utils/fixtures';
 import {
   envelopeRequestParser,
   shouldSkipFeatureFlagsTest,
   waitForErrorRequest,
 } from '../../../../../../utils/helpers';
-import { FLAG_BUFFER_SIZE } from '../../../constants';
 
 sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/statsig/onError/basic/test.ts

@@ -1,4 +1,5 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
 import { sentryTest } from '../../../../../utils/fixtures';
 import {
   type EventAndTraceHeader,
@@ -7,7 +8,6 @@ import {
   shouldSkipFeatureFlagsTest,
   shouldSkipTracingTest,
 } from '../../../../../utils/helpers';
-import { MAX_FLAGS_PER_SPAN } from '../../constants';
 
 sentryTest("Feature flags are added to active span's attributes on span end.", async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest() || shouldSkipTracingTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/statsig/onSpan/test.ts

@@ -1,11 +1,11 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
 import { sentryTest } from '../../../../../../utils/fixtures';
 import {
   envelopeRequestParser,
   shouldSkipFeatureFlagsTest,
   waitForErrorRequest,
 } from '../../../../../../utils/helpers';
-import { FLAG_BUFFER_SIZE } from '../../../constants';
 
 sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/onError/basic/test.ts

@@ -1,4 +1,5 @@
 import { expect } from '@playwright/test';
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
 import { sentryTest } from '../../../../../utils/fixtures';
 import {
   type EventAndTraceHeader,
@@ -7,7 +8,6 @@ import {
   shouldSkipFeatureFlagsTest,
   shouldSkipTracingTest,
 } from '../../../../../utils/helpers';
-import { MAX_FLAGS_PER_SPAN } from '../../constants';
 
 sentryTest("Feature flags are added to active span's attributes on span end.", async ({ getLocalTestUrl, page }) => {
   if (shouldSkipFeatureFlagsTest() || shouldSkipTracingTest()) {

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/onSpan/test.ts

@@ -0,0 +1,19 @@
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  sampleRate: 1.0,
+  transport: loggingTransport,
+  integrations: [Sentry.featureFlagsIntegration()],
+});
+
+const flagsIntegration = Sentry.getClient()?.getIntegrationByName<Sentry.FeatureFlagsIntegration>('FeatureFlags');
+for (let i = 1; i <= FLAG_BUFFER_SIZE; i++) {
+  flagsIntegration?.addFeatureFlag(`feat${i}`, false);
+}
+flagsIntegration?.addFeatureFlag(`feat${FLAG_BUFFER_SIZE + 1}`, true); // eviction
+flagsIntegration?.addFeatureFlag('feat3', true); // update
+
+throw new Error('Test error');

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onError/basic/scenario.ts

@@ -0,0 +1,31 @@
+import { _INTERNAL_FLAG_BUFFER_SIZE as FLAG_BUFFER_SIZE } from '@sentry/core';
+import { afterAll, test } from 'vitest';
+import { cleanupChildProcesses, createRunner } from '../../../../../utils/runner';
+
+afterAll(() => {
+  cleanupChildProcesses();
+});
+
+test('Flags captured on error with eviction, update, and no async tasks', async () => {
+  // Based on scenario.ts.
+  const expectedFlags = [{ flag: 'feat2', result: false }];
+  for (let i = 4; i <= FLAG_BUFFER_SIZE; i++) {
+    expectedFlags.push({ flag: `feat${i}`, result: false });
+  }
+  expectedFlags.push({ flag: `feat${FLAG_BUFFER_SIZE + 1}`, result: true });
+  expectedFlags.push({ flag: 'feat3', result: true });
+
+  await createRunner(__dirname, 'scenario.ts')
+    .expect({
+      event: {
+        exception: { values: [{ type: 'Error', value: 'Test error' }] },
+        contexts: {
+          flags: {
+            values: expectedFlags,
+          },
+        },
+      },
+    })
+    .start()
+    .completed();
+});

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onError/basic/test.ts

@@ -0,0 +1,22 @@
+import type { Scope } from '@sentry/node';
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  sampleRate: 1.0,
+  transport: loggingTransport,
+  integrations: [Sentry.featureFlagsIntegration()],
+});
+
+const flagsIntegration = Sentry.getClient()?.getIntegrationByName<Sentry.FeatureFlagsIntegration>('FeatureFlags');
+flagsIntegration?.addFeatureFlag('shared', true);
+
+Sentry.withScope((_scope: Scope) => {
+  flagsIntegration?.addFeatureFlag('forked', true);
+  flagsIntegration?.addFeatureFlag('shared', false);
+  Sentry.captureException(new Error('Error in forked scope'));
+});
+
+flagsIntegration?.addFeatureFlag('main', true);
+throw new Error('Error in main scope');

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onError/withScope/scenario.ts

@@ -0,0 +1,38 @@
+import { afterAll, test } from 'vitest';
+import { cleanupChildProcesses, createRunner } from '../../../../../utils/runner';
+
+afterAll(() => {
+  cleanupChildProcesses();
+});
+
+test('Flags captured on error are isolated by current scope', async () => {
+  await createRunner(__dirname, 'scenario.ts')
+    .expect({
+      event: {
+        exception: { values: [{ type: 'Error', value: 'Error in forked scope' }] },
+        contexts: {
+          flags: {
+            values: [
+              { flag: 'forked', result: true },
+              { flag: 'shared', result: false },
+            ],
+          },
+        },
+      },
+    })
+    .expect({
+      event: {
+        exception: { values: [{ type: 'Error', value: 'Error in main scope' }] },
+        contexts: {
+          flags: {
+            values: [
+              { flag: 'shared', result: true },
+              { flag: 'main', result: true },
+            ],
+          },
+        },
+      },
+    })
+    .start()
+    .completed();
+});

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onError/withScope/test.ts

@@ -0,0 +1,25 @@
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  sampleRate: 1.0,
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+  integrations: [Sentry.featureFlagsIntegration()],
+});
+
+const flagsIntegration = Sentry.getClient()?.getIntegrationByName<Sentry.FeatureFlagsIntegration>('FeatureFlags');
+
+Sentry.startSpan({ name: 'test-root-span' }, () => {
+  Sentry.startSpan({ name: 'test-span' }, () => {
+    Sentry.startSpan({ name: 'test-nested-span' }, () => {
+      for (let i = 1; i <= MAX_FLAGS_PER_SPAN; i++) {
+        flagsIntegration?.addFeatureFlag(`feat${i}`, false);
+      }
+      flagsIntegration?.addFeatureFlag(`feat${MAX_FLAGS_PER_SPAN + 1}`, true); // dropped flag
+      flagsIntegration?.addFeatureFlag('feat3', true); // update
+    });
+  });
+});

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onSpan/scenario.ts

@@ -0,0 +1,33 @@
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
+import { afterAll, expect, test } from 'vitest';
+import { cleanupChildProcesses, createRunner } from '../../../../utils/runner';
+
+afterAll(() => {
+  cleanupChildProcesses();
+});
+
+test('Flags captured on span attributes with max limit', async () => {
+  // Based on scenario.ts.
+  const expectedFlags: Record<string, boolean> = {};
+  for (let i = 1; i <= MAX_FLAGS_PER_SPAN; i++) {
+    expectedFlags[`flag.evaluation.feat${i}`] = i === 3;
+  }
+
+  await createRunner(__dirname, 'scenario.ts')
+    .expect({
+      transaction: {
+        spans: [
+          expect.objectContaining({
+            description: 'test-span',
+            data: expect.objectContaining({}),
+          }),
+          expect.objectContaining({
+            description: 'test-nested-span',
+            data: expect.objectContaining(expectedFlags),
+          }),
+        ],
+      },
+    })
+    .start()
+    .completed();
+});

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onSpan/test.ts

@@ -135,6 +135,8 @@ export {
   consoleLoggingIntegration,
   wrapMcpServerWithSentry,
   NODE_VERSION,
+  featureFlagsIntegration,
+  type FeatureFlagsIntegration,
 } from '@sentry/node';
 
 export { init } from './server/sdk';

packages/astro/src/index.server.ts

@@ -121,6 +121,8 @@ export {
   consoleLoggingIntegration,
   wrapMcpServerWithSentry,
   NODE_VERSION,
+  featureFlagsIntegration,
+  type FeatureFlagsIntegration,
 } from '@sentry/node';
 
 export {

packages/aws-serverless/src/index.ts

@@ -61,13 +61,13 @@ export {
   instrumentSupabaseClient,
   zodErrorsIntegration,
   thirdPartyErrorFilterIntegration,
+  featureFlagsIntegration,
 } from '@sentry/core';
-export type { Span } from '@sentry/core';
+export type { Span, FeatureFlagsIntegration } from '@sentry/core';
 export { makeBrowserOfflineTransport } from './transports/offline';
 export { browserProfilingIntegration } from './profiling/integration';
 export { spotlightBrowserIntegration } from './integrations/spotlight';
 export { browserSessionIntegration } from './integrations/browsersession';
-export { featureFlagsIntegration, type FeatureFlagsIntegration } from './integrations/featureFlags';
 export { launchDarklyIntegration, buildLaunchDarklyFlagUsedHandler } from './integrations/featureFlags/launchdarkly';
 export { openFeatureIntegration, OpenFeatureIntegrationHook } from './integrations/featureFlags/openfeature';
 export { unleashIntegration } from './integrations/featureFlags/unleash';

packages/browser/src/index.ts

@@ -1,6 +1,10 @@
 import type { Client, Event, EventHint, IntegrationFn } from '@sentry/core';
-import { defineIntegration } from '@sentry/core';
-import { addFeatureFlagToActiveSpan, copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
+import {
+  _INTERNAL_addFeatureFlagToActiveSpan,
+  _INTERNAL_copyFlagsFromScopeToEvent,
+  _INTERNAL_insertFlagToScope,
+  defineIntegration,
+} from '@sentry/core';
 import type { LDContext, LDEvaluationDetail, LDInspectionFlagUsedHandler } from './types';
 
 /**
@@ -23,7 +27,7 @@ export const launchDarklyIntegration = defineIntegration(() => {
     name: 'LaunchDarkly',
 
     processEvent(event: Event, _hint: EventHint, _client: Client): Event {
-      return copyFlagsFromScopeToEvent(event);
+      return _INTERNAL_copyFlagsFromScopeToEvent(event);
     },
   };
 }) satisfies IntegrationFn;
@@ -45,8 +49,8 @@ export function buildLaunchDarklyFlagUsedHandler(): LDInspectionFlagUsedHandler
      * Handle a flag evaluation by storing its name and value on the current scope.
      */
     method: (flagKey: string, flagDetail: LDEvaluationDetail, _context: LDContext) => {
-      insertFlagToScope(flagKey, flagDetail.value);
-      addFeatureFlagToActiveSpan(flagKey, flagDetail.value);
+      _INTERNAL_insertFlagToScope(flagKey, flagDetail.value);
+      _INTERNAL_addFeatureFlagToActiveSpan(flagKey, flagDetail.value);
     },
   };
 }