Dup integration and utils to core, todos in index and integration

aliu39 · aliu39 · commit 70ccac1034c1 · 2025-06-09T21:13:16.000-05:00
diff --git a/packages/browser/src/index.ts b/packages/browser/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';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -112,6 +112,7 @@ export { supabaseIntegration, instrumentSupabaseClient } from './integrations/su
 export { zodErrorsIntegration } from './integrations/zoderrors';
 export { thirdPartyErrorFilterIntegration } from './integrations/third-party-errors-filter';
 export { consoleIntegration } from './integrations/console';
+export { featureFlagsIntegration, type FeatureFlagsIntegration } from './integrations/featureFlags';
 
 export { profiler } from './profiling';
 export { instrumentFetchRequest } from './fetch';
@@ -123,6 +124,8 @@ export { _INTERNAL_captureLog, _INTERNAL_flushLogsBuffer, _INTERNAL_captureSeria
 export { consoleLoggingIntegration } from './logs/console-integration';
 
 export type { FeatureFlag } from './featureFlags';
+// TODO: ^export from utils?
+// TODO: how to export utils without making public?
 
 export { applyAggregateErrorsToEvent } from './utils-hoist/aggregate-errors';
 export { getBreadcrumbLogLevelFromHttpStatusCode } from './utils-hoist/breadcrumb-log-level';
diff --git a/packages/core/src/integrations/featureFlags/featureFlagsIntegration.ts b/packages/core/src/integrations/featureFlags/featureFlagsIntegration.ts
@@ -0,0 +1,60 @@
+import { type Client } from '../../client';
+import { defineIntegration } from '../../integration';
+import { type Event, type EventHint } from '../../types-hoist/event';
+import { type Integration, type IntegrationFn } from '../../types-hoist/integration';
+import { type Span } from '../../types-hoist/span';
+import {
+  bufferSpanFeatureFlag,
+  copyFlagsFromScopeToEvent,
+  freezeSpanFeatureFlags,
+  insertFlagToScope,
+} from '../../utils/featureFlags';
+
+export interface FeatureFlagsIntegration extends Integration {
+  addFeatureFlag: (name: string, value: unknown) => void;
+}
+
+/**
+ * Sentry integration for buffering feature flag evaluations manually with an API, and
+ * capturing them on error events and spans.
+ *
+ * See the [feature flag documentation](https://develop.sentry.dev/sdk/expected-features/#feature-flags) for more information.
+ *
+ * @example
+ * ```
+ * import * as Sentry from '@sentry/*'; //TODO:
+ * import { type FeatureFlagsIntegration } from '@sentry/*';
+ *
+ * // Setup
+ * Sentry.init(..., integrations: [Sentry.featureFlagsIntegration()])
+ *
+ * // Verify
+ * const flagsIntegration = Sentry.getClient()?.getIntegrationByName<FeatureFlagsIntegration>('FeatureFlags');
+ * if (flagsIntegration) {
+ *   flagsIntegration.addFeatureFlag('my-flag', true);
+ * } else {
+ *   // check your setup
+ * }
+ * Sentry.captureException(Exception('broke')); // 'my-flag' should be captured to this Sentry event.
+ * ```
+ */
+export const featureFlagsIntegration = defineIntegration(() => {
+  return {
+    name: 'FeatureFlags',
+
+    setup(client: Client) {
+      client.on('spanEnd', (span: Span) => {
+        freezeSpanFeatureFlags(span);
+      });
+    },
+
+    processEvent(event: Event, _hint: EventHint, _client: Client): Event {
+      return copyFlagsFromScopeToEvent(event);
+    },
+
+    addFeatureFlag(name: string, value: unknown): void {
+      insertFlagToScope(name, value);
+      bufferSpanFeatureFlag(name, value);
+    },
+  };
+}) as IntegrationFn<FeatureFlagsIntegration>;
diff --git a/packages/core/src/integrations/featureFlags/index.ts b/packages/core/src/integrations/featureFlags/index.ts
@@ -0,0 +1 @@
+export { featureFlagsIntegration, type FeatureFlagsIntegration } from './featureFlagsIntegration';
diff --git a/packages/core/src/utils/featureFlags.ts b/packages/core/src/utils/featureFlags.ts
@@ -0,0 +1,161 @@
+import { getCurrentScope } from '../currentScopes';
+import { DEBUG_BUILD } from '../debug-build';
+import { type FeatureFlag } from '../featureFlags';
+import { type Event } from '../types-hoist/event';
+import { type Span } from '../types-hoist/span';
+import { logger } from '../utils-hoist/logger';
+import { GLOBAL_OBJ } from '../utils-hoist/worldwide';
+import { getActiveSpan } from './spanUtils';
+
+/**
+ * Ordered LRU cache for storing feature flags in the scope context. The name
+ * of each flag in the buffer is unique, and the output of getAll() is ordered
+ * from oldest to newest.
+ */
+
+/**
+ * Max size of the LRU flag buffer stored in Sentry scope and event contexts.
+ */
+export const FLAG_BUFFER_SIZE = 100;
+
+/**
+ * Max number of flag evaluations to record per span.
+ */
+export const MAX_FLAGS_PER_SPAN = 10;
+
+// Global map of spans to feature flag buffers. Populated by feature flag integrations.
+GLOBAL_OBJ._spanToFlagBufferMap = new WeakMap<Span, FeatureFlag[]>();
+
+const SPAN_FLAG_ATTRIBUTE_PREFIX = 'flag.evaluation.';
+
+/**
+ * Copies feature flags that are in current scope context to the event context
+ */
+export function copyFlagsFromScopeToEvent(event: Event): Event {
+  const scope = getCurrentScope();
+  const flagContext = scope.getScopeData().contexts.flags;
+  const flagBuffer = flagContext ? flagContext.values : [];
+
+  if (!flagBuffer.length) {
+    return event;
+  }
+
+  if (event.contexts === undefined) {
+    event.contexts = {};
+  }
+  event.contexts.flags = { values: [...flagBuffer] };
+  return event;
+}
+
+/**
+ * Inserts a flag into the current scope's context while maintaining ordered LRU properties.
+ * Not thread-safe. After inserting:
+ * - The flag buffer is sorted in order of recency, with the newest evaluation at the end.
+ * - The names in the buffer are always unique.
+ * - The length of the buffer never exceeds `maxSize`.
+ *
+ * @param name     Name of the feature flag to insert.
+ * @param value    Value of the feature flag.
+ * @param maxSize  Max number of flags the buffer should store. Default value should always be used in production.
+ */
+export function insertFlagToScope(name: string, value: unknown, maxSize: number = FLAG_BUFFER_SIZE): void {
+  const scopeContexts = getCurrentScope().getScopeData().contexts;
+  if (!scopeContexts.flags) {
+    scopeContexts.flags = { values: [] };
+  }
+  const flags = scopeContexts.flags.values as FeatureFlag[];
+  insertToFlagBuffer(flags, name, value, maxSize);
+}
+
+/**
+ * Exported for tests only. Currently only accepts boolean values (otherwise no-op).
+ * Inserts a flag into a FeatureFlag array while maintaining the following properties:
+ * - Flags are sorted in order of recency, with the newest evaluation at the end.
+ * - The flag names are always unique.
+ * - The length of the array never exceeds `maxSize`.
+ *
+ * @param flags      The buffer to insert the flag into.
+ * @param name       Name of the feature flag to insert.
+ * @param value      Value of the feature flag.
+ * @param maxSize    Max number of flags the buffer should store. Default value should always be used in production.
+ * @param allowEviction  If true, the oldest flag is evicted when the buffer is full. Otherwise the new flag is dropped.
+ */
+export function insertToFlagBuffer(
+  flags: FeatureFlag[],
+  name: string,
+  value: unknown,
+  maxSize: number,
+  allowEviction: boolean = true,
+): void {
+  if (typeof value !== 'boolean') {
+    return;
+  }
+
+  if (flags.length > maxSize) {
+    DEBUG_BUILD && logger.error(`[Feature Flags] insertToFlagBuffer called on a buffer larger than maxSize=${maxSize}`);
+    return;
+  }
+
+  // Check if the flag is already in the buffer - O(n)
+  const index = flags.findIndex(f => f.flag === name);
+
+  if (index !== -1) {
+    // The flag was found, remove it from its current position - O(n)
+    flags.splice(index, 1);
+  }
+
+  if (flags.length === maxSize) {
+    if (allowEviction) {
+      // If at capacity, pop the earliest flag - O(n)
+      flags.shift();
+    } else {
+      return;
+    }
+  }
+
+  // Push the flag to the end - O(1)
+  flags.push({
+    flag: name,
+    result: value,
+  });
+}
+
+/**
+ * Records a feature flag evaluation for the active span, adding it to a weak map of flag buffers. This is a no-op for non-boolean values.
+ * The keys in each buffer are unique. Once the buffer for a span reaches maxFlagsPerSpan, subsequent flags are dropped.
+ *
+ * @param name             Name of the feature flag.
+ * @param value            Value of the feature flag. Non-boolean values are ignored.
+ * @param maxFlagsPerSpan  Max number of flags a buffer should store. Default value should always be used in production.
+ */
+export function bufferSpanFeatureFlag(
+  name: string,
+  value: unknown,
+  maxFlagsPerSpan: number = MAX_FLAGS_PER_SPAN,
+): void {
+  const spanFlagMap = GLOBAL_OBJ._spanToFlagBufferMap;
+  if (!spanFlagMap || typeof value !== 'boolean') {
+    return;
+  }
+
+  const span = getActiveSpan();
+  if (span) {
+    const flags = spanFlagMap.get(span) || [];
+    insertToFlagBuffer(flags, name, value, maxFlagsPerSpan, false);
+    spanFlagMap.set(span, flags);
+  }
+}
+
+/**
+ * Add the buffered feature flags for a span to the span attributes. Call this on span end.
+ *
+ * @param span         Span to add flags to.
+ */
+export function freezeSpanFeatureFlags(span: Span): void {
+  const flags = GLOBAL_OBJ._spanToFlagBufferMap?.get(span);
+  if (flags) {
+    span.setAttributes(
+      Object.fromEntries(flags.map(flag => [`${SPAN_FLAG_ATTRIBUTE_PREFIX}${flag.flag}`, flag.result])),
+    );
+  }
+}
diff --git a/packages/core/test/lib/utils/featureFlags.test.ts b/packages/core/test/lib/utils/featureFlags.test.ts
@@ -0,0 +1,128 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getCurrentScope } from '../../../src/currentScopes';
+import { type FeatureFlag } from '../../../src/featureFlags';
+import { insertFlagToScope, insertToFlagBuffer } from '../../../src/utils/featureFlags';
+import { logger } from '../../../src/utils-hoist/logger';
+
+describe('flags', () => {
+  describe('insertFlagToScope()', () => {
+    it('adds flags to the current scope context', () => {
+      const maxSize = 3;
+      insertFlagToScope('feat1', true, maxSize);
+      insertFlagToScope('feat2', true, maxSize);
+      insertFlagToScope('feat3', true, maxSize);
+      insertFlagToScope('feat4', true, maxSize);
+
+      const scope = getCurrentScope();
+      expect(scope.getScopeData().contexts.flags?.values).toEqual([
+        { flag: 'feat2', result: true },
+        { flag: 'feat3', result: true },
+        { flag: 'feat4', result: true },
+      ]);
+    });
+  });
+
+  describe('insertToFlagBuffer()', () => {
+    const loggerSpy = vi.spyOn(logger, 'error');
+
+    afterEach(() => {
+      loggerSpy.mockClear();
+    });
+
+    it('maintains ordering and evicts the oldest entry', () => {
+      const buffer: FeatureFlag[] = [];
+      const maxSize = 3;
+      insertToFlagBuffer(buffer, 'feat1', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat2', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat3', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat4', true, maxSize);
+
+      expect(buffer).toEqual([
+        { flag: 'feat2', result: true },
+        { flag: 'feat3', result: true },
+        { flag: 'feat4', result: true },
+      ]);
+    });
+
+    it('does not duplicate same-name flags and updates order and values', () => {
+      const buffer: FeatureFlag[] = [];
+      const maxSize = 3;
+      insertToFlagBuffer(buffer, 'feat1', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat2', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat3', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat3', false, maxSize);
+      insertToFlagBuffer(buffer, 'feat1', false, maxSize);
+
+      expect(buffer).toEqual([
+        { flag: 'feat2', result: true },
+        { flag: 'feat3', result: false },
+        { flag: 'feat1', result: false },
+      ]);
+    });
+
+    it('drops new entries when allowEviction is false and buffer is full', () => {
+      const buffer: FeatureFlag[] = [];
+      const maxSize = 0;
+      insertToFlagBuffer(buffer, 'feat1', true, maxSize, false);
+      insertToFlagBuffer(buffer, 'feat2', true, maxSize, false);
+      insertToFlagBuffer(buffer, 'feat3', true, maxSize, false);
+
+      expect(buffer).toEqual([]);
+    });
+
+    it('still updates order and values when allowEviction is false and buffer is full', () => {
+      const buffer: FeatureFlag[] = [];
+      const maxSize = 1;
+      insertToFlagBuffer(buffer, 'feat1', false, maxSize, false);
+      insertToFlagBuffer(buffer, 'feat1', true, maxSize, false);
+
+      expect(buffer).toEqual([{ flag: 'feat1', result: true }]);
+    });
+
+    it('does not allocate unnecessary space', () => {
+      const buffer: FeatureFlag[] = [];
+      const maxSize = 1000;
+      insertToFlagBuffer(buffer, 'feat1', true, maxSize);
+      insertToFlagBuffer(buffer, 'feat2', true, maxSize);
+
+      expect(buffer).toEqual([
+        { flag: 'feat1', result: true },
+        { flag: 'feat2', result: true },
+      ]);
+    });
+
+    it('does not accept non-boolean values', () => {
+      const buffer: FeatureFlag[] = [];
+      const maxSize = 1000;
+      insertToFlagBuffer(buffer, 'feat1', 1, maxSize);
+      insertToFlagBuffer(buffer, 'feat2', 'string', maxSize);
+
+      expect(buffer).toEqual([]);
+    });
+
+    it('logs error and is a no-op when buffer is larger than maxSize', () => {
+      const buffer: FeatureFlag[] = [
+        { flag: 'feat1', result: true },
+        { flag: 'feat2', result: true },
+      ];
+
+      insertToFlagBuffer(buffer, 'feat1', true, 1);
+      expect(loggerSpy).toHaveBeenCalledWith(
+        expect.stringContaining('[Feature Flags] insertToFlagBuffer called on a buffer larger than maxSize'),
+      );
+      expect(buffer).toEqual([
+        { flag: 'feat1', result: true },
+        { flag: 'feat2', result: true },
+      ]);
+
+      insertToFlagBuffer(buffer, 'feat1', true, -2);
+      expect(loggerSpy).toHaveBeenCalledWith(
+        expect.stringContaining('[Feature Flags] insertToFlagBuffer called on a buffer larger than maxSize'),
+      );
+      expect(buffer).toEqual([
+        { flag: 'feat1', result: true },
+        { flag: 'feat2', result: true },
+      ]);
+    });
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export { featureFlagsIntegration, type FeatureFlagsIntegration } from './featureFlagsIntegration';`