---
title: "Feature Flags"
description: "Guidelines for tracking feature flag evaluations — scope storage, span attributes, the add_feature_flag API, and third-party integrations."
url: https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags/
---

# Feature Flags

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in

<!-- -->

[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.

Statusstable

Version`1.0.0`[(changelog)](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#changelog)

## [Overview](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#overview)

An SDK may optionally track feature flag evaluations. Feature flags can be attached to error events or to span events.

***

## [Behavior](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#behavior)

### [Tracking Feature Flag Evaluations](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#tracking-feature-flag-evaluations)

Stablespecified since

<!-- -->

1.0.0

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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts.md#feature-flag-context) protocol documentation.

### [The `add_feature_flag` API](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#the-add_feature_flag-api)

Stablespecified since

<!-- -->

1.0.0

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](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#integrations)

Stablespecified since

<!-- -->

1.0.0

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.

***

## [Changelog](https://develop.sentry.dev/sdk/foundations/client/integrations/feature-flags.md#changelog)

| Version | Date       | Summary                                        |
| ------- | ---------- | ---------------------------------------------- |
| `1.0.0` | 2025-02-24 | Initial spec, extracted from expected features |