[codex] Fix Feature Flags documentation guidance#36573
Conversation
| ## Overview | ||
|
|
||
| Feature flags enable you to toggle features on and off, conduct A/B/n testing, gradually roll out new functionality, and personalize user experiences—all without the need for extensive code deployments. With feature flags, you can empower your team to make dynamic changes, iterate rapidly, and deliver enhanced user experiences. | ||
| Datadog Feature Flags is Datadog's flag management product. You create flags in Datadog, deliver flag configuration to Datadog SDKs, and evaluate variants in your application through Datadog or OpenFeature APIs. |
There was a problem hiding this comment.
🤖 Context from Codex: This establishes the distinction the old hub was missing: Datadog Feature Flags is the flag-management product, while RUM Feature Flag Tracking is the observability path for third-party providers. Without that distinction, browser telemetry settings later in the docs are easy to misread.
| - **Real-time metrics:** Understand who's receiving each variant, as well as how your flag impacts the health & performance of your application—all in real time. | ||
|
|
||
| - **Supports any data type:** Use Booleans, strings, numbers or full JSON objects—whatever your use case requires. | ||
| - **Supports common flag types:** Use Boolean, string, numeric, or JSON variants. Some SDKs expose integer and floating-point methods separately, while JavaScript uses `getNumberValue()` for numeric variants. |
There was a problem hiding this comment.
🤖 Context from Codex: The old wording promised every data type, but the SDK pages and APIs expose specific Boolean, string, numeric, and object/JSON shapes. Calling out JavaScript's single numeric getter also reconciles the cross-SDK difference between JS and SDKs that split integer/double methods.
|
|
||
| Then, add the following to your project to initialize the SDK: | ||
|
|
||
| Supported browser Feature Flags sites are `datadoghq.com`, `us3.datadoghq.com`, `us5.datadoghq.com`, `ap1.datadoghq.com`, `ap2.datadoghq.com`, and `datadoghq.eu`. Browser Feature Flags are not supported on GovCloud sites. |
There was a problem hiding this comment.
🤖 Context from Codex: The browser endpoint code has an explicit site allowlist and throws for unsupported sites, including GovCloud. Adding the supported list near the first browser setup sample keeps users from discovering this only at runtime.
| ``` | ||
|
|
||
| <div class="alert alert-warning">Setting <code>enableExposureLogging</code> to <code>true</code> can impact <a href="https://docs.datadoghq.com/real_user_monitoring/">RUM</a> 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.</div> | ||
| <div class="alert alert-info">The browser SDK emits three independent telemetry streams, all enabled by default. <code>enableExposureLogging</code> sends per-evaluation exposure events to the exposures intake. <code>enableFlagEvaluationTracking</code> sends aggregated evaluation telemetry to the flag-evaluation intake. <code>enableRumFeatureFlagTracking</code> attaches flag evaluations to RUM events and is the setting that can affect RUM usage. Disable only the stream you do not need.</div> |
There was a problem hiding this comment.
🤖 Context from Codex: The prior warning attached RUM cost impact to enableExposureLogging, but the browser SDK separates exposure logging, evaluation telemetry, and RUM correlation. enableRumFeatureFlagTracking is the setting that attaches flag evaluations to RUM events.
|
|
||
| In your application code, use the SDK to evaluate the flag and gate the new feature. | ||
|
|
||
| <div class="alert alert-warning">Datadog Feature Flags requires evaluation-context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div> |
There was a problem hiding this comment.
🤖 Context from Codex: The client and server hub pages already warn that nested objects and arrays are not supported in evaluation context. Repeating that warning next to the first copy-paste context sample reduces the risk of silently dropped exposure data.
| import DatadogFlags | ||
|
|
||
| let flagsClient = FlagsClient.shared() | ||
| let flagsClient = FlagsClient.create() |
There was a problem hiding this comment.
🤖 Context from Codex: The iOS direct API returns a client from FlagsClient.create() and uses getBooleanValue(key:defaultValue:). The previous migration sample used Android-style resolveBooleanValue(flagKey:defaultValue:), which would not compile in Swift.
| import com.launchdarkly.sdk.LDContext | ||
| import com.launchdarkly.sdk.android.LDClient | ||
| import com.launchdarkly.sdk.android.LDConfig | ||
| import android.app.Application |
There was a problem hiding this comment.
🤖 Context from Codex: The Android fallback wrapper previously referenced an application object and Datadog configuration without importing or initializing them. Adding the explicit application/config setup makes the sample self-contained enough to adapt.
| init(userId: String, evaluationContext: [String: AnyValue] = [:]) { | ||
| let ldConfig = LDConfig(mobileKey: 'YOUR_LD_MOBILE_KEY', autoEnvAttributes: .enabled) | ||
| var ldContext = LDContextBuilder(key: userId) | ||
| init(userId: String, evaluationContext: [String: String] = [:]) { |
There was a problem hiding this comment.
🤖 Context from Codex: Using [String: String] for the fallback wrapper keeps the sample compatible with both LaunchDarkly context attributes and Datadog's flat primitive evaluation context requirement.
| } catch { | ||
| print("Falling back to LaunchDarkly for flag: \(flagKey)") | ||
| return self.ldClient.boolVariation(forKey: flagKey, defaultValue: defaultValue) | ||
| let details = self.ddClient.getBooleanDetails( |
There was a problem hiding this comment.
🤖 Context from Codex: The iOS FlagsClient getter does not throw, so a do/catch fallback would never trigger as shown. Using details lets the wrapper inspect evaluation errors before falling back to LaunchDarkly.
| class FallbackWrapper { | ||
| private ldClient; | ||
| private ddClient; | ||
| ldClient; |
There was a problem hiding this comment.
🤖 Context from Codex: The browser fallback block is JavaScript, not TypeScript, so private class fields were invalid syntax. Plain class fields keep the snippet runnable as documented.
| - **Real-time metrics:** Understand who's receiving each variant, as well as how your flag impacts the health & performance of your application—all in real time. | ||
|
|
||
| - **Supports any data type:** Use Booleans, strings, numbers or full JSON objects—whatever your use case requires. | ||
| - **Supports common flag types:** Use Boolean, string, integer, numeric (float/double), or JSON variants. JavaScript SDKs use `getNumberValue()` for both integer and numeric variants, while Java, Swift, Kotlin, and Python expose separate integer and floating-point evaluation methods. |
There was a problem hiding this comment.
🤖 Context from Codex: Aligns the overview with the platform variant model and spells out the SDK API split: JavaScript has one numeric getter, while Java/Swift/Kotlin/Python expose integer and floating-point paths separately. Sources: DataDog/dd-sdk-ios@develop:DatadogFlags/Sources/Client/FlagsClientProtocol.swift:207 and :223; DataDog/dd-sdk-android@develop:features/dd-sdk-android-flags-openfeature/src/main/kotlin/com/datadog/android/flags/openfeature/DatadogFlagsProvider.kt:140 and :146; content/en/feature_flags/server/python.md:139; content/en/feature_flags/server/nodejs.md:194.
| ### Step 1: Import and initialize the SDK | ||
|
|
||
| First, install `@datadog/openfeature-browser`, `@openfeature/web-sdk`, and `@openfeature/core` as dependencies in your project: | ||
| Choose the SDK that matches where the flag is evaluated and initialize the Datadog Feature Flags provider. |
There was a problem hiding this comment.
🤖 Context from Codex: Adds the requested multi-SDK initialization tabs so server-side readers do not have to leave the getting-started flow to find their first setup snippet. Snippets are copied from the per-language docs: content/en/feature_flags/client/javascript.md:48, content/en/feature_flags/server/nodejs.md:30, content/en/feature_flags/server/java.md:42, and content/en/feature_flags/server/python.md:41.
|
|
||
| - **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) | ||
| - **Variant type**: The data type for the flag variants (Boolean, string, integer, numeric (float/double), or JSON) |
There was a problem hiding this comment.
🤖 Context from Codex: Keeps the create-flag UI terminology consistent with the overview by using numeric (float/double) instead of the ambiguous number. The follow-up line explains the JavaScript-versus-typed-SDK getter distinction.
| ```js | ||
| <div class="alert alert-warning">Datadog Feature Flags requires evaluation-context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div> | ||
|
|
||
| {{< tabs >}} |
There was a problem hiding this comment.
🤖 Context from Codex: Adds the requested JavaScript, Node.js, Java, and Python evaluation tabs using the same canonical Boolean examples from the platform pages: content/en/feature_flags/client/javascript.md:98, content/en/feature_flags/server/nodejs.md:143, content/en/feature_flags/server/java.md:247, and content/en/feature_flags/server/python.md:111.
| Feature flags enable you to toggle features on and off, conduct A/B/n testing, gradually roll out new functionality, and personalize user experiences—all without the need for extensive code deployments. With feature flags, you can empower your team to make dynamic changes, iterate rapidly, and deliver enhanced user experiences. | ||
| Datadog Feature Flags is Datadog's flag management product. You create flags in Datadog, deliver flag configuration to Datadog Feature Flags SDKs, and evaluate variants in your application through Datadog or OpenFeature APIs. | ||
|
|
||
| Datadog Feature Flags is built on the [OpenFeature standard](https://openfeature.dev/docs/reference/intro/), an open-source, vendor-neutral specification for feature flag APIs. See OpenFeature's getting-started guide if you're new to OpenFeature concepts like providers, evaluation context, and hooks. |
There was a problem hiding this comment.
🤖 Context from Codex: Adds the OpenFeature primer link on the hub so readers can learn provider, evaluation-context, and hook concepts from the upstream standard instead of us duplicating that primer here. Source: https://openfeature.dev/docs/reference/intro/.
| ## Overview | ||
|
|
||
| This page describes how to instrument your .NET application with the Datadog Feature Flags SDK. The .NET SDK integrates with [OpenFeature][1], an open standard for feature flag management, and uses the Datadog SDK's Remote Configuration to receive flag updates in real time. | ||
| This page describes how to instrument your .NET application with the Datadog Feature Flags SDK. The .NET SDK integrates with [OpenFeature][1], an open standard for feature flag management, and receives flag updates through Remote Configuration in the Datadog .NET tracer (`dd-trace-dotnet`). |
There was a problem hiding this comment.
🤖 Context from Codex: Clarifies that .NET server-side flags receive Remote Configuration through the Datadog .NET tracer (dd-trace-dotnet), not a generic Datadog SDK.
| ## Overview | ||
|
|
||
| This page describes how to instrument your Go application with the Datadog Feature Flags SDK. The Go SDK integrates with [OpenFeature][1], an open standard for feature flag management, and uses the Datadog SDK's Remote Configuration to receive flag updates in real time. | ||
| This page describes how to instrument your Go application with the Datadog Feature Flags SDK. The Go SDK integrates with [OpenFeature][1], an open standard for feature flag management, and receives flag updates through Remote Configuration in the Datadog Go tracer (`dd-trace-go`). |
There was a problem hiding this comment.
🤖 Context from Codex: Clarifies that Go server-side flags receive Remote Configuration through the Datadog Go tracer (dd-trace-go), and the initialization wording now says to start that tracer first.
| This page describes how to instrument a Java application with the Datadog Feature Flags SDK. Datadog feature flags provide a unified way to remotely control feature availability in your app, experiment safely, and deliver new experiences with confidence. | ||
|
|
||
| The Java SDK integrates feature flags directly into the Datadog SDK and implements the [OpenFeature](https://openfeature.dev/) standard for maximum flexibility and compatibility. | ||
| The Java SDK integrates feature flags directly into the Datadog Java tracer (`dd-trace-java`) and implements the [OpenFeature](https://openfeature.dev/) standard for maximum flexibility and compatibility. |
There was a problem hiding this comment.
🤖 Context from Codex: Clarifies that Java Feature Flags are integrated with the Datadog Java tracer (dd-trace-java), reducing the ambiguity caused by the generic Datadog SDK phrase.
| ## Overview | ||
|
|
||
| This page describes how to instrument your Node.js application with the Datadog Feature Flags SDK. The Node.js SDK integrates with [OpenFeature][2], an open standard for feature flag management, and uses the Datadog SDK's Remote Configuration to receive flag updates in real time. | ||
| This page describes how to instrument your Node.js application with the Datadog Feature Flags SDK. The Node.js SDK integrates with [OpenFeature][2], an open standard for feature flag management, and receives flag updates through Remote Configuration in the Datadog Node.js tracer (`dd-trace`). |
There was a problem hiding this comment.
🤖 Context from Codex: Clarifies that Node.js server-side flags receive Remote Configuration through the Datadog Node.js tracer (dd-trace).
| ## Overview | ||
|
|
||
| This page describes how to instrument your Python application with the Datadog Feature Flags SDK. The Python SDK integrates with [OpenFeature][1], an open standard for feature flag management, and uses the Datadog SDK's Remote Configuration to receive flag updates in real time. | ||
| This page describes how to instrument your Python application with the Datadog Feature Flags SDK. The Python SDK integrates with [OpenFeature][1], an open standard for feature flag management, and receives flag updates through Remote Configuration in the Datadog Python tracer (`ddtrace`). |
There was a problem hiding this comment.
🤖 Context from Codex: Clarifies that Python server-side flags receive Remote Configuration through the Datadog Python tracer (ddtrace).
|
🤖 Context from Codex: Follow-up disposition for the Claude review iteration (commit
Validation: |
aarsilv
left a comment
There was a problem hiding this comment.
🤖 Context from Codex: Context notes for the GovCloud wording simplification.
| Then, add the following to your project to initialize the SDK: | ||
|
|
||
| ```js | ||
| Note: Browser Feature Flags are currently not supported on GovCloud sites. |
There was a problem hiding this comment.
🤖 Context from Codex: Replaces the enumerated commercial Datadog site list with the durable compatibility note requested in review. The provider still accepts a site option, but listing domains here creates avoidable maintenance risk; the important product caveat is that browser Feature Flags are not supported on GovCloud sites.
| Create a `DatadogProvider` instance with your Datadog credentials. To create a client token, see [Client tokens][2]. | ||
| Create a `DatadogProvider` instance with your Datadog credentials. `applicationId`, `clientToken`, `site`, and `env` are required. To create a client token, see [Client tokens][2]. | ||
|
|
||
| Note: Browser Feature Flags are currently not supported on GovCloud sites. |
There was a problem hiding this comment.
🤖 Context from Codex: Replaces the enumerated commercial Datadog site list with the durable compatibility note requested in review. The provider still accepts a site option, but listing domains here creates avoidable maintenance risk; the important product caveat is that browser Feature Flags are not supported on GovCloud sites.
| Create a `DatadogProvider` instance and register it with OpenFeature. Do this as early as possible in your application, before rendering your React components. To create a client token, see [Client tokens][2]. | ||
| Create a `DatadogProvider` instance and register it with OpenFeature. Do this as early as possible in your application, before rendering your React components. `applicationId`, `clientToken`, `site`, and `env` are required. To create a client token, see [Client tokens][2]. | ||
|
|
||
| Note: Browser Feature Flags are currently not supported on GovCloud sites. |
There was a problem hiding this comment.
🤖 Context from Codex: Replaces the enumerated commercial Datadog site list with the durable compatibility note requested in review. The provider still accepts a site option, but listing domains here creates avoidable maintenance risk; the important product caveat is that browser Feature Flags are not supported on GovCloud sites.
| Create a `DatadogProvider` instance with your Datadog credentials. To create a client token, see [Client tokens][2]. | ||
| Create a `DatadogProvider` instance with your Datadog credentials. `applicationId`, `clientToken`, `site`, and `env` are required. To create a client token, see [Client tokens][2]. | ||
|
|
||
| Note: Browser Feature Flags are currently not supported on GovCloud sites. |
There was a problem hiding this comment.
🤖 Context from Codex: Replaces the enumerated commercial Datadog site list with the durable compatibility note requested in review. The provider still accepts a site option, but listing domains here creates avoidable maintenance risk; the important product caveat is that browser Feature Flags are not supported on GovCloud sites.
aarsilv
left a comment
There was a problem hiding this comment.
🤖 Context from Codex: Context note for the evaluation context terminology cleanup.
| In your application code, use the SDK to evaluate the flag and gate the new feature. | ||
|
|
||
| ```js | ||
| <div class="alert alert-warning">Datadog Feature Flags requires evaluation context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div> |
There was a problem hiding this comment.
🤖 Context from Codex: OpenFeature uses evaluation context as the term of art without a hyphen; its concept docs define “The evaluation context…” and the spec describes custom fields on the evaluation context. This removes the hyphenated compound from the repeated Datadog warning text while preserving the intended meaning. Sources: https://openfeature.dev/docs/reference/concepts/evaluation-context and https://openfeature.dev/specification/sections/evaluation-context/.
aarsilv
left a comment
There was a problem hiding this comment.
🤖 Context from Codex: Context note for removing duplicate RUM tracking guidance.
|
|
||
| Evaluation context attributes are the flat string, number, and Boolean values that Datadog uses for targeting rules and rollout bucketing. Set a stable `targetingKey`, such as a user ID, session ID, or device ID, so percentage rollouts are consistent. | ||
|
|
||
| Feature Flags telemetry includes exposure events, flag evaluation metrics, and optional RUM correlation depending on the SDK and configuration. |
There was a problem hiding this comment.
🤖 Context from Codex: Removes the second RUM Feature Flag Tracking pointer from the telemetry section because the index already directs third-party flag-provider users to that page earlier in the overview.
There was a problem hiding this comment.
Pull request overview
This PR updates Datadog Feature Flags documentation to better match current public SDK/provider behavior, especially around supported evaluation types, telemetry, Remote Configuration prerequisites, and platform-specific setup details.
Changes:
- Expands and standardizes SDK setup guidance across client-side and server-side docs (versions, Remote Configuration/Agent requirements, and metrics toggles).
- Clarifies evaluation context requirements (flat primitive attributes) and documents additional telemetry/configuration options.
- Updates migration and getting-started docs with corrected/expanded examples and navigation improvements.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| content/en/getting_started/feature_flags/_index.md | Adds multi-SDK tabs, credential guidance, context constraints, and clarifies supported flag types. |
| content/en/feature_flags/server/ruby.md | Updates prerequisites/versions and adds env-var + context guidance. |
| content/en/feature_flags/server/python.md | Clarifies tracer/RC relationship, adds metrics env var, and strengthens prerequisites/context guidance. |
| content/en/feature_flags/server/nodejs.md | Clarifies tracer/RC relationship, adds env-var guidance, and context constraints. |
| content/en/feature_flags/server/java.md | Aligns Agent/RC prerequisites, adds metrics toggle, and updates troubleshooting guidance. |
| content/en/feature_flags/server/go.md | Clarifies tracer/RC relationship, adds metrics env var, and context constraints. |
| content/en/feature_flags/server/dotnet.md | Clarifies tracer/RC relationship, adds metrics env var, and context constraints. |
| content/en/feature_flags/server/_index.md | Clarifies server-side conceptual model (tracer + RC) and RC defaults. |
| content/en/feature_flags/guide/migrate_from_launchdarkly.md | Updates migration steps and modernizes client-side fallback examples. |
| content/en/feature_flags/feature_flag_mcp_server.md | Adds preview API note and refines tool capability description. |
| content/en/feature_flags/client/unity.md | Clarifies Unity SDK wording, adds context constraints, and expands testing guidance. |
| content/en/feature_flags/client/reactnative.md | Clarifies SDK wording, fixes hook usage, and adds in-memory provider testing example. |
| content/en/feature_flags/client/react.md | Adds required deps/options guidance and expands browser provider configuration. |
| content/en/feature_flags/client/javascript.md | Adds required-fields note, GovCloud note, context constraints, and browser provider options. |
| content/en/feature_flags/client/ios.md | Clarifies iOS SDK wording, fixes sample variable name, adds context constraints, and documents evaluation endpoint. |
| content/en/feature_flags/client/angular.md | Adds required-fields note, GovCloud note, context constraints, and browser provider options/testing example. |
| content/en/feature_flags/client/android.md | Clarifies Android SDK wording, adds context constraints, and adds evaluation endpoint guidance. |
| content/en/feature_flags/client/_index.md | Adds OpenFeature positioning plus cross-platform telemetry option mapping. |
| content/en/feature_flags/_index.md | Reframes overview around OpenFeature + credential/context/telemetry fundamentals. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| FlagsClient.Builder().build() | ||
| val flagsClient = FlagsClient.get() |
| applicationId: '<APPLICATION_ID>', | ||
| enableExposureLogging: true, // Can impact RUM costs if enabled | ||
| clientToken: '<CLIENT_TOKEN>', | ||
| site: 'datadoghq.com', |
| const ddProvider = new DatadogProvider({ | ||
| applicationId: 'YOUR_APP_ID', | ||
| clientToken: 'YOUR_CLIENT_TOKEN', | ||
| site: 'datadoghq.com', |
| import { useBooleanFlag } from '@openfeature/react-sdk'; | ||
| import { Suspense } from 'react'; | ||
|
|
||
| import | ||
| function Content() { | ||
| // Display a loading message if the component uses feature flags and the provider is not ready | ||
| return ( |
What changed
This updates Datadog Feature Flags docs after auditing the current docs against the public SDK/provider implementations.
Validation
Could not run full local Hugo/Vale validation because this checkout does not have
node_modules,hugo, orvaleinstalled.