flags: Add improved developer documentation (#12643)

* Add improved developer documentation

* Remove mention of cap

* Add period

Author: cmanallen

develop-docs/sdk/expected-features/data-handling.mdx

@@ -111,6 +111,8 @@ Fields in the event payload that allow user-specified or dynamic values are rest
 
 - Mappings of values (such as HTTP data, extra data, etc) are limited to 50 item pairs.
 - Event IDs are limited to 36 characters and must be valid UUIDs.
+- Flag keys are limited to 32 characters.
+- Flag values are limited to 200 characters.
 - Tag keys are limited to 32 characters.
 - Tag values are limited to 200 characters.
 - Culprits are limited to 200 characters.

develop-docs/sdk/expected-features/index.mdx

@@ -30,7 +30,7 @@ What scope means depends on the application, for a web framework it is most like
 
 ## Automatic Context Data
 
-Automatic addition of useful attributes such as `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/expected-features/data-handling) for considerations.
+Automatic addition of useful attributes such as `flags` or `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/expected-features/data-handling) for considerations.
 
 ## Breadcrumbs
 
@@ -118,24 +118,15 @@ This functionality should be gated behind the `includeLocalVariables` option, wh
 
 ## Feature Flags
 
-An SDK may expose a Scope property for tracking feature flag evaluations. When the scope forks, it's important to clone the feature flags property. Leaking flag evaluations between threads could lead to inaccurate feature flag evaluation logs.
+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.
 
-The Scope's flag property should have a capped capacity and should prefer recently-evaluated flags over less-recently-evaluated flags. The recommended data structure is a LRU-cache but it is not required so long as the data structure behaves similarly. Serious deviations from the behavior of an LRU-cache should be documented for your language.
+If an SDK supports feature flags it must expose a function `set_flag` which has identical 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. 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.
 
-The Scope's flag property should expose two methods: `get/0` and `set/2`. `set/2` takes two arguments. The first argument is the name of the flag. It is of type string. The second argument is the evaluation result. It is of type boolean. `set/2` should remove all entries from the LRU-cache which match the provided flag's name and append the new evaluation result to the end of the queue. `get/0` accepts zero arguments. The `get/0` method must return a list of serialized flag evaluation results in order of evaluation. Oldest values first, newest values last. See the <Link to="/sdk/data-model/event-payloads/contexts/#feature-flag-context">Feature Flag Context</Link> protocol documentation for details.
+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.
 
 ### Integrations
 
-Integrations automate the work of tracking feature flag evaluations and serializing them on error context. An integration should hook into third-party SDK and record feature flag evaluations using the current scope. For example, in Python an integration would call `sentry_sdk.get_current_scope().flags.set(...)` on each flag evaluation.
-
-An integration is also responsible for registering an "on error" hook with the Sentry SDK. When an error occurs the integration should request the current scope and serialize the flags property. For example, in Python an integration might define this callback function:
-
-```python
-def flag_error_processor(event, exc_info):
-    scope = sentry_sdk.get_current_scope()
-    event["contexts"]["flags"] = {"values": scope.flags.get()}
-    return event
-```
+Integrations automate the work of tracking feature flag evaluations. An integration should hook into a third-party SDK and record feature flag evaluations using the current scope.
 
 ## Desymbolication
 

develop-docs/sdk/miscellaneous/hub_and_scope_refactoring.mdx

@@ -78,7 +78,7 @@ This scope is probably only used for process-wide data like the `release`.
 
 **Isolation Scope**
 
-This scope holds data only applicable to the current request (on a server), tab (in a browser), or user (on a mobile). The top-level APIs that manipulate data (like `sentry_sdk.set_tag()`, `sentry_sdk.set_context()` etc) write to the isolation scope (at least once the migration phase is over, see "Backwards Compatibility").
+This scope holds data only applicable to the current request (on a server), tab (in a browser), or user (on a mobile). The top-level APIs that manipulate data (like `sentry_sdk.set_flag()`, `sentry_sdk.set_tag()`, `sentry_sdk.set_context()` etc.) write to the isolation scope (at least once the migration phase is over, see "Backwards Compatibility").
 
 The isolation scope is stored in a context variable, thread local, async local, or something similar (depending on the platform). It may also be stored on OTel `Context` so we can rely on OTels `Context` propagation once SDKs implement POTEL.
 

develop-docs/sdk/miscellaneous/unified-api/index.mdx

@@ -216,6 +216,8 @@ Sentry.configureScope((scope) =>
 
 - `scope.set_extras(extras)`: Sets an object with key/value pairs, convenience function instead of multiple `set_extra` calls. As with `set_extra` this is considered deprecated functionality.
 
+- `scope.set_flag(key, value)`: Sets the flag to a string value, overwriting a potential previous value. Entries can not be removed except by expiration.
+
 - `scope.set_tag(key, value)`: Sets the tag to a string value, overwriting a potential previous value. Removing a key is SDK-defined, either with a `remove_tag` function or by passing nothing as data.
 
 - `scope.set_tags(tags)`: Sets an object with key/value pairs, convenience function instead of multiple `set_tag` calls.