Add feature flags on spans documentation

cmanallen · cmanallen · commit 35b338f62cb5 · 2025-04-29T10:16:53.000-05:00
diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx
@@ -118,11 +118,13 @@ This functionality should be gated behind the `includeLocalVariables` option, wh
 
 ## Feature Flags
 
-An SDK may optionally support feature flag collection. Feature flags are collected on evaluation, stored on the scope, and submitted to Sentry on error obeying the schema specified in the <Link to="/sdk/data-model/event-payloads/contexts/#feature-flag-context">Feature Flag Context</Link> protocol documentation.
+An SDK may optionally track feature flag evaluations. Feature flags can be attached to error events or to span events.
 
-If an SDK supports feature flags it must expose a function `addFeatureFlag` which has similar behavior to the `set_tag` function. It must accept a key of type string and a value which is a union of string, boolean, integer, float, and structure. An SDK may hold up to 100 evaluations (similar to the breadcrumb implementation). Evaluations are ordered based on their evaluation time. Typically, an LRU cache is used to store feature flags. When the capacity of the cache is exceeded the oldest flag is dropped. Any (or multiple) data structure(s) may be chosen by the SDK to store feature flags as long as the evaluation order of the flags is maintained.
+When tracking feature flag evaluations on spans, we track the first 10 feature flags evaluated within the span's scope.  Evaluations are span attributes and follow the existing span attribute schema.
 
-Because flags are stored on the scope, when a scope forks the flags data structure must be cloned. Failure to clone the data structure appropriately will lead to flags leaking across thread boundaries and lead to unexpected results.
+When tracking on error feature flag evaluations, we record the 100 most recent, unique feature flag evaluations.  Evaluations are stored on the scope. When the scope forks a copy of the collected feature flag evaluations are given to the child scope.  Mutations to the child's copy of the feature flags object should not be propagated to the parent.  Flag evaluations within a scope are considered local to the scope and do not propagate.  Evaluations should be submitted to Sentry following the schema specified in the <Link to="/sdk/data-model/event-payloads/contexts/#feature-flag-context">Feature Flag Context</Link> protocol documentation.
+
+If an SDK supports feature flags it must expose a function `add_feature_flag` which has similar behavior to the `set_tag` function. It must accept a key of type string and a value which is a union of string, boolean, integer, float, and structure.
 
 ### Integrations
 
diff --git a/docs/platforms/javascript/common/configuration/integrations/launchdarkly.mdx b/docs/platforms/javascript/common/configuration/integrations/launchdarkly.mdx
@@ -30,7 +30,7 @@ This integration only works inside a browser environment. It is only available f
 
 </Alert>
 
-The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory, and in the event an error occurs, sent to Sentry for review and analysis. **At the moment, we only support boolean flag evaluations.** This integration is available in
+The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations.** This integration is available in
 Sentry SDK **versions 8.43.0 or higher.**
 
 _Import names: `Sentry.launchDarklyIntegration` and `Sentry.buildLaunchDarklyFlagUsedHandler`_
diff --git a/docs/platforms/javascript/common/configuration/integrations/openfeature.mdx b/docs/platforms/javascript/common/configuration/integrations/openfeature.mdx
@@ -31,7 +31,7 @@ This integration only works inside a browser environment. It is only available f
 
 </Alert>
 
-The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory, and in the event an error occurs, sent to Sentry for review and analysis. **At the moment, we only support boolean flag evaluations.** This integration is available in
+The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations.** This integration is available in
 Sentry SDK **versions 8.43.0 or higher.**
 
 _Import name: `Sentry.openFeatureIntegration` and `Sentry.OpenFeatureIntegrationHook`_
diff --git a/docs/platforms/javascript/common/configuration/integrations/statsig.mdx b/docs/platforms/javascript/common/configuration/integrations/statsig.mdx
@@ -29,7 +29,7 @@ This integration only works inside a browser environment. It is only available f
 
 </Alert>
 
