Skip to content

feat(flags): track feature flag evaluations in span attributes #16475

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

feat(flags): track feature flag evaluations in span attributes #16475

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3a547a3
Span class updates
aliu39 Jun 3, 2025
dff89ff
Use in browser util and integrations
aliu39 Jun 3, 2025
710945c
Disable max lines in sentrySpan
aliu39 Jun 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/browser/src/integrations/featureFlags/featureFlagsIntegration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { Client, Event, EventHint, Integration, IntegrationFn } from '@sentry/core';
import { defineIntegration } from '@sentry/core';
import { copyFlagsFromScopeToEvent, insertFlagToScope } from '../../utils/featureFlags';
import { addFlagToActiveSpan, copyFlagsFromScopeToEvent, insertFlagToScope } from '../../utils/featureFlags';

export interface FeatureFlagsIntegration extends Integration {
addFeatureFlag: (name: string, value: unknown) => void;
Expand Down Expand Up @@ -41,6 +41,7 @@ export const featureFlagsIntegration = defineIntegration(() => {

addFeatureFlag(name: string, value: unknown): void {
insertFlagToScope(name, value);
addFlagToActiveSpan(name, value);
},
};
}) as IntegrationFn<FeatureFlagsIntegration>;
3 changes: 2 additions & 1 deletion packages/browser/src/integrations/featureFlags/launchdarkly/integration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { Client, Event, EventHint, IntegrationFn } from '@sentry/core';
import { defineIntegration } from '@sentry/core';
import { copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import { addFlagToActiveSpan, copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import type { LDContext, LDEvaluationDetail, LDInspectionFlagUsedHandler } from './types';

/**
Expand Down Expand Up @@ -46,6 +46,7 @@ export function buildLaunchDarklyFlagUsedHandler(): LDInspectionFlagUsedHandler
*/
method: (flagKey: string, flagDetail: LDEvaluationDetail, _context: LDContext) => {
insertFlagToScope(flagKey, flagDetail.value);
addFlagToActiveSpan(flagKey, flagDetail.value);
},
};
}
4 changes: 3 additions & 1 deletion packages/browser/src/integrations/featureFlags/openfeature/integration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
*/
import type { Client, Event, EventHint, IntegrationFn } from '@sentry/core';
import { defineIntegration } from '@sentry/core';
import { copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import { addFlagToActiveSpan, copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import type { EvaluationDetails, HookContext, HookHints, JsonValue, OpenFeatureHook } from './types';

export const openFeatureIntegration = defineIntegration(() => {
Expand All @@ -29,12 +29,14 @@ export class OpenFeatureIntegrationHook implements OpenFeatureHook {
*/
public after(_hookContext: Readonly<HookContext<JsonValue>>, evaluationDetails: EvaluationDetails<JsonValue>): void {
insertFlagToScope(evaluationDetails.flagKey, evaluationDetails.value);
addFlagToActiveSpan(evaluationDetails.flagKey, evaluationDetails.value);
}

/**
* On error evaluation result.
*/
public error(hookContext: Readonly<HookContext<JsonValue>>, _error: unknown, _hookHints?: HookHints): void {
insertFlagToScope(hookContext.flagKey, hookContext.defaultValue);
addFlagToActiveSpan(hookContext.flagKey, hookContext.defaultValue);
}
}
3 changes: 2 additions & 1 deletion packages/browser/src/integrations/featureFlags/statsig/integration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { Client, Event, EventHint, IntegrationFn } from '@sentry/core';
import { defineIntegration } from '@sentry/core';
import { copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import { addFlagToActiveSpan, copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import type { FeatureGate, StatsigClient } from './types';

/**
Expand Down Expand Up @@ -38,6 +38,7 @@ export const statsigIntegration = defineIntegration(
setup() {
statsigClient.on('gate_evaluation', (event: { gate: FeatureGate }) => {
insertFlagToScope(event.gate.name, event.gate.value);
addFlagToActiveSpan(event.gate.name, event.gate.value);
});
},
};
Expand Down
3 changes: 2 additions & 1 deletion packages/browser/src/integrations/featureFlags/unleash/integration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import type { Client, Event, EventHint, IntegrationFn } from '@sentry/core';
import { defineIntegration, fill, logger } from '@sentry/core';
import { DEBUG_BUILD } from '../../../debug-build';
import { copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import { addFlagToActiveSpan, copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
import type { UnleashClient, UnleashClientClass } from './types';

type UnleashIntegrationOptions = {
Expand Down Expand Up @@ -65,6 +65,7 @@ function _wrappedIsEnabled(

if (typeof toggleName === 'string' && typeof result === 'boolean') {
insertFlagToScope(toggleName, result);
addFlagToActiveSpan(toggleName, result);
} else if (DEBUG_BUILD) {
logger.error(
`[Feature Flags] UnleashClient.isEnabled does not match expected signature. arg0: ${toggleName} (${typeof toggleName}), result: ${result} (${typeof result})`,
Expand Down
14 changes: 13 additions & 1 deletion packages/browser/src/utils/featureFlags.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import type { Event, FeatureFlag } from '@sentry/core';
import { getCurrentScope, logger } from '@sentry/core';
import { getActiveSpan, getCurrentScope, logger } from '@sentry/core';
import { DEBUG_BUILD } from '../debug-build';

/**
Expand Down Expand Up @@ -87,3 +87,15 @@ export function insertToFlagBuffer(flags: FeatureFlag[], name: string, value: un
result: value,
});
}

/**
* Add a feature flag evaluation to the active span. Currently a no-op for non-boolean values.
* @param name
* @param value
*/
export function addFlagToActiveSpan(name: string, value: unknown): void {
if (typeof value !== 'boolean') {
return;
}
getActiveSpan()?.addFeatureFlag(name, value);
}
5 changes: 5 additions & 0 deletions packages/core/src/tracing/sentryNonRecordingSpan.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,11 @@ export class SentryNonRecordingSpan implements Span {
return this;
}

/** @inheritDoc */
public addFeatureFlag(_name: string, _value: boolean): this {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding a new method onto a span breaks our compatibility with OTEL, which we leverage for duck typing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This strategy makes sense, but how can we track the num current flags? (currently a protected field on the span)

Copy link
Member Author

@aliu39 aliu39 Jun 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it expected that this will be used by users? Like they will call span.addFeatureFlag?

I'm thinking we can expose this as an API for users, following the pattern we have for adding flags to scope in featureFlagIntegration. It'd be the same as the addFeatureFlag method, without the need for an integration

return this;
}

/**
* This should generally not be used,
* but we need it for being compliant with the OTEL Span interface.
Expand Down
17 changes: 17 additions & 0 deletions packages/core/src/tracing/sentrySpan.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
/* eslint-disable max-lines */
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

304 lines after changes


import { getClient, getCurrentScope } from '../currentScopes';
import { DEBUG_BUILD } from '../debug-build';
import { createSpanEnvelope } from '../envelope';
Expand Down Expand Up @@ -45,6 +47,8 @@ import { timedEventsToMeasurements } from './measurement';
import { getCapturedScopesOnSpan } from './utils';

const MAX_SPAN_COUNT = 1000;
const MAX_FEATURE_FLAGS_PER_SPAN = 10; // The maximum number of feature flag evaluations that can be recorded in span attributes.
const FEATURE_FLAG_ATTRIBUTE_PREFIX = 'sentry.flag.evaluation.';
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since users can call setAttribute, can be user defined I thought it best to prefix with sentry. See SpanAttributes defn


/**
* Span contains all data about a span
Expand All @@ -57,6 +61,7 @@ export class SentrySpan implements Span {
protected _name?: string | undefined;
protected _attributes: SpanAttributes;
protected _links?: SpanLink[];
protected _numFeatureFlags: number;
/** Epoch timestamp in seconds when the span started. */
protected _startTime: number;
/** Epoch timestamp in seconds when the span ended. */
Expand All @@ -81,6 +86,7 @@ export class SentrySpan implements Span {
this._spanId = spanContext.spanId || generateSpanId();
this._startTime = spanContext.startTimestamp || timestampInSeconds();
this._links = spanContext.links;
this._numFeatureFlags = 0;

this._attributes = {};
this.setAttributes({
Expand Down Expand Up @@ -132,6 +138,17 @@ export class SentrySpan implements Span {
return this;
}

/** @inheritDoc */
public addFeatureFlag(name: string, value: boolean): this {
if (!(name in this._attributes)) {
if (this._numFeatureFlags >= MAX_FEATURE_FLAGS_PER_SPAN) {
return this;
}
Comment on lines +144 to +146
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be a buffer so that we can evict the least recently added flags (similar to what we do w/ breadcrumbs)? Silently ignoring the flag here feels not great.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's what we do on in python atm, cc @cmanallen. We could have a buffer but need to make sure the attribute is serializable - Doesn't look like SpanAttributeValue allows nested objects. Maybe we could store a buffer of keys internally

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For spans the oldest flag evaluations are the most important because they're likely to have the largest performance impact. We drop late arrivals due to request size concerns.

this._numFeatureFlags++;
}
return this.setAttribute(`${FEATURE_FLAG_ATTRIBUTE_PREFIX}${name}`, value);
}

/**
* This should generally not be used,
* but it is needed for being compliant with the OTEL Span interface.
Expand Down
7 changes: 7 additions & 0 deletions packages/core/src/types-hoist/span.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,13 @@ export interface Span {
*/
addLinks(links: SpanLink[]): this;

/**
* Adds a feature flag evaluation to the span.
* @param name - The name of the feature flag.
* @param value - The value of the feature flag.
*/
addFeatureFlag(name: string, value: boolean): this;

/**
* NOT USED IN SENTRY, only added for compliance with OTEL Span interface
*/
Expand Down
Loading