diff --git a/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/basic/test.ts b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/basic/test.ts
new file mode 100644
index 000000000000..d4686433d3ed
--- /dev/null
+++ b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/basic/test.ts
@@ -0,0 +1,48 @@
+import { expect } from '@playwright/test';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+
+import { envelopeRequestParser, shouldSkipFeatureFlagsTest, waitForErrorRequest } from '../../../../../utils/helpers';
+
+const FLAG_BUFFER_SIZE = 100; // Corresponds to constant in featureFlags.ts, in browser utils.
+
+sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
+ if (shouldSkipFeatureFlagsTest()) {
+ sentryTest.skip();
+ }
+
+ await page.route('https://dsn.ingest.sentry.io/**/*', route => {
+ return route.fulfill({
+ status: 200,
+ contentType: 'application/json',
+ body: JSON.stringify({ id: 'test-id' }),
+ });
+ });
+
+ const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+ await page.goto(url);
+
+ await page.waitForFunction(bufferSize => {
+ const ldClient = (window as any).initializeLD();
+ for (let i = 1; i <= bufferSize; i++) {
+ ldClient.variation(`feat${i}`, false);
+ }
+ ldClient.variation(`feat${bufferSize + 1}`, true); // eviction
+ ldClient.variation('feat3', true); // update
+ return true;
+ }, FLAG_BUFFER_SIZE);
+
+ const reqPromise = waitForErrorRequest(page);
+ await page.locator('#error').click();
+ const req = await reqPromise;
+ const event = envelopeRequestParser(req);
+
+ 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 });
+
+ expect(event.contexts?.flags?.values).toEqual(expectedFlags);
+});
diff --git a/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/init.js b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/init.js
new file mode 100644
index 000000000000..aeea903b4eab
--- /dev/null
+++ b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/init.js
@@ -0,0 +1,35 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+window.sentryLDIntegration = Sentry.launchDarklyIntegration();
+
+Sentry.init({
+ dsn: 'https://public@dsn.ingest.sentry.io/1337',
+ sampleRate: 1.0,
+ integrations: [window.sentryLDIntegration],
+});
+
+// Manually mocking this because LD only has mock test utils for the React SDK.
+// Also, no SDK has mock utils for FlagUsedHandler's.
+const MockLaunchDarkly = {
+ initialize(_clientId, context, options) {
+ const flagUsedHandler = options && options.inspectors ? options.inspectors[0].method : undefined;
+
+ return {
+ variation(key, defaultValue) {
+ if (flagUsedHandler) {
+ flagUsedHandler(key, { value: defaultValue }, context);
+ }
+ return defaultValue;
+ },
+ };
+ },
+};
+
+window.initializeLD = () => {
+ return MockLaunchDarkly.initialize(
+ 'example-client-id',
+ { kind: 'user', key: 'example-context-key' },
+ { inspectors: [Sentry.buildLaunchDarklyFlagUsedHandler()] },
+ );
+};
diff --git a/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/subject.js b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/subject.js
new file mode 100644
index 000000000000..e6697408128c
--- /dev/null
+++ b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/subject.js
@@ -0,0 +1,3 @@
+document.getElementById('error').addEventListener('click', () => {
+ throw new Error('Button triggered error');
+});
diff --git a/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/template.html b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/template.html
new file mode 100644
index 000000000000..9330c6c679f4
--- /dev/null
+++ b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/template.html
@@ -0,0 +1,9 @@
+
+
+
+
+
+
+
+
+
diff --git a/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/withScope/test.ts b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/withScope/test.ts
new file mode 100644
index 000000000000..43e2d307b5ed
--- /dev/null
+++ b/dev-packages/browser-integration-tests/suites/integrations/featureFlags/launchdarkly/withScope/test.ts
@@ -0,0 +1,65 @@
+import { expect } from '@playwright/test';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+
+import { envelopeRequestParser, shouldSkipFeatureFlagsTest, waitForErrorRequest } from '../../../../../utils/helpers';
+
+import type { Scope } from '@sentry/browser';
+
+sentryTest('Flag evaluations in forked scopes are stored separately.', async ({ getLocalTestUrl, page }) => {
+ if (shouldSkipFeatureFlagsTest()) {
+ sentryTest.skip();
+ }
+
+ await page.route('https://dsn.ingest.sentry.io/**/*', route => {
+ return route.fulfill({
+ status: 200,
+ contentType: 'application/json',
+ body: JSON.stringify({ id: 'test-id' }),
+ });
+ });
+
+ const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+ await page.goto(url);
+
+ const forkedReqPromise = waitForErrorRequest(page, event => !!event.tags && event.tags.isForked === true);
+ const mainReqPromise = waitForErrorRequest(page, event => !!event.tags && event.tags.isForked === false);
+
+ await page.waitForFunction(() => {
+ const Sentry = (window as any).Sentry;
+ const errorButton = document.querySelector('#error') as HTMLButtonElement;
+ const ldClient = (window as any).initializeLD();
+
+ ldClient.variation('shared', true);
+
+ Sentry.withScope((scope: Scope) => {
+ ldClient.variation('forked', true);
+ ldClient.variation('shared', false);
+ scope.setTag('isForked', true);
+ if (errorButton) {
+ errorButton.click();
+ }
+ });
+
+ ldClient.variation('main', true);
+ Sentry.getCurrentScope().setTag('isForked', false);
+ errorButton.click();
+ return true;
+ });
+
+ const forkedReq = await forkedReqPromise;
+ const forkedEvent = envelopeRequestParser(forkedReq);
+
+ const mainReq = await mainReqPromise;
+ const mainEvent = envelopeRequestParser(mainReq);
+
+ expect(forkedEvent.contexts?.flags?.values).toEqual([
+ { flag: 'forked', result: true },
+ { flag: 'shared', result: false },
+ ]);
+
+ expect(mainEvent.contexts?.flags?.values).toEqual([
+ { flag: 'shared', result: true },
+ { flag: 'main', result: true },
+ ]);
+});
diff --git a/dev-packages/browser-integration-tests/utils/helpers.ts b/dev-packages/browser-integration-tests/utils/helpers.ts
index 01d92a07a8e5..b77db038e020 100644
--- a/dev-packages/browser-integration-tests/utils/helpers.ts
+++ b/dev-packages/browser-integration-tests/utils/helpers.ts
@@ -273,6 +273,18 @@ export function shouldSkipMetricsTest(): boolean {
return bundle != null && !bundle.includes('tracing') && !bundle.includes('esm') && !bundle.includes('cjs');
}
+/**
+ * We only test feature flags integrations in certain bundles/packages:
+ * - NPM (ESM, CJS)
+ * - Not CDNs.
+ *
+ * @returns `true` if we should skip the feature flags test
+ */
+export function shouldSkipFeatureFlagsTest(): boolean {
+ const bundle = process.env.PW_BUNDLE as string | undefined;
+ return bundle != null && !bundle.includes('esm') && !bundle.includes('cjs');
+}
+
/**
* Waits until a number of requests matching urlRgx at the given URL arrive.
* If the timeout option is configured, this function will abort waiting, even if it hasn't received the configured
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
index bc720295b090..5f762c2cfa9b 100644
--- a/packages/browser/src/index.ts
+++ b/packages/browser/src/index.ts
@@ -77,3 +77,4 @@ export type { Span } from '@sentry/types';
export { makeBrowserOfflineTransport } from './transports/offline';
export { browserProfilingIntegration } from './profiling/integration';
export { spotlightBrowserIntegration } from './integrations/spotlight';
+export { launchDarklyIntegration, buildLaunchDarklyFlagUsedHandler } from './integrations/featureFlags/launchdarkly';
diff --git a/packages/browser/src/integrations/featureFlags/launchdarkly/index.ts b/packages/browser/src/integrations/featureFlags/launchdarkly/index.ts
new file mode 100644
index 000000000000..7a81279ad319
--- /dev/null
+++ b/packages/browser/src/integrations/featureFlags/launchdarkly/index.ts
@@ -0,0 +1 @@
+export { launchDarklyIntegration, buildLaunchDarklyFlagUsedHandler } from './integration';
diff --git a/packages/browser/src/integrations/featureFlags/launchdarkly/integration.ts b/packages/browser/src/integrations/featureFlags/launchdarkly/integration.ts
new file mode 100644
index 000000000000..3d5b491ed889
--- /dev/null
+++ b/packages/browser/src/integrations/featureFlags/launchdarkly/integration.ts
@@ -0,0 +1,68 @@
+import type { Client, Event, EventHint, IntegrationFn } from '@sentry/types';
+import type { LDContext, LDEvaluationDetail, LDInspectionFlagUsedHandler } from './types';
+
+import { defineIntegration, getCurrentScope } from '@sentry/core';
+import { insertToFlagBuffer } from '../../../utils/featureFlags';
+
+/**
+ * Sentry integration for capturing feature flags from LaunchDarkly.
+ *
+ * See the [feature flag documentation](https://develop.sentry.dev/sdk/expected-features/#feature-flags) for more information.
+ *
+ * @example
+ * ```
+ * import * as Sentry from '@sentry/browser';
+ * import {launchDarklyIntegration, buildLaunchDarklyFlagUsedInspector} from '@sentry/browser';
+ * import * as LaunchDarkly from 'launchdarkly-js-client-sdk';
+ *
+ * Sentry.init(..., integrations: [launchDarklyIntegration()])
+ * const ldClient = LaunchDarkly.initialize(..., {inspectors: [buildLaunchDarklyFlagUsedHandler()]});
+ * ```
+ */
+export const launchDarklyIntegration = defineIntegration(() => {
+ return {
+ name: 'LaunchDarkly',
+
+ processEvent(event: Event, _hint: EventHint, _client: Client): Event {
+ const scope = getCurrentScope();
+ const flagContext = scope.getScopeData().contexts.flags;
+ const flagBuffer = flagContext ? flagContext.values : [];
+
+ if (event.contexts === undefined) {
+ event.contexts = {};
+ }
+ event.contexts.flags = { values: [...flagBuffer] };
+ return event;
+ },
+ };
+}) satisfies IntegrationFn;
+
+/**
+ * LaunchDarkly hook that listens for flag evaluations and updates the `flags`
+ * context in our Sentry scope. This needs to be registered as an
+ * 'inspector' in LaunchDarkly initialize() options, separately from
+ * `launchDarklyIntegration`. Both are needed to collect feature flags on error.
+ */
+export function buildLaunchDarklyFlagUsedHandler(): LDInspectionFlagUsedHandler {
+ return {
+ name: 'sentry-flag-auditor',
+ type: 'flag-used',
+
+ synchronous: true,
+
+ /**
+ * Handle a flag evaluation by storing its name and value on the current scope.
+ */
+ method: (flagKey: string, flagDetail: LDEvaluationDetail, _context: LDContext) => {
+ if (typeof flagDetail.value === 'boolean') {
+ const scopeContexts = getCurrentScope().getScopeData().contexts;
+ if (!scopeContexts.flags) {
+ scopeContexts.flags = { values: [] };
+ }
+ const flagBuffer = scopeContexts.flags.values;
+ insertToFlagBuffer(flagBuffer, flagKey, flagDetail.value);
+ }
+ return;
+ },
+ };
+}
diff --git a/packages/browser/src/integrations/featureFlags/launchdarkly/types.ts b/packages/browser/src/integrations/featureFlags/launchdarkly/types.ts
new file mode 100644
index 000000000000..55a388109e60
--- /dev/null
+++ b/packages/browser/src/integrations/featureFlags/launchdarkly/types.ts
@@ -0,0 +1,50 @@
+/**
+ * Inline definitions of LaunchDarkly types so we don't have to include their
+ * SDK in devDependencies. These are only for type-checking and can be extended
+ * as needed - for exact definitions, reference `launchdarkly-js-client-sdk`.
+ */
+
+/**
+ * Currently, the Sentry integration does not read from values of this type.
+ */
+export type LDContext = object;
+
+/**
+ * An object that combines the result of a feature flag evaluation with information about
+ * how it was calculated.
+ */
+export interface LDEvaluationDetail {
+ value: unknown;
+ // unused optional props: variationIndex and reason
+}
+
+/**
+ * Callback interface for collecting information about the SDK at runtime.
+ *
+ * This interface is used to collect information about flag usage.
+ *
+ * This interface should not be used by the application to access flags for the purpose of controlling application
+ * flow. It is intended for monitoring, analytics, or debugging purposes.
+ */
+export interface LDInspectionFlagUsedHandler {
+ type: 'flag-used';
+
+ /**
+ * Name of the inspector. Will be used for logging issues with the inspector.
+ */
+ name: string;
+
+ /**
+ * If `true`, then the inspector will be ran synchronously with evaluation.
+ * Synchronous inspectors execute inline with evaluation and care should be taken to ensure
+ * they have minimal performance overhead.
+ */
+ synchronous?: boolean;
+
+ /**
+ * This method is called when a flag is accessed via a variation method, or it can be called based on actions in
+ * wrapper SDKs which have different methods of tracking when a flag was accessed. It is not called when a call is made
+ * to allFlags.
+ */
+ method: (flagKey: string, flagDetail: LDEvaluationDetail, context: LDContext) => void;
+}
diff --git a/packages/browser/src/utils/featureFlags.ts b/packages/browser/src/utils/featureFlags.ts
new file mode 100644
index 000000000000..caddd68bc31e
--- /dev/null
+++ b/packages/browser/src/utils/featureFlags.ts
@@ -0,0 +1,59 @@
+import { logger } from '@sentry/core';
+import type { FeatureFlag } from '@sentry/types';
+import { DEBUG_BUILD } from '../debug-build';
+
+/**
+ * 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;
+
+/**
+ * Insert into a FeatureFlag array while maintaining ordered LRU properties. Not
+ * thread-safe. After inserting:
+ * - `flags` is sorted in order of recency, with the newest flag at the end.
+ * - No other flags with the same name exist in `flags`.
+ * - The length of `flags` does not exceed `maxSize`. The oldest flag is evicted
+ * as needed.
+ *
+ * @param flags The array to insert 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. It's recommended
+ * to keep this consistent across insertions. Default is DEFAULT_MAX_SIZE
+ */
+export function insertToFlagBuffer(
+ flags: FeatureFlag[],
+ name: string,
+ value: boolean,
+ maxSize: number = FLAG_BUFFER_SIZE,
+): void {
+ 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 at capacity, pop the earliest flag - O(n)
+ flags.shift();
+ }
+
+ // Push the flag to the end - O(1)
+ flags.push({
+ flag: name,
+ result: value,
+ });
+}
diff --git a/packages/browser/test/utils/featureFlags.test.ts b/packages/browser/test/utils/featureFlags.test.ts
new file mode 100644
index 000000000000..ef4ca7f4611f
--- /dev/null
+++ b/packages/browser/test/utils/featureFlags.test.ts
@@ -0,0 +1,82 @@
+import type { FeatureFlag } from '@sentry/types';
+import { logger } from '@sentry/utils';
+import { vi } from 'vitest';
+import { insertToFlagBuffer } from '../../src/utils/featureFlags';
+
+describe('flags', () => {
+ 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('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('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 },
+ ]);
+ });
+ });
+});
diff --git a/packages/core/src/scope.ts b/packages/core/src/scope.ts
index e03f378cac20..9ca6411eac35 100644
--- a/packages/core/src/scope.ts
+++ b/packages/core/src/scope.ts
@@ -127,6 +127,14 @@ class ScopeClass implements ScopeInterface {
newScope._tags = { ...this._tags };
newScope._extra = { ...this._extra };
newScope._contexts = { ...this._contexts };
+ if (this._contexts.flags) {
+ // We need to copy the `values` array so insertions on a cloned scope
+ // won't affect the original array.
+ newScope._contexts.flags = {
+ values: [...this._contexts.flags.values],
+ };
+ }
+
newScope._user = this._user;
newScope._level = this._level;
newScope._session = this._session;
diff --git a/packages/core/src/utils/prepareEvent.ts b/packages/core/src/utils/prepareEvent.ts
index bf23a0e3ee79..d4a2cc1f877e 100644
--- a/packages/core/src/utils/prepareEvent.ts
+++ b/packages/core/src/utils/prepareEvent.ts
@@ -303,6 +303,14 @@ function normalizeEvent(event: Event | null, depth: number, maxBreadth: number):
});
}
+ // event.contexts.flags (FeatureFlagContext) stores context for our feature
+ // flag integrations. It has a greater nesting depth than our other typed
+ // Contexts, so we re-normalize with a fixed depth of 3 here. We do not want
+ // to skip this in case of conflicting, user-provided context.
+ if (event.contexts && event.contexts.flags && normalized.contexts) {
+ normalized.contexts.flags = normalize(event.contexts.flags, 3, maxBreadth);
+ }
+
return normalized;
}
diff --git a/packages/types/src/context.ts b/packages/types/src/context.ts
index 10fc61420e25..718e36fe8f26 100644
--- a/packages/types/src/context.ts
+++ b/packages/types/src/context.ts
@@ -1,3 +1,4 @@
+import type { FeatureFlag } from './featureFlags';
import type { Primitive } from './misc';
import type { SpanOrigin } from './span';
@@ -13,6 +14,7 @@ export interface Contexts extends Record {
cloud_resource?: CloudResourceContext;
state?: StateContext;
profile?: ProfileContext;
+ flags?: FeatureFlagContext;
}
export interface StateContext extends Record {
@@ -124,3 +126,12 @@ export interface MissingInstrumentationContext extends Record {
package: string;
['javascript.is_cjs']?: boolean;
}
+
+/**
+ * Used to buffer flag evaluation data on the current scope and attach it to
+ * error events. `values` should be initialized as empty ([]), and it should
+ * only be modified by @sentry/util "FlagBuffer" functions.
+ */
+export interface FeatureFlagContext extends Record {
+ values: FeatureFlag[];
+}
diff --git a/packages/types/src/featureFlags.ts b/packages/types/src/featureFlags.ts
new file mode 100644
index 000000000000..c117fbd0d686
--- /dev/null
+++ b/packages/types/src/featureFlags.ts
@@ -0,0 +1,2 @@
+// Key names match the type used by Sentry frontend.
+export type FeatureFlag = { readonly flag: string; readonly result: boolean };
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 5dd1839aeba7..7d2adbcbaf2d 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -56,6 +56,7 @@ export type { Event, EventHint, EventType, ErrorEvent, TransactionEvent } from '
export type { EventProcessor } from './eventprocessor';
export type { Exception } from './exception';
export type { Extra, Extras } from './extra';
+export type { FeatureFlag } from './featureFlags';
// eslint-disable-next-line deprecation/deprecation
export type { Hub } from './hub';
export type { Integration, IntegrationClass, IntegrationFn } from './integration';