Add feature flags on spans documentation (#13551)

<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->

## DESCRIBE YOUR PR
*Tell us what you're changing and why. If your PR **resolves an issue**,
please link it so it closes automatically.*

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

## LEGAL BOILERPLATE

<!-- Sentry employees and contractors can delete or ignore this section.
-->

Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.

## EXTRA RESOURCES

- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)

Author: cmanallen

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
 

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
 

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
 

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
 

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