Feature Flags
Guidelines for tracking feature flag evaluations — scope storage, span attributes, the add_feature_flag API, and third-party integrations.
An SDK may optionally track feature flag evaluations. Feature flags can be attached to error events or to span events.
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.
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 Feature Flag Context 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 of type boolean. Non-boolean values MUST be rejected.
SDKs MAY expose a clear_feature_flags function on the scope. When called, it MUST remove all feature flag evaluations stored on the current scope. It MUST NOT affect feature flags on parent or sibling scopes.
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.
| Version | Date | Summary |
|---|---|---|
1.0.2 | 2026-07-07 | Added `clear_feature_flags` scope API |
1.0.1 | 2026-06-05 | Fixed `add_feature_flag` API specifying unsupported feature flag value types |
1.0.0 | 2025-02-24 | Initial spec, extracted from expected features |
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").