Flagpole

Flagpole is Sentry's internal, options-backed feature flagging library.

Features are defined in the sentry-options-automator repository as yaml objects within the options/defaults/flagpole.yml file. These yaml options are pushed to each of our deployments and stored in a database table, where they are later queried and parsed during feature flag evaluation.

Here's the example configuration for a feature named organizations:is_sentry, which is enabled for an organization with the slug sentry.

options:
  "feature.organizations:is_sentry":
    created_at: "2024-06-01T00:00:00.000000"
    enabled: false
    owner: hybrid-cloud
    segments:
      - conditions:
          - operator: in
            value:
              - sentry
            property: organization_slug
        name: is_sentry
        rollout: 100

Flagpole Feature Yaml Structure

created_at

The ISO 8601 datetime of when the feature was added to the config yaml.

owner

The team name or email of the user that owns this feature flag

enabled [optional]

The global toggle for the feature flag. Defaults to True. Setting this to False can be a break-glass safety valve to disable a feature without having to modify existing segments or conditions.

segments

A wrapper around a list of conditions, acting as a logical grouping of customers/entities to enable the feature flag for. Segments allow you to create OR operations with other segments, meaning at least one segment must evaluate to True for a feature to be granted. If an empty segments list is provided, the feature will evaluate to False.

Segments

conditions

A list of predicates to evaluate for the feature flag to be enabled for this segment. All conditions in a segment must be evaluate to True in order for the segment to be enabled. If no conditions are defined, the segment will evaluate to False.

name

A brief description of the segment identifying its intended purpose.

rollout [optional]

A percentage of entities to enable the feature for, defined as an integer between 0 - 100. Defaults to 100.

Conditions

property

The property name of the evaluation context entry to match against.

value

The expected value to compare against the evaluation context's property value, using the provided operator.

operator

The comparison strategy to apply between the evaluation context's property value and the provided condition value.

Operators

Flagpole currently supports the following operator types:

in

Given a list of values, evaluates to True if the context property value exists in the list.

not_in

The inverse of in, evaluates to True if the context property value does not exist in the provided list.

contains

Given a single int, string, float, or boolean value, evalutes to True if the context property value is a list containing the provided value.

not_contains

The inverse of contains, evalutes to True if the context property value is a list which does not contain the provided value.

equals

Given a single int, string, float, or boolean value, evaluates to True if the context property value exactly matches the provided value.

not_equals

The inverse of equals, evaluates to True if the context property value does not match the provided value.

Evaluation Contexts

When a feature flag is checked, the caller must provide one or more entity objects for the feature handler to match against. These objects are used to construct an EvaluationContext, which is essentially a flat dictionary of keys and primitive values. This context is passed to each feature, which provides this context to each segment and condition to enforce whether the feature should be enabled.

Context Builders

Each evaluation context is built up in stages via a ContextBuilder object.

Each context builder consists of a list of context transformers, which are responsible for creating individual slices of the larger evaluation context.

Here are some common properties we surface via our Sentry and GetSentry context builders that you can use in your conditions:

System Context Properties

sentry_region [str]

The sentry region or single-tenant the flag check is being perfomed in.

sentry_singletenant [bool]

Whether or not the application is operating in a single-tenant environment.

Organization Context Properties

organization_id [int]

The organization's ID

organization_slug [str]

The organization's slug

organization_name [str]

The organization's name

organization_is-early-adopter [bool]

Whether or not the organization has the early_adopter flag enabled

Project Context Properties (If checking a project feature)

project_id [int]

The project's ID

project_slug [str]

The project's slug

User Context Properties (If checking a flag with an actor)

user_id [int]

The active user's ID

user_email [str]

The active user's email address. This should only contain Sentry employee email addresses.

To see the latest context properties available, check out the repo-specific context builders:

• Sentry Context Builder
• GetSentry Context Builder

Rolling out a new Flagpole feature

Creating a new Flagpole Feature is currently a 2 step process:

1. Register a new feature in Sentry's temporary.py file or GetSentry's features.py file with the Flagpole strategy:

features.add(
    "<feature_scope>:<feature_name>",
    OrganizationFeature,
    FeatureHandlerStrategy.FLAGPOLE
)

2. Add a new feature object entry to sentry-options-automator's flagpole.yml file. The feature's option name must follow the following format in order to be picked up by Flagpole:

feature.<feature_scope>:<feature_name>

Once the option change is deployed, the feature checks will immediately be active in all environments and regions.

Using Flagpole in single-tenants

To allow your flagpole feature configuration to be used in single-tenant environments, you'll need to add your feature name to the flagpole.allowed_features list for each tenant. For example, in options/regions/acme.yml add the following:

options:
  flagpole.allowed_features: ["organizations:is_sentry"]

You can also use the sentry_singletenant and sentry_region context values in your feature conditions as required.

Testing a Flagpole feature locally

You can test a flagpole feature flag locally using the GetSentry devserver. Because the feature handler for Flagpole only exists in GetSentry, it's not possible to test flagpole features using the Sentry devserver at this time.

Start by creating a new yaml file containing your feature config:

options:
  "feature.organizations:is_sentry":
    created_at: "2024-06-01T00:00:00.000000"
    enabled: false
    owner: hybrid-cloud
    segments:
      - conditions:
          - operator: in
            value:
              - sentry
            property: organization_slug
        name: is_sentry
        rollout: 100

You can push your feature option to your local devserver using the following getsentry configoptions CLI command:

getsentry configoptions -f <path>/<to>/<your>/<config>.yml -l DEBUG patch

If this command runs successfully, your flagpole feature should now be active in your local devserver instance and will persist across runs until you remove the feature option.

To unset your feature, comment out or remove your feature config from the option object, and rerun the getsentry configoptions command above.

Removing Flagpole features

Because our options automator CI relies on the feature definitions in both Sentry and GetSentry, flags must be removed in a specific order to avoid causing test failures:

1. Remove all flag checks from the codebase and set a default value of True for the flag.
2. Once all flag checks have been removed and the changes have been deployed to all environments, remove the feature flag config from options automator.
3. Remove the feature registration from GetSentry or Sentry.