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.

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 3 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>

3. Add the feature name to the flagpole.flagpole_only_features list in sentry-options-automator's default app.yaml file, omitting the feature. prefix.

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

Note: The feature config should not be merged until the registration commit in step 1 has been fully deployed to all target environments. This is because Options Automator will fail to push options to any environments missing the option registration.

If this happens, make sure to rerun the options deployment once all environments have been updated to ensure your feature is active.

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. The config file should contain a top-level options object containing your feature object, and a flagpole.flagpole_only_features list option containing the name of the feature you want to test, without the feature. prefix:

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

  "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

Note: The flagpole_only_features option will only be required while Flagpole is actively being rolled out.

You can push your feature option to your local devserver using the following getsentry 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.