diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index ef229ea31b3..e20c85d5c57 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -6152,6 +6152,26 @@ menu: parent: feature_flags_server identifier: feature_flags_server_ruby weight: 206 + - name: Use Cases + url: feature_flags/use_cases + parent: feature_flags + identifier: feature_flags_use_cases + weight: 3 + - name: Progressive Rollouts and Canaries + url: feature_flags/use_cases/progressive_rollouts + parent: feature_flags_use_cases + identifier: feature_flags_use_cases_progressive_rollouts + weight: 401 + - name: Kill Switches + url: feature_flags/use_cases/kill_switches + parent: feature_flags_use_cases + identifier: feature_flags_use_cases_kill_switches + weight: 402 + - name: Dynamic Configuration + url: feature_flags/use_cases/dynamic_configuration + parent: feature_flags_use_cases + identifier: feature_flags_use_cases_dynamic_configuration + weight: 403 - name: Flag History url: feature_flags/history parent: feature_flags diff --git a/content/en/feature_flags/_index.md b/content/en/feature_flags/_index.md index cae0159b609..aad952b6b46 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/use_cases/" + tag: "Documentation" + text: "Feature Flags Use Cases" - link: "/feature_flags/client/" tag: "Documentation" text: "Set up Feature Flags for client-side applications" diff --git a/content/en/feature_flags/use_cases/_index.md b/content/en/feature_flags/use_cases/_index.md new file mode 100644 index 00000000000..7fdb85b35bf --- /dev/null +++ b/content/en/feature_flags/use_cases/_index.md @@ -0,0 +1,12 @@ +--- +title: Use Cases +description: Common use cases for Datadog Feature Flags. +--- + +Learn how teams use Datadog Feature Flags for rollouts, kill switches, and dynamic configuration. + +{{< whatsnext desc=" " >}} + {{< nextlink href="/feature_flags/use_cases/progressive_rollouts" >}}Progressive Rollouts and Canaries{{< /nextlink >}} + {{< nextlink href="/feature_flags/use_cases/kill_switches" >}}Kill Switches{{< /nextlink >}} + {{< nextlink href="/feature_flags/use_cases/dynamic_configuration" >}}Dynamic Configuration{{< /nextlink >}} +{{< /whatsnext >}} diff --git a/content/en/feature_flags/use_cases/dynamic_configuration.md b/content/en/feature_flags/use_cases/dynamic_configuration.md new file mode 100644 index 00000000000..fd9fbf5871f --- /dev/null +++ b/content/en/feature_flags/use_cases/dynamic_configuration.md @@ -0,0 +1,98 @@ +--- +title: Dynamic Configuration +description: Change application behavior with feature flag configuration instead of code deployments. +further_reading: +- link: "/feature_flags/concepts/variants_and_flag_types" + tag: "Documentation" + text: "Variants and Flag Types" +- link: "/feature_flags/concepts/json_schema_validation" + tag: "Documentation" + text: "JSON Schema Validation" +--- + +## Overview + +**Dynamic configuration** lets you change application behavior from the Datadog UI without a code deployment. Your application reads configuration values from feature flag variants—strings, numbers, or JSON objects—and you update those values in Datadog when you want to change behavior. + +## How it works + +1. Define variables in your application that read from a feature flag variant. +2. Create a flag with the appropriate [variant type](/feature_flags/concepts/variants_and_flag_types/) (string, integer, number, or JSON). +3. Update variant values or [targeting rules](/feature_flags/concepts/targeting_rules/) in Datadog. +4. The SDK picks up changes on the next configuration refresh. + +For JSON configuration, use [JSON Schema validation](/feature_flags/concepts/json_schema_validation/) to help enforce type safety on variant values. + +## Example: JSON configuration flag + +### Create the flag + +1. Create a JSON feature flag with a control variant, for example: + +```json +{ + "headline": "Welcome", + "cta_color": "blue", + "show_banner": true +} +``` + +2. Optionally add a [JSON Schema](/feature_flags/concepts/json_schema_validation/) to validate future variant values. + +### Read configuration in code + +{{< programming-lang-wrapper langs="javascript,python,go" >}} + +{{< programming-lang lang="javascript" >}} + +```javascript +const client = OpenFeature.getClient(); +const config = await client.getObjectValue('homepage-config', { + headline: 'Welcome', + cta_color: 'blue', + show_banner: false, +}); + +document.title = config.headline; +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="python" >}} + +```python +import json + +default = {"headline": "Welcome", "cta_color": "blue", "show_banner": False} +raw = client.get_string_value("homepage-config", json.dumps(default), eval_ctx) +config = json.loads(raw) +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="go" >}} + +```go +defaultVal := map[string]interface{}{ + "headline": "Welcome", "cta_color": "blue", "show_banner": false, +} +config, _ := client.ObjectValue(ctx, "homepage-config", defaultVal, evalCtx) +``` + +{{< /programming-lang >}} + +{{< /programming-lang-wrapper >}} + +### Run experiments + +Create additional variants with different configuration values and use an **experiment** targeting rule to compare behavior. See [Targeting Rules and Filters](/feature_flags/concepts/targeting_rules/). + +## Common use cases + +- **Marketing**: Update headline copy, CTA text, or colors without deploying. +- **AI and ML**: Compare model parameters or feature toggles across variants in experiments. +- **Operations**: Adjust limits, timeouts, or feature thresholds per environment. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} diff --git a/content/en/feature_flags/use_cases/kill_switches.md b/content/en/feature_flags/use_cases/kill_switches.md new file mode 100644 index 00000000000..e7a8db12143 --- /dev/null +++ b/content/en/feature_flags/use_cases/kill_switches.md @@ -0,0 +1,109 @@ +--- +title: Kill Switches +description: Use boolean feature flags as kill switches to disable features instantly without redeploying. +further_reading: +- link: "/feature_flags/concepts/targeting_rules" + tag: "Documentation" + text: "Targeting Rules and Filters" +- link: "/feature_flags/concepts/environments" + tag: "Documentation" + text: "Environments" +- link: "/feature_flags/client/" + tag: "Documentation" + text: "Client-Side SDKs" +--- + +## Overview + +A **kill switch** is a boolean feature flag that lets you disable a feature instantly when something goes wrong—without redeploying your application. Operations and engineering teams can turn off a problematic feature from the Datadog UI while the application continues to run. + +## When to use a kill switch + +Use kill switches for: + +- New features that might cause errors or performance issues +- Integrations with third-party services that can fail +- Experimental code paths you want to disable quickly in production + +## Set up a kill switch + +### Step 1: Create a boolean flag + +1. Navigate to [**Create Feature Flag**][1]. +2. Set the variant type to **Boolean**. +3. Set distribution channels appropriate for where the feature runs (client, server, or both). +4. Save the flag. + +### Step 2: Evaluate the flag in your application + +Wrap the feature code with a boolean evaluation and a safe default of `false` (feature off): + +{{< programming-lang-wrapper langs="javascript,python,go" >}} + +{{< programming-lang lang="javascript" >}} + +```javascript +import { OpenFeature } from '@openfeature/web-sdk'; + +const client = OpenFeature.getClient(); +const fallback = false; +const showFeature = await client.getBooleanValue('my-kill-switch-flag', fallback); + +if (showFeature) { + // Feature code here +} +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="python" >}} + +```python +enabled = client.get_boolean_value("my-kill-switch-flag", False, eval_ctx) +if enabled: + # Feature code here + pass +``` + +{{< /programming-lang >}} + +{{< programming-lang lang="go" >}} + +```go +enabled, _ := client.BooleanValue(ctx, "my-kill-switch-flag", false, evalCtx) +if enabled { + // Feature code here +} +``` + +{{< /programming-lang >}} + +{{< /programming-lang-wrapper >}} + +Deploy the application with the flag check in place before enabling the flag in production. + +### Step 3: Enable and target the flag + +1. Add [targeting rules](/feature_flags/concepts/targeting_rules/) if you want to limit the feature to specific subjects. +2. Enable the flag in the target [environment](/feature_flags/concepts/environments/). + +### Step 4: Disable the feature in an emergency + +To kill the feature: + +1. Navigate to the flag in Datadog. +2. **Disable** the flag in the affected environment, or **override** the environment to serve `false`. + +The SDK returns the default value (`false`) on the next configuration refresh, and the feature code path stops running. + +## Best practices + +- Use a default value of `false` so the feature is off when the flag is disabled or unavailable. +- Test the kill switch in Staging before relying on it in Production. +- Use [evaluation tracking](/feature_flags/concepts/evaluation_tracking/) to confirm the flag state during an incident. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://app.datadoghq.com/feature-flags/create diff --git a/content/en/feature_flags/use_cases/progressive_rollouts.md b/content/en/feature_flags/use_cases/progressive_rollouts.md new file mode 100644 index 00000000000..f072d66514b --- /dev/null +++ b/content/en/feature_flags/use_cases/progressive_rollouts.md @@ -0,0 +1,75 @@ +--- +title: Progressive Rollouts & Canaries +description: Gradually roll out feature flags on a schedule with optional guardrail metrics for canary releases. +further_reading: +- link: "/feature_flags/concepts/targeting_rules" + tag: "Documentation" + text: "Targeting Rules and Filters" +- link: "/feature_flags/concepts/traffic_splitting" + tag: "Documentation" + text: "Traffic Splitting and Randomization" +- link: "/feature_flags/concepts/evaluation_tracking" + tag: "Documentation" + text: "Evaluation Tracking" +- link: "/feature_flags/concepts/notifications" + tag: "Documentation" + text: "Notifications" +--- + +## Overview + +Progressive rollouts let you gradually release new functionality on a schedule instead of enabling a flag for 100% of traffic at once. **Canaries** are progressive rollouts that monitor **guardrail metrics** and automatically pause or abort when regressions are detected. + +## Progressive rollouts + +### Configure a multistep rollout + +1. Navigate to your feature flag and open **Targeting Rules & Rollouts** for the target environment. +2. Add or edit a targeting rule and choose a **progressive rollout**. +3. Configure rollout steps: + - Set the percentage for each step, or delete steps to simplify the schedule. + - Customize the delay between steps for a slower or faster rollout. + +{{< img src="getting_started/feature_flags/ff-targeting-rules-and-rollouts.png" alt="Multistep progressive rollout configuration" style="width:100%;" >}} + +### Start and control the rollout + +1. **Enable** the flag in the environment so SDKs evaluate your targeting rules. +2. Click the **play** button to start the progressive rollout. + +After the rollout starts: + +- **Pause** to stop progress temporarily. +- **Abort** to revert all progress on the rollout. + +Monitor progress with [evaluation tracking](/feature_flags/concepts/evaluation_tracking/) and configure [notifications](/feature_flags/concepts/notifications/) for rollout events. + +## Canaries + +A canary is a progressive rollout that includes **guardrail metrics**. Guardrail metrics measure standard KPIs such as error rate and long task count. + +### How canaries work + +When guardrail metrics are configured, the rollout monitors metrics in both groups: + +- **Treatment**: Subjects receiving the variant you are rolling out +- **Control**: Subjects not receiving the treatment variant + +If a statistically significant change is observed for any guardrail metric (direction depends on metric type), the rollout is automatically **paused** or **aborted** based on the behavior you configure when you create the canary rollout. + +### Configure a canary rollout + +1. Create a progressive rollout targeting rule as described above. +2. Add guardrail metrics to the rollout configuration. +3. Choose whether guardrail failures should pause or abort the rollout. + +
enableExposureLogging to true on client SDKs can impact RUM costs when guardrail metrics rely on exposure data.