diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index 8c74613882c..85a1d06ab61 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -6047,6 +6047,46 @@ menu: parent: feature_flags identifier: feature_flags_server weight: 2 + - name: Concepts + url: feature_flags/concepts + parent: feature_flags + identifier: feature_flags_concepts + weight: 3 + - name: Environments + url: feature_flags/concepts/environments + parent: feature_flags_concepts + identifier: feature_flags_concepts_environments + weight: 301 + - name: Variants and Flag Types + url: feature_flags/concepts/variants_and_flag_types + parent: feature_flags_concepts + identifier: feature_flags_concepts_variants + weight: 302 + - name: Targeting Rules and Filters + url: feature_flags/concepts/targeting_rules + parent: feature_flags_concepts + identifier: feature_flags_concepts_targeting_rules + weight: 303 + - name: Traffic Splitting and Randomization + url: feature_flags/concepts/traffic_splitting + parent: feature_flags_concepts + identifier: feature_flags_concepts_traffic_splitting + weight: 304 + - name: Distribution Channels + url: feature_flags/concepts/distribution_channels + parent: feature_flags_concepts + identifier: feature_flags_concepts_distribution_channels + weight: 305 + - name: Flag History + url: feature_flags/concepts/flag_history + parent: feature_flags_concepts + identifier: feature_flags_history + weight: 306 + - name: MCP Server + url: feature_flags/concepts/feature_flag_mcp_server + parent: feature_flags_concepts + identifier: feature_flags_mcp_server + weight: 307 - name: .NET url: feature_flags/server/dotnet parent: feature_flags_server @@ -6077,16 +6117,6 @@ menu: parent: feature_flags_server identifier: feature_flags_server_ruby weight: 206 - - name: Flag History - url: feature_flags/history - parent: feature_flags - identifier: feature_flags_history - weight: 6 - - name: MCP Server - url: feature_flags/feature_flag_mcp_server - parent: feature_flags - identifier: feature_flags_mcp_server - weight: 8 - name: Guides url: feature_flags/guide parent: feature_flags diff --git a/content/en/feature_flags/_index.md b/content/en/feature_flags/_index.md index cae0159b609..fb047251f04 100644 --- a/content/en/feature_flags/_index.md +++ b/content/en/feature_flags/_index.md @@ -11,6 +11,9 @@ further_reading: - link: "/getting_started/feature_flags/" tag: "Documentation" text: "Getting started with Feature Flags" +- link: "/feature_flags/concepts/" + tag: "Documentation" + text: "Learn the core concepts of Feature Flags" - link: "/feature_flags/client/" tag: "Documentation" text: "Set up Feature Flags for client-side applications" diff --git a/content/en/feature_flags/client/_index.md b/content/en/feature_flags/client/_index.md index 222a36bd8f4..c9008b5a602 100644 --- a/content/en/feature_flags/client/_index.md +++ b/content/en/feature_flags/client/_index.md @@ -28,7 +28,7 @@ Datadog supports these testing approaches: - **Integration tests**: Point `DatadogProvider` at a dedicated test environment and control flag values from the Datadog UI. This exercises the real provider end-to-end, including the CDN-delivered flag assignments. - **Unit tests**: Swap `DatadogProvider` for OpenFeature's standard `InMemoryProvider` (or an equivalent test stub, where no in-memory provider is available in the language) and set flag values directly in test code. This keeps tests hermetic and offline. -This section covers the in-memory approach. Because the OpenFeature API is designed to make providers swappable at runtime, your application code does not change — only the provider registered during test setup. +This section covers the in-memory approach. Because the OpenFeature API is designed to make providers swappable at runtime, your application code does not change — only the provider registered during test setup. A typical test follows this pattern: @@ -71,4 +71,6 @@ const evaluationContext = { ## Further reading +For percentage-based rollouts and deterministic bucketing, see [Traffic Splitting and Randomization](/feature_flags/concepts/traffic_splitting/). + {{< partial name="whats-next/whats-next.html" >}} diff --git a/content/en/feature_flags/concepts/_index.md b/content/en/feature_flags/concepts/_index.md new file mode 100644 index 00000000000..83ea746106c --- /dev/null +++ b/content/en/feature_flags/concepts/_index.md @@ -0,0 +1,16 @@ +--- +title: Concepts +description: Learn the core concepts and fundamentals of Datadog Feature Flags. +--- + +Learn how Datadog Feature Flags work and how to configure flags, environments, targeting, and governance. + +{{< whatsnext desc=" " >}} + {{< nextlink href="/feature_flags/concepts/environments" >}}Environments{{< /nextlink >}} + {{< nextlink href="/feature_flags/concepts/variants_and_flag_types" >}}Variants and Flag Types{{< /nextlink >}} + {{< nextlink href="/feature_flags/concepts/targeting_rules" >}}Targeting Rules and Filters{{< /nextlink >}} + {{< nextlink href="/feature_flags/concepts/traffic_splitting" >}}Traffic Splitting and Randomization{{< /nextlink >}} + {{< nextlink href="/feature_flags/concepts/distribution_channels" >}}Distribution Channels{{< /nextlink >}} + {{< nextlink href="/feature_flags/concepts/flag_history" >}}Flag History{{< /nextlink >}} + {{< nextlink href="/feature_flags/concepts/feature_flag_mcp_server" >}}Feature Flags MCP Server{{< /nextlink >}} +{{< /whatsnext >}} diff --git a/content/en/feature_flags/concepts/distribution_channels.md b/content/en/feature_flags/concepts/distribution_channels.md new file mode 100644 index 00000000000..6a4d9a1a531 --- /dev/null +++ b/content/en/feature_flags/concepts/distribution_channels.md @@ -0,0 +1,46 @@ +--- +title: Distribution Channels +description: Control which SDKs receive your feature flag configuration with distribution channels. +further_reading: +- link: "/feature_flags/concepts/variants_and_flag_types" + tag: "Documentation" + text: "Variants and Flag Types" +- link: "/feature_flags/client/" + tag: "Documentation" + text: "Client-Side SDKs" +- link: "/feature_flags/server/" + tag: "Documentation" + text: "Server-Side SDKs" +--- + +## Overview + +Distribution channels control which SDKs receive your flag configuration. When you create or edit a flag, you can set distribution channels to **Client**, **Server**, or both. + +## Why use distribution channels + +Use distribution channels to protect sensitive configuration and reduce payload size. + +### Protect sensitive configuration + +Client-side SDKs fetch flag configuration over the network. Flag keys and variant values sent to client SDKs can be visible in API requests. Restrict server-only flags to the **Server** distribution channel to avoid exposing sensitive flag keys or variant values to client SDKs. + +### Reduce payload size + +If you work with a large number of feature flags, limiting which flags each SDK type receives can reduce the size of the configuration payload. This can improve performance for client and server SDK initialization. + +## Configure distribution channels + +When you [create a feature flag][1], select which distribution channels should receive the flag: + +- **Client**: Client-side SDKs only (browser and mobile) +- **Server**: Server-side SDKs only +- **Both**: All SDK types + +You can also update distribution channels on an existing flag from the **Manage Implementation & Variants** section of the flag details page. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://app.datadoghq.com/feature-flags/create diff --git a/content/en/feature_flags/concepts/environments.md b/content/en/feature_flags/concepts/environments.md new file mode 100644 index 00000000000..b985c9260b3 --- /dev/null +++ b/content/en/feature_flags/concepts/environments.md @@ -0,0 +1,103 @@ +--- +title: Environments +description: Learn how Datadog Feature Flags environments isolate flag configuration across deployment stages. +further_reading: +- link: "/getting_started/feature_flags/" + tag: "Documentation" + text: "Getting Started with Feature Flags" +- link: "/feature_flags/concepts/variants_and_flag_types" + tag: "Documentation" + text: "Variants and Flag Types" +- link: "/feature_flags/concepts/targeting_rules" + tag: "Documentation" + text: "Targeting Rules and Filters" +--- + +## Overview + +Environments represent different deployment stages or modes in your software delivery life cycle, such as Development, Staging, and Production. Flag configuration is isolated by environment. A flag can be enabled, disabled, overridden, or given targeting rules in one environment without affecting other environments. + +## Manage environments + +Manage environments from **Feature Flags > Settings > Environments**: + +{{< img src="getting_started/feature_flags/environments-list.png" alt="Environments list in Feature Flags settings." style="width:100%;" >}} + +### Add an environment + +1. Navigate to [**Feature Flags > Settings > Environments**][1]. +2. Click **Create Environment**. +3. Configure the environment name, queries, and whether it is a production environment. + +### Edit an environment + +1. Navigate to [**Feature Flags > Settings > Environments**][1]. +2. Click the environment you want to edit. +3. Update the environment settings and save. + +### Delete an environment + +1. Navigate to [**Feature Flags > Settings > Environments**][1]. +2. Hover over the environment you want to delete, then click the trash icon. + +## Default environments + +By default, Datadog creates three environments for your organization: + +- **Development** +- **Staging** +- **Production** + +You can modify these environments or add new ones to match how your team ships code. + +## Production environments + +Mark an environment as **production** to indicate that changes in that environment can affect customers. Production environments support additional governance controls, such as required change approvals. + +## Environment queries + +Each environment is configured with a **name** and a set of **queries**. Queries are the `env` or `DD_ENV` strings your applications send at runtime. + +Having multiple queries per environment lets you keep the `env` value consistent with the environment you pass to RUM, APM, or StatsD. For example, you might have `staging-eu` and `staging-us` as separate `env` values in your telemetry, but map both to a single **Staging** environment in Feature Flags. That way, you do not need to duplicate flag configuration across multiple Staging environments when you want to enable a flag across all of Staging. + +## Connect environments in the SDK + +The `env` value you use must match a query configured for the Feature Flags environment you want, such as `staging-us` or `production`. If you already set `env` or `DD_ENV` for RUM, APM, or tracing, use the **same value** for Feature Flags. + +### Client-side applications + +Set `env` when you initialize the Datadog OpenFeature provider (same value as RUM): + +```javascript +import { DatadogProvider } from '@datadog/openfeature-browser'; +import { OpenFeature } from '@openfeature/web-sdk'; + +const provider = new DatadogProvider({ + clientToken: '', + applicationId: '', + site: 'datadoghq.com', + env: 'staging-us', // Must match an environment query in Feature Flags + service: '', + version: '1.0.0', +}); + +await OpenFeature.setProviderAndWait(provider); +``` + +### Server-side applications + +Set `DD_ENV` in your deployment environment (shell, container, or orchestrator), not in application code: + +{{< code-block lang="bash" >}} +export DD_ENV=staging-us # Must match an environment query in Feature Flags +export DD_SERVICE= +export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +{{< /code-block >}} + +This applies to Python, Go, Java, Node.js, Ruby, and .NET server SDKs. See [Server-Side Feature Flags](/feature_flags/server/) for language-specific setup. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://app.datadoghq.com/feature-flags/settings/environments diff --git a/content/en/feature_flags/feature_flag_mcp_server.md b/content/en/feature_flags/concepts/feature_flag_mcp_server.md similarity index 98% rename from content/en/feature_flags/feature_flag_mcp_server.md rename to content/en/feature_flags/concepts/feature_flag_mcp_server.md index e21464a82bf..07ac393bb6d 100644 --- a/content/en/feature_flags/feature_flag_mcp_server.md +++ b/content/en/feature_flags/concepts/feature_flag_mcp_server.md @@ -1,6 +1,8 @@ --- title: Feature Flags MCP Server description: "Learn how to use the Feature Flags toolset in the Datadog MCP Server" +aliases: + - /feature_flags/feature_flag_mcp_server further_reading: - link: "getting_started/feature_flags" tag: "Documentation" diff --git a/content/en/feature_flags/history.md b/content/en/feature_flags/concepts/flag_history.md similarity index 98% rename from content/en/feature_flags/history.md rename to content/en/feature_flags/concepts/flag_history.md index 5eaf7fc2fb6..25b2afe3619 100644 --- a/content/en/feature_flags/history.md +++ b/content/en/feature_flags/concepts/flag_history.md @@ -1,6 +1,8 @@ --- title: Feature Flag History description: "Track and manage the history of your feature flags" +aliases: + - /feature_flags/history further_reading: - link: "/getting_started/feature_flags/" tag: "Documentation" diff --git a/content/en/feature_flags/concepts/targeting_rules.md b/content/en/feature_flags/concepts/targeting_rules.md new file mode 100644 index 00000000000..743ac952d1c --- /dev/null +++ b/content/en/feature_flags/concepts/targeting_rules.md @@ -0,0 +1,142 @@ +--- +title: Targeting Rules and Filters +description: Learn how targeting rules, filters, and rollout types control which variants your application serves. +further_reading: +- link: "/feature_flags/concepts/traffic_splitting" + tag: "Documentation" + text: "Traffic Splitting and Randomization" +- link: "/feature_flags/concepts/environments" + tag: "Documentation" + text: "Environments" +- link: "/feature_flags/client/" + tag: "Documentation" + text: "Client-Side SDKs" +--- + +## Overview + +**Targeting rules** define which variant to serve to which subjects. Each rule can include a **filter**, one or more variants, and an optional percentage rollout. Rules are evaluated in order until a match is found. + +## Targeting rule types + +Datadog supports different targeting rule types depending on your rollout strategy: + +| Type | Description | +|------|-------------| +| **Feature gate** | Roll out immediately to a percentage of subjects matching your filter (randomized or not) | +| **Progressive rollout** | Randomized rollout over a schedule with multiple steps. See [Progressive Rollouts & Canaries](/feature_flags/use_cases/progressive_rollouts/) | +| **Experiment** | Randomized allocation associated with an experiment | + +## Configure targeting rules + +To configure targeting rules for a flag: + +1. Navigate to **Feature Flags** and select your flag. +2. Select the environment whose rules you want to modify. +3. Click **Add Targeting Rule** (or click the targeting rule you want to modify). + +{{< img src="getting_started/feature_flags/ff-targeting-rules-and-rollouts.png" alt="Targeting Rules and Rollouts section on a feature flag." style="width:100%;" >}} + +For each targeting rule, configure the following: + +- **Name your targeting rule**: Give your targeting rule a name to describe the group it targets. +- **Define a filter** (optional): If you do not define a filter, the rule matches all subjects in that environment. +- **Select variants**: Choose which variants to serve to matching subjects. Click **Split Traffic** to randomize across multiple variants (see [Traffic Splitting and Randomization](/feature_flags/concepts/traffic_splitting/)). +- **Set the traffic exposure** (optional): Serve the variant to a percentage of matching subjects (see [Traffic Splitting and Randomization](/feature_flags/concepts/traffic_splitting/)). + +{{< img src="getting_started/feature_flags/configure-targeting-rule.png" alt="Targeting Rule editor side panel on a feature flag." style="width:100%;" >}} + +After configuring your targeting rules, click **Save Changes**, then enable the flag in the environment so SDKs can evaluate targeting rules. + +
+SDKs do not evaluate targeting rules when the flag is disabled or overridden in the given environment. If the flag is overridden with a fixed variant, the SDK returns that variant instead. If the flag is disabled, the SDK returns the coded default variant. +
+ +## Filters and evaluation context + +Filters use attributes from your SDK's **evaluation context**. Define attributes when you set the evaluation context before evaluating flags. Attributes must be flat primitive values (strings, numbers, booleans). Nested objects and arrays are not supported. + +### Example evaluation contexts and filters + +Given the following evaluation context, you can build filters with different operators, such as equality, **is one of**, **is not**, or numeric comparisons: + +**Evaluation context:** + +{{< programming-lang-wrapper langs="javascript,python,go" >}} + +{{< programming-lang lang="javascript" >}} + +```javascript +await OpenFeature.setContext({ + targetingKey: 'user-123', + user_id: 'user-123', + user_role: 'admin', + email: 'user@example.com', + country: 'US', + tier: 'premium', + account_age_days: 120, +}); +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="python" >}} + +```python +from openfeature.evaluation_context import EvaluationContext + +eval_ctx = EvaluationContext( + targeting_key="user-123", + attributes={ + "user_id": "user-123", + "user_role": "admin", + "email": "user@example.com", + "country": "US", + "tier": "premium", + "account_age_days": 120, + }, +) +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="go" >}} + +```go +evalCtx := openfeature.NewEvaluationContext( + "user-123", + map[string]interface{}{ + "user_id": "user-123", + "user_role": "admin", + "email": "user@example.com", + "country": "US", + "tier": "premium", + "account_age_days": 120, + }, +) +``` + +{{< /programming-lang >}} + +{{< /programming-lang-wrapper >}} + +#### Example filters + +- `country` **is one of** `US`, `CA` +- `tier` **equals** `premium` +- `user_role` **is not** `guest` +- `account_age_days` **greater than** `90` + +**Note**: Other SDKs follow the same pattern. See your platform's [client](/feature_flags/client/) or [server](/feature_flags/server/) SDK documentation for evaluation context setup. + +## Rule hierarchy + +Targeting rules are evaluated **in order** from top to bottom: + +1. The SDK evaluates the first rule. If the subject matches the filter (or no filter is defined), the rule may serve a variant. +2. If the subject does not match, evaluation passes through to the next rule. +3. If no rule matches, the SDK serves the **default variant** for that environment. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} diff --git a/content/en/feature_flags/concepts/traffic_splitting.md b/content/en/feature_flags/concepts/traffic_splitting.md new file mode 100644 index 00000000000..6abab3a3fa2 --- /dev/null +++ b/content/en/feature_flags/concepts/traffic_splitting.md @@ -0,0 +1,76 @@ +--- +title: Traffic Splitting and Randomization +description: Learn how Datadog Feature Flags use deterministic randomization for percentage-based rollouts. +further_reading: +- link: "/feature_flags/concepts/targeting_rules" + tag: "Documentation" + text: "Targeting Rules and Filters" +- link: "/feature_flags/use_cases/progressive_rollouts" + tag: "Documentation" + text: "Progressive Rollouts and Canaries" +--- + +## Overview + +When you define a targeting rule, you can serve a variant to a percentage of subjects that match your targeting filter. Datadog uses **deterministic randomization** based on the `targetingKey` in your evaluation context so the same subject consistently receives the same variant for a given flag. + +## Percentage rollouts + +In the **Targeting Rules & Rollouts** section, set the percentage of the audience that should receive each variant. For a **single-variant** targeting rule, assign your desired traffic exposure to one variant. For example, roll the **Free Shipping** variant of your promo banner to 50% of subjects matching your filter: + +{{< img src="getting_started/feature_flags/single-variant-traffic-exposure.png" alt="Targeting rule with a single-variant percentage rollout." style="width:100%;" >}} + +For a **multi-variant** rollout, assign percentages across multiple variants in the same targeting rule by selecting **Serve > Split Traffic** when editing or creating your targeting rule. The SDK distributes matching subjects across those variants according to the percentages you configure. + +{{< img src="getting_started/feature_flags/multi-variant-traffic-split.png" alt="Targeting rule with percentages split across multiple variants." style="width:100%;" >}} + +## How the SDK evaluates percentage rollouts + +When the SDK evaluates a targeting rule with a percentage rollout, it first checks whether the evaluation context matches the rule's filter. If it matches, the SDK uses the flag key and the `targetingKey` from the evaluation context to assign the subject to a rollout bucket. That bucket determines whether the subject receives a variant from the current rule or passes through to the next rule. + +Randomization is **deterministic**: a subject with the same `targetingKey` always lands in the same bucket for a given flag, so they receive the same variant on repeat evaluations. If you increase a rollout percentage later (for example, from 30% to 50%), subjects already in the treatment bucket stay there. + +For multi-variant rules, the SDK applies the same bucketing logic to distribute subjects across variants according to the percentages defined on the rule. + +### Example evaluation context + +{{< programming-lang-wrapper langs="javascript,python,go" >}} + +{{< programming-lang lang="javascript" >}} + +```javascript +await OpenFeature.setContext({ + targetingKey: 'user-123', + user_id: 'user-123', +}); +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="python" >}} + +```python +eval_ctx = EvaluationContext( + targeting_key="user-123", + attributes={"user_id": "user-123"}, +) +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="go" >}} + +```go +evalCtx := openfeature.NewEvaluationContext( + "user-123", + map[string]interface{}{"user_id": "user-123"}, +) +``` + +{{< /programming-lang >}} + +{{< /programming-lang-wrapper >}} + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} diff --git a/content/en/feature_flags/concepts/variants_and_flag_types.md b/content/en/feature_flags/concepts/variants_and_flag_types.md new file mode 100644 index 00000000000..71a2898b5f1 --- /dev/null +++ b/content/en/feature_flags/concepts/variants_and_flag_types.md @@ -0,0 +1,53 @@ +--- +title: Variants and Flag Types +description: Learn about feature flag data types and how to manage flag variants in Datadog. +further_reading: +- link: "/feature_flags/concepts/environments" + tag: "Documentation" + text: "Environments" +- link: "/feature_flags/concepts/distribution_channels" + tag: "Documentation" + text: "Distribution Channels" +--- + +## Overview + +Each feature flag has a **variant type** that defines the data type of values the flag can return. **Variants** are the specific values your application can receive when it evaluates the flag. + +## Flag types + +Datadog Feature Flags support five data types: + +| Type | Description | +|------|-------------| +| **Boolean** | `true` or `false` | +| **String** | Text values | +| **Integer** | Whole numbers | +| **Number** | Floating-point numbers | +| **JSON** | Structured JSON objects | + +**Note**: The flag key and variant type cannot be changed after you create the flag. + +## Add a variant + +1. Navigate to your feature flag's details page. +2. Open the **Manage Implementation & Variants** side panel. +3. Click **Add Variant**. +4. Enter the variant name and value, then save. + +**Note**: You cannot add variants to Boolean flags. Boolean flags are limited to `true` and `false`. + +## Edit a variant + +1. Navigate to your feature flag's details page. +2. Open the **Manage Implementation & Variants** side panel. +3. Click the pencil icon next to the variant you want to modify. +4. Update the variant's name, value, or both, then save. + +
+Changing the value of a variant that is being served as part of a running experiment may invalidate the results of that experiment. +
+ +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} diff --git a/content/en/feature_flags/server/_index.md b/content/en/feature_flags/server/_index.md index 153bf658403..98a9c4cfd28 100644 --- a/content/en/feature_flags/server/_index.md +++ b/content/en/feature_flags/server/_index.md @@ -119,6 +119,8 @@ const evaluationContext = { ## Further reading +For percentage-based rollouts and deterministic bucketing, see [Traffic Splitting and Randomization](/feature_flags/concepts/traffic_splitting/). + {{< partial name="whats-next/whats-next.html" >}} [1]: /remote_configuration diff --git a/content/en/getting_started/feature_flags/_index.md b/content/en/getting_started/feature_flags/_index.md index 61553c2278a..dc7528274d0 100644 --- a/content/en/getting_started/feature_flags/_index.md +++ b/content/en/getting_started/feature_flags/_index.md @@ -49,9 +49,7 @@ This guide uses the JavaScript browser SDK as an example. You can integrate Data ## Configure your environments -Your organization likely already has pre-configured environments for Development, Staging, and Production. If you need to configure these or any other environments, navigate to the [**Environments**][3] page to create tag queries for each environment. You can also identify which environment should be considered a Production environment. - -{{< img src="getting_started/feature_flags/environments-list.png" alt="Environments list" style="width:100%;" >}} +Your organization likely already has pre-configured environments for Development, Staging, and Production. For details on environment queries, production marking, and managing environments, see [Environments][4]. ## Create your first feature flag @@ -86,19 +84,15 @@ await OpenFeature.setProviderAndWait(provider);
Setting enableExposureLogging to true can impact RUM costs, as it sends exposure events to Datadog through RUM. You can disable it if you don't need to track feature exposure or guardrail metric status.
-More information about OpenFeature SDK configuration options can be found in its [documentation][1]. For more information on creating client tokens and application IDs, see [API and Application Keys][4]. +More information about OpenFeature SDK configuration options can be found in its [documentation][1]. For more information on creating client tokens and application IDs, see [API and Application Keys][3]. ### Step 2: Create a feature flag Go to [**Create Feature Flag**][2] in Datadog and configure the following: - **Name and key**: The flag's display name and the key referenced in code -- **Variant type**: The data type for the flag variants (Boolean, string, integer, number, or JSON) - - **Note**: The flag key and variant type cannot be modified after creation. - -- **Variant values**: The possible values the flag can return (you can add these later) -- **Distribution channels**: Which types of SDKs receive this flag's configuration (client-side, server-side, or both) +- **Variant type** and **variant values**: See [Variants and Flag Types][5] +- **Distribution channels**: See [Distribution Channels][6]
Flag keys, variant keys, and variant values should be considered public when sent to client SDKs. @@ -138,27 +132,15 @@ After you've completed this step, redeploy the application to pick up these chan ### Step 4: Define targeting rules and enable the feature flag -Now that the application is ready to check the value of your flag, you can start adding targeting rules. Targeting rules enable you to define where or to whom to serve different variants of your feature. - -Go to **Feature Flags**, select your flag, select the environment whose rules you want to modify, and click **Edit Targeting Rules**. - -{{< img src="getting_started/feature_flags/ff-targeting-rules-and-rollouts.png" alt="Targeting Rules & Rollouts" style="width:100%;" >}} - -### Step 5: Publish the rules in your environments - -After saving changes to the targeting rules, publish those rules by enabling your flag in the environment of your choice. +Configure [targeting rules][7] to define which subjects receive each variant. After saving your rules, enable the flag in your chosen environment.
-As a general best practice, changes should be rolled out in a Staging environment before rolling out in Production. +As a general best practice, roll out changes in a Staging environment before Production.
-Toggle your selected environment to **Enabled**. - -{{< img src="getting_started/feature_flags/publish-targeting-rules.png" alt="Publish targeting rules" style="width:100%;" >}} - -The flag serves your targeting rules in this environment. You can continue to edit these targeting rules to control where the variants are served. +For percentage rollouts, see [Traffic Splitting and Randomization][8]. -### Step 6: Monitor your rollout +### Step 5: Monitor your rollout Monitor the feature rollout from the feature flag details page, which provides real-time exposure tracking and metrics such as **error rate** and **page load time**. As you incrementally release the feature with the flag, view the **Real-Time Metric Overview** panel in the Datadog UI to see how the feature impacts application performance. @@ -170,5 +152,9 @@ Monitor the feature rollout from the feature flag details page, which provides r [1]: https://openfeature.dev/docs/reference/technologies/client/web/ [2]: https://app.datadoghq.com/feature-flags/create -[3]: https://app.datadoghq.com/feature-flags/settings/environments -[4]: https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens +[3]: https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens +[4]: /feature_flags/concepts/environments/ +[5]: /feature_flags/concepts/variants_and_flag_types/ +[6]: /feature_flags/concepts/distribution_channels/ +[7]: /feature_flags/concepts/targeting_rules/ +[8]: /feature_flags/concepts/traffic_splitting/ diff --git a/static/images/getting_started/feature_flags/configure-targeting-rule.png b/static/images/getting_started/feature_flags/configure-targeting-rule.png new file mode 100644 index 00000000000..3f552f077da Binary files /dev/null and b/static/images/getting_started/feature_flags/configure-targeting-rule.png differ diff --git a/static/images/getting_started/feature_flags/ff-targeting-rules-and-rollouts.png b/static/images/getting_started/feature_flags/ff-targeting-rules-and-rollouts.png index 8382471fd6c..f90a8d8f298 100644 Binary files a/static/images/getting_started/feature_flags/ff-targeting-rules-and-rollouts.png and b/static/images/getting_started/feature_flags/ff-targeting-rules-and-rollouts.png differ diff --git a/static/images/getting_started/feature_flags/multi-variant-traffic-split.png b/static/images/getting_started/feature_flags/multi-variant-traffic-split.png new file mode 100644 index 00000000000..68d53dea772 Binary files /dev/null and b/static/images/getting_started/feature_flags/multi-variant-traffic-split.png differ diff --git a/static/images/getting_started/feature_flags/single-variant-traffic-exposure.png b/static/images/getting_started/feature_flags/single-variant-traffic-exposure.png new file mode 100644 index 00000000000..f48bae2b44a Binary files /dev/null and b/static/images/getting_started/feature_flags/single-variant-traffic-exposure.png differ