-The [Statsig](https://www.statsig.com/) integration tracks feature flag evaluations produced by the Statsig JavaScript Client SDK. These evaluations are held in memory, and in the event an error occurs, sent to Sentry for review and analysis. **At the moment, we only support boolean flag evaluations from Statsig's `checkGate` method**. Learn more about [Statsig feature gates](https://docs.statsig.com/feature-flags/working-with/).
+The [Statsig](https://www.statsig.com/) integration tracks feature flag evaluations produced by the Statsig JavaScript Client SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations from Statsig's `checkGate` method**. Learn more about [Statsig feature gates](https://docs.statsig.com/feature-flags/working-with/).
 
 This integration is available in Sentry SDK **versions 9.0.0 and higher**, or **versions 8.55.0 and higher for v8.**
 
diff --git a/docs/platforms/javascript/common/configuration/integrations/unleash.mdx b/docs/platforms/javascript/common/configuration/integrations/unleash.mdx
@@ -30,7 +30,7 @@ This integration only works inside a browser environment. It is only available f
 
 </Alert>
 
-The [Unleash](https://www.getunleash.io/) integration tracks feature flag evaluations produced by the Unleash SDK. These evaluations are held in memory, and in the event an error occurs, sent to Sentry for review and analysis. **At the moment, we only support boolean flag evaluations from Unleash's isEnabled method.** This integration is available in Sentry SDK **versions 8.51.0 or higher.**
+The [Unleash](https://www.getunleash.io/) integration tracks feature flag evaluations produced by the Unleash SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations from Unleash's isEnabled method.** This integration is available in Sentry SDK **versions 8.51.0 or higher.**
 
 _Import names: `Sentry.unleashIntegration`_
 
diff --git a/docs/platforms/python/integrations/launchdarkly/index.mdx b/docs/platforms/python/integrations/launchdarkly/index.mdx
@@ -5,7 +5,7 @@ description: "Learn how to use Sentry with LaunchDarkly."
 
 <PlatformContent includePath="feature-flags/prerelease-alert" />
 
-The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory and sent to Sentry for review and analysis if an error occurs. **At the moment, we only support boolean flag evaluations.**
+The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations.**
 
 ## Install
 
diff --git a/docs/platforms/python/integrations/openfeature/index.mdx b/docs/platforms/python/integrations/openfeature/index.mdx
@@ -5,7 +5,7 @@ description: "Learn how to use Sentry with OpenFeature."
 
 <PlatformContent includePath="feature-flags/prerelease-alert" />
 
-The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory and sent to Sentry for review and analysis if an error occurs. **At the moment, we only support boolean flag evaluations.**
+The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations.**
 
 ## Install
 
diff --git a/docs/platforms/python/integrations/statsig/index.mdx b/docs/platforms/python/integrations/statsig/index.mdx
@@ -5,7 +5,7 @@ description: "Learn how to use Sentry with Statsig."
 
 <PlatformContent includePath="feature-flags/prerelease-alert" />
 
-The [Statsig](https://www.statsig.com/) integration tracks feature flag evaluations produced by the Statsig Python Server SDK. These evaluations are held in memory and sent to Sentry for review and analysis if an error occurs. **At the moment, we only support boolean flag evaluations from Statsig's `check_gate` function.** Learn more about [Statsig feature gates](https://docs.statsig.com/feature-flags/working-with/).
+The [Statsig](https://www.statsig.com/) integration tracks feature flag evaluations produced by the Statsig Python Server SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations from Statsig's `check_gate` function.** Learn more about [Statsig feature gates](https://docs.statsig.com/feature-flags/working-with/).
 
 ## Install
 
diff --git a/docs/platforms/python/integrations/unleash/index.mdx b/docs/platforms/python/integrations/unleash/index.mdx
@@ -5,7 +5,7 @@ description: "Learn how to use Sentry with Unleash."
 
 <PlatformContent includePath="feature-flags/prerelease-alert" />
 
-The [Unleash](https://www.getunleash.io/) integration tracks feature flag evaluations produced by the Unleash SDK. These evaluations are held in memory and sent to Sentry for review and analysis if an error occurs. **At the moment, we only support boolean flag evaluations from Unleash's is_enabled method.**
+The [Unleash](https://www.getunleash.io/) integration tracks feature flag evaluations produced by the Unleash SDK. These evaluations are held in memory and are sent to Sentry on error and trace events. **At the moment, we only support boolean flag evaluations from Unleash's is_enabled method.**
 
 ## Install
 
