A feature flag (also known as a split) allows you to choose between different code paths in your system at runtime. Feature flags are an integral part of continuous delivery allowing you to decouple deployment from release. They also enable teams to safely merge new features, bug fixes, or other code changes to one central branch in the version control system, which avoids long-lived feature branches and merge issues by integrating code changes frequently.
Note: For additional information about feature flags, refer to Feature flag best practices. It explains how to implement feature-flagged software successfully, and offers tips on how to configure and manage a growing set of feature flags within your product, maintain them over time, manage infrastructure migrations, etc.
Creating a feature flag
When you create your feature flag, you can specify information for it, which includes a name, a description, owners, and tags. This information helps you and your team manage your feature flags and customize them to your team's workflow. To create a feature flag, do the following:
- Navigate to the left navigation and click Splits. The Splits page displays.
- Click Create Split to create a new feature flag.
- Enter the following information for your new feature flag. This information can help you and your team manage your splits and customize them to your team's workflow.
- Name your feature flag: Enter a name your team can recognize. Feature flag names must start with a letter and can contain the characters - _ a-z A-Z 0-9 and cannot be named “datetime”, “string”, “set”, or “integer”, because those are reserved words.
- Select the traffic type: Select the traffic type you want to use this split for. A traffic type indicates the type of key you use to split your traffic, for example, user, account, store, etc. Refer to Using traffic types section later in this guide.
Note: Once a feature flag is created with specific traffic types, you cannot change the traffic type or name. This is done by design so the experiment data is not mixed from different traffic types, which could contaminate the results. To use a different traffic type, create a new feature flag with the desired traffic type.
- Add owners. By default, a user creating a feature flag is an owner, along with the Admin group. You can add one or more users or groups as owners for your feature flag. Use owners to organize a feature flag to those "owned by me" for filtering and notification purposes, and to grant edit permissions in environments that restrict who can edit.
- Add tags: Optionally add one or more tags to categorize a feature flag or associate it with a particular team, feature release, area of your product, or other internal structure. Tags are useful for filtering lists and rollout boards. Be aware that tags are case sensitive.
- Describe your feature flag: Optionally provide a description of a feature flag. The description explains the it’s purpose and what functionality is controlled. If it’s being used for an experiment, use this to provide information about the goal.
- Click Create to create your feature flag. Your new flag displays.
- To configure your feature flag for a particular environment, from the Environment field, select the desired environment you want it added to and click the Add Rules button.
From here, you can now create a rollout plan. This is also known as targeting rules. Refer to the Create a rollout plan guide for next steps in setting up your feature flag.
Note: When you set up an account, two environments are automatically created. If you want to create additional environments, refer to the Environments guide for more information.
Deleting a feature flag
To delete a feature flag, you first need to delete all targeting rules for that flag within all environments. To delete a feature flag, do the following:
- Select the feature flag you want to delete.
- Access the desired environment and click the (...) icon next to the KILL button and click Delete targeting rules. The Delete rules page appears.
- Type DELETE in the warning page field and then, in the Add approvers fields, optionally start typing users or groups.
Note: If you don’t add approvers, the feature flag is deleted immediately.
- Click the Delete button. If you haven’t selected approvers, the targeting rules are deleted.
- Repeat the same action for all environments that the feature flag is added to.
- Once you delete definitions, delete the feature flag by using the (...) icon in the upper right of the screen.
Using the kill switch
If a feature flag negatively impacts performance or your user’s experience, you can kill it without changing targeting rules or performing a redeployment. When you kill a feature, all traffic is sent to the default treatment selected for that feature flag. To kill a feature flag, do the following:
- From the left navigation, click Splits. The Splits view appears.
- Select the desired split and click Kill on the page. The Kill split warning page opens.
- Type KILL in the warning page field.
- Optionally add a title, comment, or approver.
- Click the Kill button. The feature flag is now killed.
Using traffic types
When you create a feature flag, you must specify a traffic type. Use traffic types to identify the type of key you are using to split traffic. A traffic type is a particular identifier type for any hierarchy of your customer base. Traffic types in Split are customizable and can be any key you choose to send to Split, e.g., a user ID, account ID, device, persistent cookie, etc. The traffic type denotes the nature of the keys that is passed to getTreatment for that split.
You can customize traffic types in Split to your particular use cases. You must have a traffic type for each type of key you plan to pass to getTreatment. The most commonly used traffic types are:
- user. The key uniquely identifies a known, logged-in user. To protect personally identifiable information (PII), never use email address or login name here. Instead, consider using either a numeric identifier that is the primary key in the table you use to store user information, or a hash of that primary key.
- anonymous. The key is a randomly generated identifier, like a uuid, that identifies a visitor using a particular mobile device or browser, where it is typically stored as a cookie.
- account. The key identifies the customer account to which the (logged-in) user belongs. This traffic type is often used to maintain consistency of behavior for all visitors from a given company or account.
Creating traffic types
You can create traffic types as needed at any time, but it is a best practice to do so during your initial account setup, taking into account your anticipated needs. Once you create a split with a given traffic type, that traffic type cannot be changed, so it is important to get it right the first time.
Note: Only administrators can create traffic types.
Split allows you to have up to ten traffic types per workspace. All environments within a workspace share the same set of traffic types. By default, a workspace has one traffic type named user when you first sign up for your account You can customize your traffic types as needed during your setup.
To add your traffic types, do the following:
- From the left navigation, click at the top left and select Admin settings.
- On Workspaces, select the workspace that you want to edit traffic types for.
- To add additional traffic types to a particular workspace, click View.
- Click the Actions button and then Add Traffic type. The Create traffic type page appears.
- Enter a name for the traffic type and click Save.
Note: Once a traffic type is created it cannot be edited.
- To delete a traffic type, in the Actions column, click the Delete link. You can only delete a traffic type if it is no longer used by any feature flags or metric definitions.
If you need assistance with traffic types, contact firstname.lastname@example.org.
Other traffic types
It is also possible for a traffic type to identify something other than a visitor. For instance, a realty site might use “listing” as a traffic type if they wanted to explore the possibility of having a single visitor see different appearances for different property listings. For that traffic type, the code would pass to getTreatment the id of the listing being displayed.
Another example of a less common but useful traffic type is “pair,” which represents a unique match of two users engaged in a dialog.
Use tags to organize and manage feature flags, segments, and metrics across the Split web interface. Tags can filter the display to focus on a particular team, feature release, portion of your app, or other organizational unit you use. We recommend creating tags that are specific to your workflow, for example:
- By team: Identify the responsible team using tags such as front end, infrastructure, web, or mobile.
- By feature release: Identify all of the splits associated with a particular release using tags such as reporting, new permissioning, or contact database migration.
- By feature flag type: Identify all the feature flags associated with paywalls or those that are permanent versus temporary, using tags such as paywall, permanent, or temporary.
Notes: Be aware that:
- Tag names of tags are case sensitive.
- Tags are shared across workspaces, so avoid giving them sensitive names you don't want all users in all workspaces to see.
Adding or removing tags
To add a tag to a feature flag, do the following:
- Select the feature flag you want to tag.
- Click the edit pencil next to the tags (below the name and description).
- In the text box, begin typing to select an existing tag from the menu or create a new tag.
- Click Apply. The new tag is added.
To remove a tag from a feature flag, do the following:
- Select the feature flag you want to tag.
- Click the edit pencil next to the tags (below the name and description). The list of tags displays.
- Hover over the tag you want to remove and click the x on the right.
- Click Apply. The selected tag is removed.
Filtering by tags
Filtering by tags allows you to focus on just the items associated with a particular tag. Filter your tags on the Split overview page by doing the following:
- From the left navigation, select Splits.
- Click Filter and hover over Tag.
- Use the menu to select as many tags as you want to filter by.
Feature flag naming conventions and organization
When you create a feature flag, name it with something consistent. Your approach should be specific to your organization.
Note: This also applies to segments and metrics. In addition, with metrics, you should be more descriptive in order to explain what the metric is intended to measure.
Feature flag naming conventions
Use a common taxonomy, for example:
Feature flag: project_feature
It’s best to follow conventions you already have, such as lower case only, camel case, or snake case. A best practice is that underscores and camelCase are easier to select in code by double-clicking than dashes, which act as boundaries. Note that you cannot use periods, spaces, or special characters other than - and _, and while you can use 0-9 in the name, you can’t start the flag name with a number).
Reviewing feature flag assignments
The customer dashboard provides feature flag (split), segment, and attribute information on a particular key. This dashboard can be navigated to by clicking on a unique key when viewing impression data in Live tail or by typing the unique key in the search bar on the left navigation.
- Splits. The Splits tab shows the treatments that are served to that key for each feature flag in your workspace, based on individual targeting, membership in a segment or randomized position in a percentage rollout. Because attributes passed to our SDK remain private to your application and are never sent to Split, feature flags which use attributes for targeting don’t show an expected treatment.
- Segments. The Segments tab shows the segments that a particular key belongs to. For more information about creating segments, refer to the Create a segment guide.
- Attributes. The Attributes tab shows the customer's attribute data which is populated from the attribute data you send using the user interface or Split's API. When you add an attribute either using the user interface or an API, be sure to create or overwrite a key <link> for a given traffic type and environment. If you don’t, your values display as null.
Now that you've completed your first feature flag, you can set up your rollout plan.
Additional essential guides
The following are guides that walk you through additional capabilities of our Split application:
Refer to our Foundational concepts guide for more information about foundational concepts of the Split application..
Refer to our Setting up and using metrics guide to learn more about creating and using metrics in the Split application.