From c6cfc53b8957dd994d23bbff272fe2ac39a94f56 Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Thu, 16 Jul 2026 14:15:36 -0400 Subject: [PATCH 1/3] docs(feature-flags): document default agentless delivery --- config/_default/menus/main.en.yaml | 5 + content/en/feature_flags/_index.md | 6 +- content/en/feature_flags/concepts/_index.md | 1 + .../concepts/configuration_sources.md | 97 +++++++++++ .../implementation_patterns/serverless.md | 134 ++++++++------- content/en/feature_flags/server/_index.md | 93 +++++++--- content/en/feature_flags/server/java.md | 159 ++++++++++-------- content/en/feature_flags/server/nodejs.md | 62 +++++-- 8 files changed, 392 insertions(+), 165 deletions(-) create mode 100644 content/en/feature_flags/concepts/configuration_sources.md diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index fc5121b8eb3..0f16a1f9555 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -6403,6 +6403,11 @@ menu: parent: feature_flags_concepts identifier: feature_flags_concepts_approvals weight: 321 + - name: Configuration Sources + url: feature_flags/concepts/configuration_sources + parent: feature_flags_server + identifier: feature_flags_server_configuration_sources + weight: 200 - name: Implementation Patterns url: feature_flags/implementation_patterns parent: feature_flags diff --git a/content/en/feature_flags/_index.md b/content/en/feature_flags/_index.md index 2112834d578..9cc2330c97c 100644 --- a/content/en/feature_flags/_index.md +++ b/content/en/feature_flags/_index.md @@ -44,7 +44,7 @@ Feature flags enable you to toggle features on and off, conduct A/B/n testing, g If your flags are managed by LaunchDarkly, Split, ConfigCat, or another provider and you only want Datadog to record evaluated variants in RUM, see [RUM Feature Flag Tracking](/real_user_monitoring/feature_flag_tracking/) instead. -Use a client-side SDK when the flag is evaluated in a browser, mobile app, or game client. Use a server-side SDK when the flag is evaluated in a backend service that receives flag configuration through the Datadog Agent and Remote Configuration. +Use a client-side SDK when the flag is evaluated in a browser, mobile app, or game client. Use a server-side SDK when the flag is evaluated in a backend service. Supported server SDK versions receive configuration directly from Datadog by default or through Agent Remote Configuration when explicitly selected. See [Server SDK Configuration Sources][1]. ### Credentials at a glance @@ -52,7 +52,7 @@ Use a client-side SDK when the flag is evaluated in a browser, mobile app, or ga | --- | --- | --- | --- | | Client token | Browser, mobile, and game SDKs | Client application configuration | No — safe to ship in public client code | | Application ID | Browser and RUM-backed client SDKs | Client application configuration | No — public identifier | -| API key | Datadog Agent for server-side Remote Configuration | Agent configuration only | Yes — keep server-side only | +| API key | Server SDKs and the Datadog Agent | Application configuration for agentless delivery; Agent configuration for Remote Configuration | Yes—keep server-side only | Do not put API keys in browser, mobile, or game applications. @@ -65,3 +65,5 @@ Feature Flags telemetry includes exposure events, flag evaluation metrics, and o ## Further reading {{< partial name="whats-next/whats-next.html" >}} + +[1]: /feature_flags/concepts/configuration_sources/ diff --git a/content/en/feature_flags/concepts/_index.md b/content/en/feature_flags/concepts/_index.md index a26f3266b33..312ca0db461 100644 --- a/content/en/feature_flags/concepts/_index.md +++ b/content/en/feature_flags/concepts/_index.md @@ -12,6 +12,7 @@ Learn how Datadog Feature Flags work and how to configure flags, environments, t {{< nextlink href="/feature_flags/concepts/saved_filters" >}}Saved 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/configuration_sources" >}}Server SDK Configuration Sources{{< /nextlink >}} {{< nextlink href="/feature_flags/concepts/flag_history" >}}Flag History{{< /nextlink >}} {{< nextlink href="/feature_flags/concepts/flag_graphs" >}}Feature Flag Graphs{{< /nextlink >}} {{< nextlink href="/feature_flags/concepts/stale_flags" >}}Stale Flags{{< /nextlink >}} diff --git a/content/en/feature_flags/concepts/configuration_sources.md b/content/en/feature_flags/concepts/configuration_sources.md new file mode 100644 index 00000000000..db0f47bbbbc --- /dev/null +++ b/content/en/feature_flags/concepts/configuration_sources.md @@ -0,0 +1,97 @@ +--- +title: Server SDK Configuration Sources +description: Understand how Datadog Feature Flags server SDKs receive flag configuration. +further_reading: +- link: "/feature_flags/server/" + tag: "Documentation" + text: "Set up Server-Side Feature Flags" +- link: "/feature_flags/implementation_patterns/serverless/" + tag: "Documentation" + text: "Use Feature Flags in serverless environments" +- link: "/remote_configuration/" + tag: "Documentation" + text: "Learn about Remote Configuration" +--- + +Datadog Feature Flags server SDKs evaluate flags locally from Universal Flag Configuration (UFC). The _configuration source_ determines how the SDK receives UFC; it does not change OpenFeature evaluation semantics. + +## Configuration source modes + +| Mode | Configuration delivery | Agent requirement | When to use | +|---|---|---|---| +| `agentless` (default) | The SDK periodically fetches UFC from the Datadog-managed CDN over HTTPS. | No Datadog Agent is required for flag configuration. | The default for supported server SDK versions, including serverless environments. | +| `remote_config` | The Datadog Agent receives UFC through Remote Configuration and delivers it to the SDK. | Requires an Agent with Remote Configuration enabled. | Use when you explicitly want Agent-managed delivery. | + +Agentless delivery is available in these SDK versions: + +| SDK | Minimum version | +|---|---| +| Java (`dd-java-agent` and `dd-openfeature`) | 1.65.0 | +| Node.js `dd-trace` v5 | 5.116.0 | +| Node.js `dd-trace` v6 | 6.5.0 | + +Earlier Java and Node.js releases continue to use Agent Remote Configuration. Upgrade the language-specific dependencies to the listed minimums before using agentless delivery. + +
The initial agentless releases support configuration delivery and local flag evaluation. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+ +## Agentless delivery + +Agentless mode is the default in SDK versions that support it. You do not need to set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` unless you want to make the selection explicit. + +Configure the application process with: + +{{< code-block lang="bash" >}} +# Required: Enable the Feature Flags provider +DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true + +# Required for agentless configuration delivery +DD_API_KEY= +DD_ENV= + +# Optional: Defaults to datadoghq.com +DD_SITE= + +# Optional: Agentless is the default +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless +{{< /code-block >}} + +The SDK fetches configuration in the background and evaluates flags locally. Individual flag evaluations do not make network requests. The agentless source: + +- polls every 30 seconds by default; +- uses a 2-second request timeout by default; +- uses ETags to avoid downloading unchanged configuration; +- preserves the last accepted configuration during temporary network or payload errors; and +- prevents overlapping polls. + +You can change the operational defaults with these environment variables: + +| Environment variable | Default | Description | +|---|---|---| +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Time between completed polling attempts. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `2` | Timeout for an individual configuration request. | + +Keep `DD_API_KEY` in a secret manager and expose it only to the application process that loads flag configuration. Agentless configuration delivery sends the API key directly from the application to Datadog over HTTPS. + +Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Applications on that site continue to use caller-provided default values unless they use Agent Remote Configuration. + +## Agent remote configuration + +Set the source to `remote_config` to use Agent-managed delivery: + +{{< code-block lang="bash" >}} +DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +DD_REMOTE_CONFIGURATION_ENABLED=true +{{< /code-block >}} + +Configure the API key on the Agent, not in the application process. See [Remote Configuration][1] for Agent setup and network requirements. + +## Future offline mode + +Offline mode is planned for applications that provide UFC JSON bytes at startup and do not make CDN or Remote Configuration network requests. It is not available in the initial agentless releases. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /remote_configuration/ diff --git a/content/en/feature_flags/implementation_patterns/serverless.md b/content/en/feature_flags/implementation_patterns/serverless.md index e7fa77d6b82..4e50379dfa3 100644 --- a/content/en/feature_flags/implementation_patterns/serverless.md +++ b/content/en/feature_flags/implementation_patterns/serverless.md @@ -1,10 +1,13 @@ --- title: Serverless Environments -description: Use Datadog Feature Flags server SDKs from serverless environments with a Datadog Agent. +description: Use Datadog Feature Flags server SDKs in serverless environments with or without a Datadog Agent. further_reading: - link: "/feature_flags/server/" tag: "Documentation" text: "Server-Side Feature Flags" +- link: "/feature_flags/concepts/configuration_sources/" + tag: "Concept" + text: "Server SDK Configuration Sources" - link: "/remote_configuration/" tag: "Documentation" text: "Remote Configuration" @@ -15,100 +18,115 @@ further_reading: ## Overview -Datadog Feature Flags server SDKs receive flag configuration through [Remote Configuration][1]. The Datadog Agent is required for this flow: it connects to Datadog, receives signed Remote Configuration payloads, validates those payloads, and makes the resulting feature flag configuration available to the Datadog SDK in your application. +Supported Datadog Feature Flags server SDKs can receive Universal Flag Configuration (UFC) directly from the Datadog-managed CDN. This _agentless_ configuration source does not require a Datadog Agent, which makes it the default delivery mode for supported serverless applications. -After the SDK receives the payload, flag evaluation happens locally in your application. The SDK does not make a network request to Datadog for each flag evaluation. +After configuration is loaded, flag evaluation happens locally in the application. The SDK does not make a network request for each evaluation. -Serverless runtimes that cannot run or reach a Datadog Agent do not support Feature Flags server SDK payload delivery. +Agentless configuration delivery is available in: -## Agent-backed architecture +| SDK | Minimum version | +|---|---| +| Java (`dd-java-agent` and `dd-openfeature`) | 1.65.0 | +| Node.js `dd-trace` v5 | 5.116.0 | +| Node.js `dd-trace` v6 | 6.5.0 | -Some serverless workloads can be configured to reach private network resources. In those environments, you may be able to route tracer traffic to a Datadog Agent running on stateful infrastructure, such as EC2, ECS, EKS, a Google Compute Engine VM, GKE, an Azure VM, or AKS. This pattern depends on your cloud networking, runtime, and SDK support. Validate it in a non-production environment before relying on it for feature flag delivery. +Other server SDKs require Agent Remote Configuration for flag delivery. Earlier Java and Node.js releases also require it. -1. Configure the Agent with Remote Configuration enabled. The Agent uses the full-word Remote Configuration variable: +
Flag evaluation only: The initial agentless releases load configuration and evaluate flags. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
- {{< code-block lang="bash" >}} - DD_REMOTE_CONFIGURATION_ENABLED=true - DD_API_KEY= - DD_SITE= - {{< /code-block >}} +## Default Agentless architecture -1. Configure the serverless application to use the Agent as its trace Agent endpoint and enable the Feature Flags provider: +Use agentless delivery when the serverless runtime can make outbound HTTPS requests to Datadog: - {{< code-block lang="bash" >}} - DD_AGENT_HOST= - DD_TRACE_AGENT_PORT=8126 - DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true - {{< /code-block >}} +1. Use a Java or Node.js SDK version listed in [Overview](#overview). +2. Enable the Feature Flags provider and configure the API key, site, and environment in the serverless application: -
The EXPERIMENTAL_ prefix is retained for backwards compatibility; the provider itself is stable.
+ {{< code-block lang="bash" >}} + DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true + DD_API_KEY= + DD_ENV= - Some language tracers also support or require a tracer-side Remote Configuration setting, such as `DD_REMOTE_CONFIG_ENABLED=true`. This is separate from the Agent's `DD_REMOTE_CONFIGURATION_ENABLED` setting. See the language-specific Feature Flags server SDK setup for the variables required by your SDK. + # Optional: Defaults to datadoghq.com + DD_SITE= -1. Configure the standard service tags used by the server SDK: + # Optional: Agentless is the default in supported versions + DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless + {{< /code-block >}} - {{< code-block lang="bash" >}} - DD_SERVICE= - DD_ENV= - DD_VERSION= - {{< /code-block >}} +3. Initialize the OpenFeature provider as described on the [Java][3] or [Node.js][4] setup page. +4. Store `DD_API_KEY` in the serverless platform's secret manager and expose it only to the application process. -1. Use the language-specific Feature Flags server SDK setup after the Agent connection is available. See [Server-Side Feature Flags][2] for setup by language. +The SDK polls the Datadog-managed CDN every 30 seconds by default and uses ETags for unchanged configuration. It preserves the last accepted configuration during temporary errors. If no configuration has been accepted, OpenFeature evaluations return the caller-provided default value. -## Operational considerations +Agentless mode removes the Agent dependency for _flag configuration_. It does not change your APM or serverless telemetry setup. You can continue to use the Datadog Lambda Extension, `serverless-init`, an Agent sidecar, or another supported telemetry path independently. -Treat the Datadog Agent as part of the runtime dependency chain for server-side flag delivery: +## Agent-backed remote configuration -- **Network path**: The serverless workload must be able to reach the Agent on the trace Agent port, typically `8126`. The Agent must be able to reach Datadog over HTTPS. -- **Private connectivity**: Keep the Agent endpoint on a private network. Do not expose the Agent trace intake publicly. -- **High availability**: If the Agent is unavailable during startup, SDKs use default values until the first configuration payload is available. Run enough Agent capacity for the serverless workload's concurrency and availability requirements. -- **Cold starts**: Blocking provider initialization can increase cold-start latency. If startup latency is more important than immediately serving remote flag values, initialize asynchronously and rely on defaults until the provider is ready. -- **Flag updates**: Remote Configuration delivery is eventually consistent. Allow for the Agent polling interval and SDK startup time when testing a newly changed flag. +Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` to explicitly use the existing Agent Remote Configuration path: -## Environment notes +{{< code-block lang="bash" >}} +# Serverless application +DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +DD_AGENT_HOST= +DD_TRACE_AGENT_PORT=8126 +{{< /code-block >}} -### AWS Lambda +Configure the Agent with Remote Configuration and the API key: -AWS Lambda does not support direct Feature Flags server SDK payload delivery through the Datadog Lambda Extension alone. The Lambda Extension can collect telemetry, but it is not a replacement for the Agent Remote Configuration path required by Feature Flags server SDKs. +{{< code-block lang="bash" >}} +DD_REMOTE_CONFIGURATION_ENABLED=true +DD_API_KEY= +DD_SITE= +{{< /code-block >}} -If the Lambda function runs in a VPC and can reach private infrastructure, you can validate an Agent-backed architecture with a Datadog Agent running on stateful infrastructure, such as EC2, ECS, or EKS. Configure the function's Agent endpoint and Feature Flags provider settings as described in [Agent-backed architecture](#agent-backed-architecture). +The serverless workload must be able to reach the Agent on a private network, and the Agent must be able to reach Datadog over HTTPS. Do not expose the Agent trace intake publicly. -For Java Lambda functions, the Java Feature Flags SDK expects the Datadog Java tracer runtime to receive Remote Configuration from the Agent. Native-image builds, such as Quarkus native or GraalVM AOT applications, are not a supported direct path for Java Feature Flags server SDK payload delivery. +## Operational considerations -### Google Cloud Run services +- **Cold starts**: Blocking provider initialization waits for the first configuration and can add cold-start latency. Initialize asynchronously if serving caller-provided default values during startup is acceptable. +- **Outbound connectivity**: Agentless delivery requires HTTPS access to the Datadog-managed UFC CDN. It does not require access to Agent port `8126`. +- **API key ownership**: In agentless mode, the application owns `DD_API_KEY`. In `remote_config` mode, the Agent owns the API key. +- **Flag updates**: Delivery is eventually consistent. Allow for the SDK polling interval and application startup time when testing changes. +- **Last-known-good behavior**: After a configuration has been accepted, temporary network failures or malformed responses do not replace it. +- **Runtime support**: Agentless configuration removes the Agent requirement, but it does not make an otherwise unsupported Java or Node.js runtime compatible with the tracer. Check the language tracer's compatibility requirements. -Cloud Run services can use Datadog serverless monitoring instrumentation, including in-container and sidecar approaches for telemetry. Remote Configuration for Feature Flags server SDKs is not supported directly in Cloud Run managed services. If your Cloud Run service can reach private network resources, validate an external Agent-backed architecture in a non-production environment before using it for feature flag delivery. +Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Use Agent Remote Configuration on that site. -### Google Cloud Run functions and Cloud Functions +## Environment notes + +### AWS Lambda -Cloud Run functions and Cloud Functions do not support direct Feature Flags server SDK payload delivery. If your networking model allows access to a private Agent endpoint, validate the Agent-backed architecture before relying on it. Otherwise, rely on application defaults. +Java and Node.js Lambda functions can use agentless configuration delivery when they run the minimum SDK versions and can reach Datadog over HTTPS. The Datadog Lambda Extension is not required for flag configuration, but you can continue to use it for supported serverless telemetry. -### Azure Functions +### Google Cloud serverless environments -Azure Functions do not support direct Feature Flags server SDK payload delivery. If the function app can reach private Azure infrastructure, validate an Agent-backed architecture with the Agent on an Azure VM, AKS, or another supported stateful compute environment. +Java and Node.js workloads can use agentless configuration delivery when the tracer is supported in the selected runtime and outbound HTTPS is available. This applies independently of in-container or sidecar telemetry instrumentation. -### AWS Fargate and container tasks +### Azure functions -If your serverless container environment lets you run a Datadog Agent sidecar or otherwise connect to a supported Agent, use the standard server SDK setup. In this model, the task or service behaves like any other application connected to an Agent with Remote Configuration enabled. +Java and Node.js function apps can use agentless configuration delivery when the tracer is supported and outbound HTTPS is available. An external Agent is only required when `remote_config` is selected. -### Managed edge and function platforms +### Edge runtimes -Platforms such as Vercel Functions, Netlify Functions, and Cloudflare Workers do not provide a supported Agent runtime or private Agent connection model for Feature Flags server SDKs. These platforms are not supported for server-side Feature Flags payload delivery. +Some edge runtimes do not support the Datadog Java or Node.js tracer APIs required by the Feature Flags provider. Verify tracer compatibility for the target platform before relying on agentless configuration delivery. ## Public API and local evaluation -The public [Feature Flags API][3] is intended for managing flags and environments. It is not a per-request flag evaluation API for server-side applications. +The public [Feature Flags API][5] is intended for managing flags and environments. It is not a per-request flag evaluation API for server-side applications. -Do not query Datadog APIs from each serverless invocation to evaluate flags. Use the server SDK with an Agent-backed Remote Configuration path when available. If no Agent path is available, use application-owned defaults or static configuration. This fallback is outside Remote Configuration delivery and does not provide signed payload validation or live updates. +Do not query Datadog APIs from each serverless invocation to evaluate flags. Use the server SDK, which periodically loads UFC and evaluates locally. -## Validate the Agent-backed architecture +## Validate your setup -Before using an external Agent endpoint for serverless feature flag delivery: +Before enabling agentless Feature Flags in production: -1. Verify that the Agent has Remote Configuration enabled with `datadog-agent status`. -2. Confirm that the serverless workload can connect to the Agent trace endpoint. +1. Confirm the application uses the minimum Java or Node.js SDK version. +2. Confirm the application has `DD_API_KEY`, `DD_ENV`, and the correct `DD_SITE`. 3. Initialize the OpenFeature provider and check that it reaches a ready state. -4. Change a non-production flag in Datadog and confirm that the serverless workload receives the updated value after the Remote Configuration polling interval. +4. Change a non-production flag in Datadog and confirm that the workload receives the updated value after the polling interval. +5. Confirm that your application handles caller-provided defaults if configuration is unavailable during a cold start. +6. Do not use exposure or aggregate `flagevaluation` data as a readiness check for a no-Agent deployment; those events do not have an agentless delivery path in the initial releases. ## Further reading @@ -116,4 +134,6 @@ Before using an external Agent endpoint for serverless feature flag delivery: [1]: /remote_configuration/ [2]: /feature_flags/server/ -[3]: /api/latest/feature-flags/ +[3]: /feature_flags/server/java/ +[4]: /feature_flags/server/nodejs/ +[5]: /api/latest/feature-flags/ diff --git a/content/en/feature_flags/server/_index.md b/content/en/feature_flags/server/_index.md index 6a787d1dee8..43fbc753193 100644 --- a/content/en/feature_flags/server/_index.md +++ b/content/en/feature_flags/server/_index.md @@ -17,15 +17,36 @@ further_reading: - link: "/feature_flags/implementation_patterns/serverless/" tag: "Documentation" text: "Serverless environments and Feature Flags" +- link: "/feature_flags/concepts/configuration_sources/" + tag: "Concept" + text: "Server SDK Configuration Sources" --- ## Overview -Datadog Feature Flags for server-side applications allow you to remotely control feature availability, run experiments, and roll out new functionality with confidence. Server-side SDKs integrate with the Datadog tracer for your language and use Remote Configuration to receive flag updates in real time. +Datadog Feature Flags for server-side applications allow you to remotely control feature availability, run experiments, and roll out new functionality with confidence. Server-side SDKs integrate with the Datadog tracer for your language, receive Universal Flag Configuration (UFC), and evaluate flags locally. + +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. If you're new to OpenFeature concepts like providers, evaluation context, and hooks, see the [OpenFeature concepts documentation](https://openfeature.dev/docs/category/concepts). + +## Configuration delivery + +Agentless configuration delivery is the default in server SDK versions that support it. The SDK fetches UFC directly from the Datadog-managed CDN over HTTPS, then evaluates flags locally. A Datadog Agent is not required for flag configuration. + +Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` to explicitly use Agent Remote Configuration instead. See [Server SDK Configuration Sources][6] for architecture, security, and operational details. + +| SDK | Minimum agentless version | +|---|---| +| Java (`dd-java-agent` and `dd-openfeature`) | 1.65.0 | +| Node.js `dd-trace` v5 | 5.116.0 | +| Node.js `dd-trace` v6 | 6.5.0 | + +
The initial agentless releases support configuration delivery and local flag evaluation. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
-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. If you're new to OpenFeature concepts like providers, evaluation context, and hooks, see the [OpenFeature concepts documentation](https://openfeature.dev/docs/category/concepts). +Agentless delivery is available for Java and Node.js in the versions listed. Other server SDKs use Agent Remote Configuration until their language pages list an agentless minimum version. -This guide covers the common setup required for all server-side SDKs, including Agent configuration and application environment variables. Select your language or framework to view SDK-specific setup instructions: +## Choose a language + +Select your language or framework to view SDK-specific setup instructions: {{< card-grid card_width="200px" >}} {{< image-card href="/feature_flags/server/dotnet/" src="integrations_logos/dotnet_text.png" alt=".NET" >}} @@ -37,33 +58,68 @@ This guide covers the common setup required for all server-side SDKs, including {{< image-card href="/feature_flags/server/ruby/" src="integrations_logos/ruby.png" alt="Ruby" >}} {{< /card-grid >}} -For serverless runtimes, see [Serverless Environments][5] for the Agent-based architecture and limitations. +For serverless runtimes, see [Serverless Environments][5] for no-Agent setup, version requirements, and initial telemetry limitations. ## Prerequisites -Before setting up server-side feature flags, ensure you have: +All server SDKs require: -- **Datadog Agent 7.55 or later** installed and running -- **Datadog [API key][2]** configured - **APM tracing** [enabled in your application][4] -- **Remote Configuration** enabled for your organization. Verify this in [{{< ui >}}Organization Settings{{< /ui >}}][3]. +- The language-specific tracer and OpenFeature provider versions listed on the SDK page +- A Datadog [API key][2] + +Source-specific requirements are: + +| Source | Requirements | +|---|---| +| `agentless` (default where supported) | Configure `DD_API_KEY`, `DD_ENV`, and optionally `DD_SITE` in the application process. No Agent is required for flag configuration. | +| `remote_config` | Datadog Agent 7.55 or later with Remote Configuration enabled, the API key configured on the Agent, and Remote Configuration enabled for your organization in [{{< ui >}}Organization Settings{{< /ui >}}][3]. | + +## Agentless configuration + +For Java 1.65.0 and Node.js 5.116.0 or 6.5.0, configure the application process: + +{{< code-block lang="bash" >}} +# Required: Enable the Feature Flags provider +DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true + +# Required for direct configuration delivery +DD_API_KEY= +DD_ENV= + +# Optional: Defaults to datadoghq.com +DD_SITE= + +# Optional: Agentless is the default +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless +{{< /code-block >}} + +See the Java and Node.js pages for dependency versions and language-specific initialization. -## Agent configuration +## Agent remote configuration -Server-side feature flags use [Remote Configuration][1] to deliver flag configurations to your application. Remote Configuration is enabled by default in Agent 7.47.0 and later. If your Agent has Remote Configuration disabled, re-enable it by setting `DD_REMOTE_CONFIGURATION_ENABLED=true` or adding `remote_configuration.enabled: true` to your `datadog.yaml`. +Set the source explicitly to retain Agent-managed delivery: -See the [Remote Configuration documentation][1] for detailed setup instructions across different deployment environments. +{{< code-block lang="bash" >}} +DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +DD_REMOTE_CONFIGURATION_ENABLED=true +{{< /code-block >}} + +Remote Configuration is enabled by default in Agent 7.47.0 and later. If your Agent has Remote Configuration disabled, re-enable it by setting `DD_REMOTE_CONFIGURATION_ENABLED=true` or adding `remote_configuration.enabled: true` to your `datadog.yaml`. -### Polling interval +See the [Remote Configuration documentation][1] for detailed setup instructions across deployment environments. -The Agent polls Datadog for configuration updates at a configurable interval. This interval determines the average time between making a flag change in the UI and the change becoming available to your application. +### Remote configuration polling interval + +The Agent polls Datadog for configuration updates at a configurable interval: {{< code-block lang="bash" >}} -# Optional: Configure polling interval (default: 60s) +# Optional: Configure the Agent polling interval (default: 60s) DD_REMOTE_CONFIGURATION_REFRESH_INTERVAL=10s {{< /code-block >}} -## Application configuration +## Common application configuration Configure your application with the standard Datadog environment variables. These are common across all server-side SDKs: @@ -73,10 +129,6 @@ DD_SERVICE= DD_ENV= DD_VERSION= -# Agent connection (if not using default localhost:8126) -DD_AGENT_HOST=localhost -DD_TRACE_AGENT_PORT=8126 - # Required: Enable the feature flagging provider DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true @@ -86,8 +138,6 @@ DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true
The DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true environment variable is required to enable the feature flagging provider. Java also supports the system property -Ddd.experimental.flagging.provider.enabled=true, and Ruby and Node.js support code-based configuration as an alternative. See the SDK-specific documentation for details.
-
Remote Configuration must be available for server-side Feature Flags. It is enabled by default on Agent 7.47.0 and later. Only set SDK-level Remote Configuration variables (such as DD_REMOTE_CONFIG_ENABLED=true) if your tracer has Remote Configuration disabled and you need to override that setting.
- See Set Up Server-Side Flag Evaluation Metrics to enable the experimental feature_flag.evaluations metric. See Feature Flag Graphs for more information on available graphing. ## Testing with in-memory providers @@ -148,3 +198,4 @@ For percentage-based rollouts and deterministic bucketing, see [Traffic Splittin [3]: https://app.datadoghq.com/organization-settings/remote-config [4]: /tracing/guide/#tutorials-enabling-tracing [5]: /feature_flags/implementation_patterns/serverless/ +[6]: /feature_flags/concepts/configuration_sources/ diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index b3599b73f4d..65d416bab56 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -14,6 +14,9 @@ further_reading: - link: "/feature_flags/concepts/flag_graphs/" tag: "Concept" text: "Feature Flag Graphs" +- link: "/feature_flags/concepts/configuration_sources/" + tag: "Concept" + text: "Server SDK Configuration Sources" ---
Enable Java Feature Flags by setting DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true. The EXPERIMENTAL_ prefix is kept for backwards compatibility; the provider is stable. See the Configuration section for details.
@@ -24,9 +27,9 @@ See Set Up Server 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 Java tracer (`dd-trace-java`) 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. Starting in version 1.65.0, the SDK loads flag configuration directly from the Datadog-managed CDN by default. Agent Remote Configuration remains available through explicit opt-in. -
If you're using Datadog APM and your application already has the Datadog Java SDK and Remote Configuration enabled, skip to Initialize the OpenFeature provider. You only need to add the OpenFeature dependencies and initialize the provider.
+
Java 1.65.0 agentless mode supports configuration delivery and local flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
## Compatibility requirements @@ -34,15 +37,16 @@ The Datadog Feature Flags SDK for Java requires: - **Java 11 or higher** - **Datadog Java SDK** (`dd-java-agent`, added with `-javaagent`): Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) - **Datadog OpenFeature provider** (`com.datadoghq:dd-openfeature`, added as a build dependency): Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) +- **Agentless configuration delivery**: Version **1.65.0** or later for both `dd-java-agent` and `dd-openfeature` - **OpenFeature SDK**: Version **1.20.1** or later -- **Datadog Agent**: Version **7.55 or later** with [Remote Configuration][1] enabled -- **Datadog [API key][7]**: Configured on the Agent (not the application) for Remote Configuration +- **Datadog Agent**: Version **7.55 or later** with [Remote Configuration][1] enabled, only when `remote_config` is selected +- **Datadog [API key][7]**: Configured in the application for agentless delivery, or on the Agent for Remote Configuration For a full list of Datadog's Java version and framework support, read [Compatibility Requirements](/tracing/trace_collection/compatibility/java/). ## Getting started -Before you begin, make sure you've already [installed and configured the Agent](/tracing/trace_collection/automatic_instrumentation/dd_libraries/java/#install-and-configure-the-agent). +Before you begin, choose a [configuration source][9]. Agentless is the default starting in Java 1.65.0 and does not require an Agent for flag configuration. Use `remote_config` to explicitly retain Agent-managed delivery. ## Installation @@ -58,7 +62,7 @@ dependencies { implementation 'dev.openfeature:sdk:1.20.1' // Datadog OpenFeature Provider - implementation 'com.datadoghq:dd-openfeature:1.63.0' + implementation 'com.datadoghq:dd-openfeature:1.65.0' } {{< /code-block >}} {{% /tab %}} @@ -72,7 +76,7 @@ dependencies { implementation("dev.openfeature:sdk:1.20.1") // Datadog OpenFeature Provider - implementation("com.datadoghq:dd-openfeature:1.63.0") + implementation("com.datadoghq:dd-openfeature:1.65.0") } {{< /code-block >}} {{% /tab %}} @@ -93,7 +97,7 @@ Add the following dependencies to your `pom.xml`: com.datadoghq dd-openfeature - 1.63.0 + 1.65.0 {{< /code-block >}} @@ -106,26 +110,9 @@ To emit flag evaluation metrics (the `feature_flag.evaluations` metric), add the ## Configuration -If your Datadog Agent already has Remote Configuration enabled for other features (like Dynamic Instrumentation or Application Security), you can skip the Agent configuration and go directly to [Application configuration](#application-configuration). - -### Agent configuration - -Configure your Datadog Agent to enable Remote Configuration: - -{{< code-block lang="yaml" filename="datadog.yaml" >}} -# Enable Remote Configuration -remote_configuration: - enabled: true - -# Set your API key -api_key: -{{< /code-block >}} - -### Application configuration - -If your application already runs with `-javaagent:dd-java-agent.jar` and Remote Configuration is available, you only need to add the feature flagging variable (`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true`). Skip the SDK download and JVM configuration steps. +### Agentless configuration (default) -Configure your Java application with the required environment variables or system properties: +Java 1.65.0 and later use agentless configuration delivery by default. Configure the API key, site, and environment in the application process. A Datadog Agent is not required for flag configuration. {{< tabs >}} {{% tab "Environment Variables" %}} @@ -134,15 +121,23 @@ Configure your Java application with the required environment variables or syste # The EXPERIMENTAL_ prefix is historical; the provider is no longer experimental. export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true -# Optional: Enable flag evaluation metrics -# See "Set Up Server-Side Flag Evaluation Metrics" documentation +# Required for agentless configuration delivery +export DD_API_KEY= +export DD_ENV= + +# Optional: Defaults to datadoghq.com +export DD_SITE= + +# Optional: Agentless is the default +export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless + +# Optional: Agentless polling controls +export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS=30 +export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS=2 # Required: Service name export DD_SERVICE= -# Required: Environment (e.g., prod, staging, dev) -export DD_ENV= - # Optional: Version export DD_VERSION= @@ -153,21 +148,47 @@ java -javaagent:path/to/dd-java-agent.jar -jar your-application.jar {{% tab "System Properties" %}} {{< code-block lang="bash" >}} +# API keys are accepted from environment variables or files, not JVM system properties. +export DD_API_KEY= + java -javaagent:path/to/dd-java-agent.jar \ -Ddd.experimental.flagging.provider.enabled=true \ - -Ddd.service= \ -Ddd.env= \ + -Ddd.site= \ + -Ddd.feature.flags.configuration.source=agentless \ + -Ddd.service= \ -Ddd.version= \ -jar your-application.jar {{< /code-block >}} {{% /tab %}} {{< /tabs >}} -The Datadog feature flagging system starts automatically when the tracer is initialized with Remote Configuration available and the feature flagging provider enabled. No additional initialization code is required in your application. +The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. -
Feature flagging requires DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true and Remote Configuration connectivity. Without the provider setting, the feature flagging system does not start and the Provider returns the programmatic default.
+
Feature flagging requires DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true. Without this setting, the feature flagging system does not start and the Provider returns the programmatic default.
-
Remote Configuration must be available for server-side Feature Flags. It is enabled by default on Agent 7.47.0 and later. Only set SDK-level Remote Configuration variables (such as DD_REMOTE_CONFIG_ENABLED=true) if your tracer has Remote Configuration disabled and you need to override that setting.
+
In Java 1.65.0, agentless mode supports flag evaluation but does not provide agentless delivery for exposure events or aggregate flagevaluation events.
+ +### Agent remote configuration + +To retain Agent-managed delivery, set the source to `remote_config`: + +{{< code-block lang="bash" >}} +export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +export DD_REMOTE_CONFIGURATION_ENABLED=true +{{< /code-block >}} + +Configure your Datadog Agent to enable Remote Configuration: + +{{< code-block lang="yaml" filename="datadog.yaml" >}} +remote_configuration: + enabled: true + +api_key: +{{< /code-block >}} + +Remote Configuration is enabled by default on Agent 7.47.0 and later. Agent 7.55 or later is required for Feature Flags. ### Add the Java tracer to the JVM @@ -217,9 +238,9 @@ public class App { } {{< /code-block >}} -Use `setProviderAndWait()` to block evaluation until the initial flag configuration is received from Remote Configuration. This helps ensure flags are ready before the application starts serving traffic. The default timeout is 30 seconds. +Use `setProviderAndWait()` to block evaluation until the selected configuration source provides the initial flag configuration. This makes flag values available before the application starts serving traffic. The default timeout is 30 seconds. -`ProviderNotReadyError` is an OpenFeature SDK exception thrown when the provider times out during initialization. Catching it allows the application to start with default flag values if Remote Configuration is unavailable. If not caught, the exception propagates and may prevent application startup. Handle this based on your availability requirements. +`ProviderNotReadyError` is an OpenFeature SDK exception thrown when the provider times out during initialization. Catching it allows the application to start with default flag values if configuration delivery is unavailable. If not caught, the exception propagates and may prevent application startup. Handle this based on your availability requirements. ### Asynchronous initialization @@ -394,7 +415,7 @@ api.setProviderAndWait(new Provider(options)); ### Configuration change events -Listen for configuration updates from Remote Configuration: +Listen for updates from the selected configuration source: {{< code-block lang="java" >}} import dev.openfeature.sdk.ProviderEvent; @@ -557,7 +578,7 @@ In Spring Boot tests, register the `InMemoryProvider` through a `@TestConfigurat ## Troubleshooting -This guide follows the flag data path from the **Flagging Platform** (where flags are configured) through **Remote Configuration** and the **Datadog Agent** to the **Java SDK**, and back to the **Flagging Platform** (where evaluations and exposures appear). Work through each step in sequence to isolate where a problem originates. +Follow the flag data path from the **Flagging Platform** through the selected configuration source to the **Java SDK**. Agentless and Remote Configuration have different prerequisites, so verify the active source before troubleshooting connectivity. ### 1. Flagging platform: Verify flag configuration @@ -567,31 +588,26 @@ Before checking infrastructure, confirm the flag itself is set up correctly: 2. The flag targets the **correct environment** (`DD_ENV`). Flags do not target specific services—they apply to all services within the enabled environment. 3. Your `DD_ENV` value appears in [{{< ui >}}Feature Flag Environments{{< /ui >}}][5]. If it is absent, the environment has not received any flag traffic yet. -### 2. Remote Configuration: Verify the path - -Remote Configuration delivers flag configurations from the Datadog backend to the Agent. +### 2. Verify the configuration source -1. **RC is enabled on the Agent**: Agent 7.47.0 and later enable Remote Configuration by default. If it has been disabled, set `remote_configuration.enabled: true` in `datadog.yaml` or `DD_REMOTE_CONFIGURATION_ENABLED=true`. See [Remote Configuration][1]. -2. **`DD_API_KEY` is valid on the Agent** and belongs to the target organization. -3. **`DD_SITE` is set correctly** on the Agent (`site` in `datadog.yaml` or `DD_SITE` env var). See [Agent Site Issues][3]. -4. **Fleet Automation**: Open [{{< ui >}}Fleet Automation{{< /ui >}}][4], select the Agent your application connects to, and confirm Remote Configuration is active. -5. **Agent CLI**: Run `datadog-agent status` and review the Remote Configuration section of the output. See [Agent Commands][6]. +#### Agentless -### 3. Agent: Verify Agent health and connectivity +1. Confirm both `dd-java-agent` and `dd-openfeature` are version 1.65.0 or later. +2. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` is unset or set to `agentless`. +3. Confirm `DD_API_KEY`, `DD_ENV`, and `DD_SITE` are configured in the application process. +4. Confirm the application can make outbound HTTPS requests to Datadog. +5. Enable `DD_TRACE_DEBUG=true` and check for authentication, timeout, or malformed-payload messages from the Feature Flagging agentless endpoint. -1. **Agent is running and reachable**: See [APM Connection Errors][2] for steps to verify Agent connectivity from the tracer. -2. **Agent version**: Feature flagging requires Agent 7.55 or later with EVP Proxy support. -3. **EVP proxy is available**: Query the Agent's info endpoint and confirm the response includes `evp_proxy/v4/` and `v0.7/config` in the `endpoints` array: - ```bash - curl http://localhost:8126/info - ``` +#### Agent remote configuration - If the Agent logs show the following error, the Agent either started after the tracer connected or does not support EVP Proxy. In this case, check the Agent version and restart order. - ``` - Cannot create backend API client since Agentless mode is disabled, and agent does not support EVP proxy - ``` +1. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` is set in the application. +2. Confirm Agent 7.55 or later is running and reachable. See [APM Connection Errors][2]. +3. Confirm Remote Configuration is enabled on the Agent. If it has been disabled, set `remote_configuration.enabled: true` in `datadog.yaml` or `DD_REMOTE_CONFIGURATION_ENABLED=true`. See [Remote Configuration][1]. +4. Confirm `DD_API_KEY` is valid on the Agent and belongs to the target organization. +5. Confirm `DD_SITE` is set correctly on the Agent. See [Agent Site Issues][3]. +6. Run `datadog-agent status` and review the Remote Configuration section. See [Agent Commands][6]. -### 4. SDK: Verify Java SDK state +### 3. Verify Java SDK state #### Enable debug logging @@ -602,12 +618,6 @@ All feature flagging startup messages are emitted at DEBUG level. Set `DD_TRACE_ [dd.trace] Feature Flagging system started ``` -Then confirm the EVP Proxy and config endpoints were discovered: - -``` -discovered ... evpProxyEndpoint=evp_proxy/v4/ configEndpoint=v0.7/config -``` - If these messages are absent, verify `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` is set and the tracer started correctly. #### Monitor provider state changes @@ -634,17 +644,17 @@ client.on(ProviderEvent.PROVIDER_CONFIGURATION_CHANGED, (event) -> { }); {{< /code-block >}} -A `PROVIDER_ERROR` or `PROVIDER_STALE` event after a period of normal operation indicates a loss of connectivity to the Agent or a Remote Configuration disruption. +A `PROVIDER_ERROR` or `PROVIDER_STALE` event after a period of normal operation indicates a disruption in the selected configuration source. #### Provider not ready -`PROVIDER_NOT_READY` is returned when flag evaluation is attempted before the provider has received its first configuration from Remote Configuration. This state persists until the tracer receives its initial flag configuration payload from the Agent. +`PROVIDER_NOT_READY` is returned when flag evaluation is attempted before the provider has received its first configuration from the selected source. Common causes: -- **Async initialization**: `setProvider()` was used instead of `setProviderAndWait()`. Evaluations that happen before the first Remote Configuration payload arrives return `PROVIDER_NOT_READY`. +- **Async initialization**: `setProvider()` was used instead of `setProviderAndWait()`. Evaluations that happen before the first configuration arrives return `PROVIDER_NOT_READY`. - **Initialization timeout**: `setProviderAndWait()` timed out (default 30 seconds) and threw `ProviderNotReadyError`, which was caught. The application continues evaluating flags while waiting for the first configuration. -Remote Configuration sync can take 30-60 seconds after publishing flags. If `PROVIDER_NOT_READY` persists beyond that, re-check steps 2 and 3. +If `PROVIDER_NOT_READY` persists beyond the source's polling and initialization interval, re-check steps 2 and 3. #### Debug flag evaluations @@ -667,7 +677,9 @@ Review `reason` and `errorCode` to understand why the provider returned a given `TYPE_MISMATCH` is returned when the evaluation method does not match the flag's configured type. Use the correct method for each flag type: `getBooleanValue()`, `getStringValue()`, `getIntegerValue()`, `getDoubleValue()`. -### 5. Flagging platform: Verify data appears in Datadog +### 4. Flagging telemetry + +
Java 1.65.0 does not provide agentless delivery for exposure events or aggregate flagevaluation events. Their absence in a no-Agent deployment is expected and does not indicate that configuration loading or local evaluation failed.
#### Flag evaluation metrics @@ -675,10 +687,10 @@ Flag evaluation counts appear in Datadog as a `feature_flag.evaluations` counter #### Experiment exposures -Exposures appear in Datadog only for flags associated with an experiment. Standard feature flags without an experiment association do not generate exposure events. If exposures are missing: +When using a delivery path that supports exposures, exposures appear in Datadog only for flags associated with an experiment. Standard feature flags without an experiment association do not generate exposure events. If exposures are missing: 1. Verify the flag is associated with an experiment in the Datadog UI. -2. Verify the Agent's `DD_API_KEY` is correct and the Agent is receiving events. +2. Verify the telemetry path's API key and connectivity. ## Further reading @@ -692,3 +704,4 @@ Exposures appear in Datadog only for flags associated with an experiment. Standa [6]: /agent/configuration/agent-commands/ [7]: /account_management/api-app-keys/#api-keys [8]: /feature_flags/guide/server_flag_evaluation_metrics/ +[9]: /feature_flags/concepts/configuration_sources/ diff --git a/content/en/feature_flags/server/nodejs.md b/content/en/feature_flags/server/nodejs.md index 9547ed69fc1..376a1c157ba 100644 --- a/content/en/feature_flags/server/nodejs.md +++ b/content/en/feature_flags/server/nodejs.md @@ -17,19 +17,25 @@ further_reading: - link: "/feature_flags/concepts/flag_graphs/" tag: "Concept" text: "Feature Flag Graphs" +- link: "/feature_flags/concepts/configuration_sources/" + tag: "Concept" + text: "Server SDK Configuration Sources" --- ## 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 receives flag updates through Remote Configuration in the Datadog Node.js tracer (`dd-trace`). +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. Starting in `dd-trace` 5.116.0 and 6.5.0, it loads flag configuration directly from the Datadog-managed CDN by default. Agent Remote Configuration remains available through explicit opt-in. + +
Agentless mode in Node.js 5.116.0 and 6.5.0 supports configuration delivery and local flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
## Prerequisites -Before setting up the Node.js Feature Flags SDK, ensure you have: +Before setting up the Node.js Feature Flags SDK, verify these requirements: -- **Datadog Agent** version 7.55 or later with [Remote Configuration](/agent/remote_config/) enabled. See [Agent Configuration](/feature_flags/server#agent-configuration) for details. -- **Datadog [API key][3]** configured on the Agent -- **Datadog Node.js SDK** `dd-trace` version 5.80.0 or later +- **Datadog Node.js SDK** `dd-trace` version 5.80.0 or later for Feature Flags +- **Agentless configuration delivery**: `dd-trace` version **5.116.0 or later on the v5 release line**, or **6.5.0 or later on the v6 release line** +- **Datadog Agent** version 7.55 or later with [Remote Configuration](/agent/remote_config/) enabled, only when `remote_config` is selected +- **Datadog [API key][3]** configured in the application for agentless delivery, or on the Agent for Remote Configuration - **@openfeature/server-sdk** version ~1.20.0 ## Installing and initializing @@ -40,25 +46,55 @@ Feature Flagging is provided by Application Performance Monitoring (APM). To int npm install dd-trace @openfeature/server-sdk ``` -Enable the provider with environment variables: +If your application stays on the v5 release line, use `dd-trace@^5.116.0`. On the v6 release line, use `dd-trace@^6.5.0`. + +### Agentless configuration (default) + +Configure the application process with: ```shell # Required: Enable the feature flags provider DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true -# Required: Enable Remote Configuration in the tracer -DD_REMOTE_CONFIGURATION_ENABLED=true +# Required for agentless configuration delivery +DD_API_KEY= +DD_ENV= + +# Optional: Defaults to datadoghq.com +DD_SITE= + +# Optional: Agentless is the default +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless + +# Optional: Agentless polling controls +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS=30 +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS=2 # Optional: Enable flag evaluation metrics DD_METRICS_OTEL_ENABLED=true # Required: Service identification DD_SERVICE= -DD_ENV= ```
The EXPERIMENTAL_ prefix is retained for backwards compatibility; the provider itself is stable.
+The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. + +
In Node.js 5.116.0 and 6.5.0, agentless mode supports flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events.
+ +### Agent remote configuration + +To retain Agent-managed delivery, configure: + +```shell +DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +DD_REMOTE_CONFIGURATION_ENABLED=true +``` + +This mode requires Datadog Agent 7.55 or later with Remote Configuration enabled and the API key configured on the Agent. + To configure `feature_flag.evaluations`, including the required tracer version and Agent OTLP setup, see [Set Up Server-Side Flag Evaluation Metrics][4]. For more information on available graphing, see [Feature Flag Graphs][5]. Or enable the provider in code: @@ -71,11 +107,13 @@ tracer.init({ experimental: { flaggingProvider: { enabled: true, + // Optional because agentless is the default. + configurationSource: 'agentless', } } }); -// setProviderAndWait resolves after Remote Configuration loads, so flags +// setProviderAndWait resolves after the selected source loads, so flags // evaluate against real configuration data instead of default values. try { await OpenFeature.setProviderAndWait(tracer.openfeature); @@ -107,7 +145,7 @@ Blocking startup until the provider is ready, as shown above, works well for mos ### Accepting default values before initialization -When responsiveness during startup matters more than serving real values for the first few requests, you can call `setProvider` without waiting for initialization. `setProvider` is synchronous, so the client returns default values until Remote Configuration loads in the background. +When responsiveness during startup matters more than serving real values for the first few requests, you can call `setProvider` without waiting for initialization. `setProvider` is synchronous, so the client returns default values until the selected configuration source loads in the background. ```javascript OpenFeature.setProvider(tracer.openfeature); @@ -264,7 +302,7 @@ const priceMultiplier = await client.getNumberValue( ### Object flags -For structured JSON data, use `getObjectValue()`. This method returns an `object`, which can represent primitives, arrays, or dictionaries. Object flags are useful for Remote Configuration scenarios where multiple properties need to be provided together. +For structured JSON data, use `getObjectValue()`. This method returns an `object`, which can represent primitives, arrays, or dictionaries. Object flags are useful when multiple properties need to be provided together. ```javascript const defaultConfig = { From 74d3ab1570ef2be1533222be044cd1c7918eca07 Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Fri, 17 Jul 2026 19:12:06 -0400 Subject: [PATCH 2/3] docs(feature-flags): clarify activation and RC migration --- .../concepts/configuration_sources.md | 49 ++++++++++++++--- .../implementation_patterns/serverless.md | 14 +++-- content/en/feature_flags/server/_index.md | 19 ++++--- content/en/feature_flags/server/java.md | 55 +++++++++++-------- content/en/feature_flags/server/nodejs.md | 38 +++++++------ 5 files changed, 115 insertions(+), 60 deletions(-) diff --git a/content/en/feature_flags/concepts/configuration_sources.md b/content/en/feature_flags/concepts/configuration_sources.md index db0f47bbbbc..0690547e28f 100644 --- a/content/en/feature_flags/concepts/configuration_sources.md +++ b/content/en/feature_flags/concepts/configuration_sources.md @@ -17,10 +17,10 @@ Datadog Feature Flags server SDKs evaluate flags locally from Universal Flag Con ## Configuration source modes -| Mode | Configuration delivery | Agent requirement | When to use | +| Mode | Configuration delivery | Activation | Agent requirement | |---|---|---|---| -| `agentless` (default) | The SDK periodically fetches UFC from the Datadog-managed CDN over HTTPS. | No Datadog Agent is required for flag configuration. | The default for supported server SDK versions, including serverless environments. | -| `remote_config` | The Datadog Agent receives UFC through Remote Configuration and delivers it to the SDK. | Requires an Agent with Remote Configuration enabled. | Use when you explicitly want Agent-managed delivery. | +| `agentless` (default) | The SDK periodically fetches UFC from the Datadog-managed CDN over HTTPS. | Polling begins when application code initializes or accesses the Datadog OpenFeature provider. | No Datadog Agent is required for flag configuration. | +| `remote_config` | The Datadog Agent receives UFC through Remote Configuration and delivers it to the SDK. | Setting `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` enables the Feature Flags Remote Configuration subscription. | Requires an Agent with Remote Configuration enabled. | Agentless delivery is available in these SDK versions: @@ -34,6 +34,28 @@ Earlier Java and Node.js releases continue to use Agent Remote Configuration. Up
The initial agentless releases support configuration delivery and local flag evaluation. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+## Activation and billing + +Server Feature Flags billing is based on configuration requests made through Remote Configuration or the CDN. Installing the tracer does not activate either delivery path by itself. + +- The default source is `agentless`, but CDN polling starts only when application code initializes or accesses the Datadog OpenFeature provider. +- Explicitly selecting `remote_config` starts the existing Agent `FFE_FLAGS` subscription. It does not require application code to initialize the provider. +- `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` defaults to `true`. This setting allows the provider to operate, but setting it to `true` does not activate a delivery path by itself. +- Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider, CDN polling, and the Feature Flags Remote Configuration subscription. + +The SDK resolves these settings once during initialization. You cannot change configuration sources without restarting the application. + +### Configuration precedence + +| Configuration | Result | +|---|---| +| `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` | Disables the provider and both delivery paths, regardless of other settings. | +| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` | Selects CDN delivery. Polling begins when application code initializes or accesses the provider. | +| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` | Selects Agent delivery and enables the Feature Flags Remote Configuration subscription. | +| No source and `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` | Preserves Remote Configuration during the migration window. | +| No source and `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false` | Keeps the provider and both delivery paths disabled. | +| Neither setting is present | Selects agentless delivery. Polling begins when application code initializes or accesses the provider. | + ## Agentless delivery Agentless mode is the default in SDK versions that support it. You do not need to set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` unless you want to make the selection explicit. @@ -41,9 +63,6 @@ Agentless mode is the default in SDK versions that support it. You do not need t Configure the application process with: {{< code-block lang="bash" >}} -# Required: Enable the Feature Flags provider -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true - # Required for agentless configuration delivery DD_API_KEY= DD_ENV= @@ -55,6 +74,10 @@ DD_SITE= DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless {{< /code-block >}} +Initialize or access the Datadog OpenFeature provider in application code to start polling. Tracer installation and tracer initialization alone do not create Feature Flags CDN traffic. + +
For a new agentless setup, do not set DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true. During the migration window, that legacy setting selects Remote Configuration when no explicit source is set.
+ The SDK fetches configuration in the background and evaluates flags locally. Individual flag evaluations do not make network requests. The agentless source: - polls every 30 seconds by default; @@ -79,13 +102,25 @@ Datadog-managed agentless delivery is not available for Datadog for Government i Set the source to `remote_config` to use Agent-managed delivery: {{< code-block lang="bash" >}} -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config DD_REMOTE_CONFIGURATION_ENABLED=true {{< /code-block >}} Configure the API key on the Agent, not in the application process. See [Remote Configuration][1] for Agent setup and network requirements. +## Migrate from the legacy provider setting + +`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. During a migration window, the SDK preserves the behavior of existing customers who explicitly set it. The removal release and timeline are communicated separately. + +If you set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true`, choose one of these paths: + +- **Stay on Agent Remote Configuration:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. Your API key remains on the Agent. +- **Move to agentless delivery:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, configure `DD_API_KEY`, `DD_ENV`, and `DD_SITE` in the application, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. CDN polling begins when application code initializes or accesses the provider. + +If you set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false`, replace it with `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false`. + +Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` values take precedence over the legacy setting. After the legacy setting is removed, an application without an explicit source uses agentless delivery. Set `remote_config` explicitly before that release if you want to remain on Agent delivery. + ## Future offline mode Offline mode is planned for applications that provide UFC JSON bytes at startup and do not make CDN or Remote Configuration network requests. It is not available in the initial agentless releases. diff --git a/content/en/feature_flags/implementation_patterns/serverless.md b/content/en/feature_flags/implementation_patterns/serverless.md index 4e50379dfa3..884b5998fa1 100644 --- a/content/en/feature_flags/implementation_patterns/serverless.md +++ b/content/en/feature_flags/implementation_patterns/serverless.md @@ -39,10 +39,9 @@ Other server SDKs require Agent Remote Configuration for flag delivery. Earlier Use agentless delivery when the serverless runtime can make outbound HTTPS requests to Datadog: 1. Use a Java or Node.js SDK version listed in [Overview](#overview). -2. Enable the Feature Flags provider and configure the API key, site, and environment in the serverless application: +2. Configure the API key, site, and environment in the serverless application: {{< code-block lang="bash" >}} - DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true DD_API_KEY= DD_ENV= @@ -53,11 +52,13 @@ Use agentless delivery when the serverless runtime can make outbound HTTPS reque DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless {{< /code-block >}} -3. Initialize the OpenFeature provider as described on the [Java][3] or [Node.js][4] setup page. +3. Initialize or access the Datadog OpenFeature provider as described on the [Java][3] or [Node.js][4] setup page. This starts CDN polling. 4. Store `DD_API_KEY` in the serverless platform's secret manager and expose it only to the application process. The SDK polls the Datadog-managed CDN every 30 seconds by default and uses ETags for unchanged configuration. It preserves the last accepted configuration during temporary errors. If no configuration has been accepted, OpenFeature evaluations return the caller-provided default value. +Tracer installation and initialization alone do not start CDN polling. Requests to the CDN contribute to server Feature Flags billing only after application code activates the provider. + Agentless mode removes the Agent dependency for _flag configuration_. It does not change your APM or serverless telemetry setup. You can continue to use the Datadog Lambda Extension, `serverless-init`, an Agent sidecar, or another supported telemetry path independently. ## Agent-backed remote configuration @@ -66,7 +67,6 @@ Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` to explicitly use the {{< code-block lang="bash" >}} # Serverless application -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config DD_AGENT_HOST= DD_TRACE_AGENT_PORT=8126 @@ -82,6 +82,8 @@ DD_SITE= The serverless workload must be able to reach the Agent on a private network, and the Agent must be able to reach Datadog over HTTPS. Do not expose the Agent trace intake publicly. +Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription, even if application code does not initialize the provider. These requests contribute to server Feature Flags billing. + ## Operational considerations - **Cold starts**: Blocking provider initialization waits for the first configuration and can add cold-start latency. Initialize asynchronously if serving caller-provided default values during startup is acceptable. @@ -90,9 +92,12 @@ The serverless workload must be able to reach the Agent on a private network, an - **Flag updates**: Delivery is eventually consistent. Allow for the SDK polling interval and application startup time when testing changes. - **Last-known-good behavior**: After a configuration has been accepted, temporary network failures or malformed responses do not replace it. - **Runtime support**: Agentless configuration removes the Agent requirement, but it does not make an otherwise unsupported Java or Node.js runtime compatible with the tracer. Check the language tracer's compatibility requirements. +- **Kill switch**: Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider and both configuration delivery paths. Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Use Agent Remote Configuration on that site. +If your deployment uses `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`, see [Migrate from the legacy provider setting][6]. + ## Environment notes ### AWS Lambda @@ -137,3 +142,4 @@ Before enabling agentless Feature Flags in production: [3]: /feature_flags/server/java/ [4]: /feature_flags/server/nodejs/ [5]: /api/latest/feature-flags/ +[6]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting diff --git a/content/en/feature_flags/server/_index.md b/content/en/feature_flags/server/_index.md index 43fbc753193..ebbd2deecfe 100644 --- a/content/en/feature_flags/server/_index.md +++ b/content/en/feature_flags/server/_index.md @@ -34,6 +34,8 @@ Agentless configuration delivery is the default in server SDK versions that supp Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` to explicitly use Agent Remote Configuration instead. See [Server SDK Configuration Sources][6] for architecture, security, and operational details. +The default source does not activate Feature Flags traffic for every tracer installation. Agentless polling begins only when application code initializes or accesses the Datadog OpenFeature provider. Explicitly selecting `remote_config` activates the Feature Flags Remote Configuration subscription. Requests through either source contribute to server Feature Flags billing. + | SDK | Minimum agentless version | |---|---| | Java (`dd-java-agent` and `dd-openfeature`) | 1.65.0 | @@ -80,9 +82,6 @@ Source-specific requirements are: For Java 1.65.0 and Node.js 5.116.0 or 6.5.0, configure the application process: {{< code-block lang="bash" >}} -# Required: Enable the Feature Flags provider -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true - # Required for direct configuration delivery DD_API_KEY= DD_ENV= @@ -94,14 +93,13 @@ DD_SITE= DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless {{< /code-block >}} -See the Java and Node.js pages for dependency versions and language-specific initialization. +See the Java and Node.js pages for dependency versions and language-specific initialization. Initializing or accessing the provider starts CDN polling; tracer installation and initialization alone do not. ## Agent remote configuration Set the source explicitly to retain Agent-managed delivery: {{< code-block lang="bash" >}} -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config DD_REMOTE_CONFIGURATION_ENABLED=true {{< /code-block >}} @@ -110,6 +108,8 @@ Remote Configuration is enabled by default in Agent 7.47.0 and later. If your Ag See the [Remote Configuration documentation][1] for detailed setup instructions across deployment environments. +Existing customers who set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` remain on Remote Configuration during a migration window. The setting is deprecated. See [Migrate from the legacy provider setting][7] to remain on Remote Configuration explicitly or move to agentless delivery. + ### Remote configuration polling interval The Agent polls Datadog for configuration updates at a configurable interval: @@ -129,14 +129,14 @@ DD_SERVICE= DD_ENV= DD_VERSION= -# Required: Enable the feature flagging provider -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +# Optional: Disable the provider and both delivery paths +# DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false # Optional: Enable flag evaluation metrics # See "Set Up Server-Side Flag Evaluation Metrics" documentation {{< /code-block >}} -
The DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true environment variable is required to enable the feature flagging provider. Java also supports the system property -Ddd.experimental.flagging.provider.enabled=true, and Ruby and Node.js support code-based configuration as an alternative. See the SDK-specific documentation for details.
+
In the Java and Node.js versions listed above, DD_FEATURE_FLAGGING_PROVIDER_ENABLED defaults to true. Setting it to false is the global kill switch for the provider, CDN polling, and the Feature Flags Remote Configuration subscription. Other server SDKs continue to use the activation settings documented on their language pages.
See Set Up Server-Side Flag Evaluation Metrics to enable the experimental feature_flag.evaluations metric. See Feature Flag Graphs for more information on available graphing. @@ -144,7 +144,7 @@ See Set Up Server 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 Remote Configuration delivery. +- **Integration tests**: Point `DatadogProvider` at a dedicated test environment and control flag values from the Datadog UI. This exercises the real provider and selected configuration source end-to-end. - **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. @@ -199,3 +199,4 @@ For percentage-based rollouts and deterministic bucketing, see [Traffic Splittin [4]: /tracing/guide/#tutorials-enabling-tracing [5]: /feature_flags/implementation_patterns/serverless/ [6]: /feature_flags/concepts/configuration_sources/ +[7]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 65d416bab56..875e1db07db 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -19,7 +19,7 @@ further_reading: text: "Server SDK Configuration Sources" --- -
Enable Java Feature Flags by setting DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true. The EXPERIMENTAL_ prefix is kept for backwards compatibility; the provider is stable. See the Configuration section for details.
+
Java 1.65.0 enables the stable Feature Flags provider by default. Agentless polling begins only when application code initializes or accesses the Datadog OpenFeature provider. The legacy DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED setting is deprecated and preserves Remote Configuration behavior during a migration window.
See Set Up Server-Side Flag Evaluation Metrics to enable the experimental feature_flag.evaluations metric. See Feature Flag Graphs for more information on available graphing. @@ -117,10 +117,6 @@ Java 1.65.0 and later use agentless configuration delivery by default. Configure {{< tabs >}} {{% tab "Environment Variables" %}} {{< code-block lang="bash" >}} -# Required: Enable the feature flagging provider -# The EXPERIMENTAL_ prefix is historical; the provider is no longer experimental. -export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true - # Required for agentless configuration delivery export DD_API_KEY= export DD_ENV= @@ -152,7 +148,6 @@ java -javaagent:path/to/dd-java-agent.jar -jar your-application.jar export DD_API_KEY= java -javaagent:path/to/dd-java-agent.jar \ - -Ddd.experimental.flagging.provider.enabled=true \ -Ddd.env= \ -Ddd.site= \ -Ddd.feature.flags.configuration.source=agentless \ @@ -163,9 +158,11 @@ java -javaagent:path/to/dd-java-agent.jar \ {{% /tab %}} {{< /tabs >}} -The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. +The provider is enabled by default. Initialize it as shown in [Initialize the OpenFeature provider](#initialize-the-openfeature-provider) to begin CDN polling. Installing or initializing the Java tracer alone does not create Feature Flags CDN traffic. + +The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. CDN requests contribute to server Feature Flags billing. -
Feature flagging requires DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true. Without this setting, the feature flagging system does not start and the Provider returns the programmatic default.
+Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider, CDN polling, and the Feature Flags Remote Configuration subscription.
In Java 1.65.0, agentless mode supports flag evaluation but does not provide agentless delivery for exposure events or aggregate flagevaluation events.
@@ -174,7 +171,6 @@ The SDK polls every 30 seconds by default and evaluates flags locally from the l To retain Agent-managed delivery, set the source to `remote_config`: {{< code-block lang="bash" >}} -export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config export DD_REMOTE_CONFIGURATION_ENABLED=true {{< /code-block >}} @@ -190,13 +186,22 @@ api_key: Remote Configuration is enabled by default on Agent 7.47.0 and later. Agent 7.55 or later is required for Feature Flags. +Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription without requiring application code to initialize the provider. Remote Configuration requests contribute to server Feature Flags billing. + +### Migrate from the legacy setting + +`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. The removal version and timeline are communicated separately. During the migration window, setting it to `true` without an explicit source keeps Java on Remote Configuration. + +- To stay on Agent delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove the legacy setting. +- To move to agentless delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, move the API key to the application environment, and remove the legacy setting. +- If you use the legacy setting with `false`, replace it with `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false`. + +After the legacy setting is removed, Java defaults to agentless delivery unless you explicitly select `remote_config`. See [Migrate from the legacy provider setting][10] for the complete precedence table. + ### Add the Java tracer to the JVM For instructions on how to add the `-javaagent` argument to your application server or framework, see [Add the Java SDK to the JVM](/tracing/trace_collection/automatic_instrumentation/dd_libraries/java/#add-the-java-sdk-to-the-jvm). -Make sure to include the feature flagging configuration flag: -- `-Ddd.experimental.flagging.provider.enabled=true` - ## Initialize the OpenFeature provider Initialize the Datadog OpenFeature provider in your application startup code. The provider connects to the feature flagging system running in the Datadog Java tracer. @@ -593,19 +598,22 @@ Before checking infrastructure, confirm the flag itself is set up correctly: #### Agentless 1. Confirm both `dd-java-agent` and `dd-openfeature` are version 1.65.0 or later. -2. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` is unset or set to `agentless`. -3. Confirm `DD_API_KEY`, `DD_ENV`, and `DD_SITE` are configured in the application process. -4. Confirm the application can make outbound HTTPS requests to Datadog. -5. Enable `DD_TRACE_DEBUG=true` and check for authentication, timeout, or malformed-payload messages from the Feature Flagging agentless endpoint. +2. Confirm `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` is not set to `false`. +3. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` is set, or that both source and legacy provider settings are absent. +4. Confirm application code initializes or accesses the Datadog OpenFeature provider. +5. Confirm `DD_API_KEY`, `DD_ENV`, and `DD_SITE` are configured in the application process. +6. Confirm the application can make outbound HTTPS requests to Datadog. +7. Enable `DD_TRACE_DEBUG=true` and check for authentication, timeout, or malformed-payload messages from the Feature Flagging agentless endpoint. #### Agent remote configuration -1. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` is set in the application. -2. Confirm Agent 7.55 or later is running and reachable. See [APM Connection Errors][2]. -3. Confirm Remote Configuration is enabled on the Agent. If it has been disabled, set `remote_configuration.enabled: true` in `datadog.yaml` or `DD_REMOTE_CONFIGURATION_ENABLED=true`. See [Remote Configuration][1]. -4. Confirm `DD_API_KEY` is valid on the Agent and belongs to the target organization. -5. Confirm `DD_SITE` is set correctly on the Agent. See [Agent Site Issues][3]. -6. Run `datadog-agent status` and review the Remote Configuration section. See [Agent Commands][6]. +1. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` is set. During the migration window, legacy `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` with no explicit source also selects Remote Configuration. +2. Confirm `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` is not set to `false`. +3. Confirm Agent 7.55 or later is running and reachable. See [APM Connection Errors][2]. +4. Confirm Remote Configuration is enabled on the Agent. If it has been disabled, set `remote_configuration.enabled: true` in `datadog.yaml` or `DD_REMOTE_CONFIGURATION_ENABLED=true`. See [Remote Configuration][1]. +5. Confirm `DD_API_KEY` is valid on the Agent and belongs to the target organization. +6. Confirm `DD_SITE` is set correctly on the Agent. See [Agent Site Issues][3]. +7. Run `datadog-agent status` and review the Remote Configuration section. See [Agent Commands][6]. ### 3. Verify Java SDK state @@ -618,7 +626,7 @@ All feature flagging startup messages are emitted at DEBUG level. Set `DD_TRACE_ [dd.trace] Feature Flagging system started ``` -If these messages are absent, verify `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` is set and the tracer started correctly. +If these messages are absent, confirm `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` is not `false` and verify the activation step for the selected source. #### Monitor provider state changes @@ -705,3 +713,4 @@ When using a delivery path that supports exposures, exposures appear in Datadog [7]: /account_management/api-app-keys/#api-keys [8]: /feature_flags/guide/server_flag_evaluation_metrics/ [9]: /feature_flags/concepts/configuration_sources/ +[10]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting diff --git a/content/en/feature_flags/server/nodejs.md b/content/en/feature_flags/server/nodejs.md index 376a1c157ba..a0f331322e2 100644 --- a/content/en/feature_flags/server/nodejs.md +++ b/content/en/feature_flags/server/nodejs.md @@ -40,7 +40,7 @@ Before setting up the Node.js Feature Flags SDK, verify these requirements: ## Installing and initializing -Feature Flagging is provided by Application Performance Monitoring (APM). To integrate APM into your application with feature flagging support, install `dd-trace` and enable the feature flagging provider. See [Tracing Node.js Applications][1] for detailed APM installation instructions. +Feature Flagging is provided by Application Performance Monitoring (APM). To integrate APM into your application with feature flagging support, install `dd-trace` and initialize the Datadog OpenFeature provider. See [Tracing Node.js Applications][1] for detailed APM installation instructions. ```shell npm install dd-trace @openfeature/server-sdk @@ -53,9 +53,6 @@ If your application stays on the v5 release line, use `dd-trace@^5.116.0`. On th Configure the application process with: ```shell -# Required: Enable the feature flags provider -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true - # Required for agentless configuration delivery DD_API_KEY= DD_ENV= @@ -77,9 +74,11 @@ DD_METRICS_OTEL_ENABLED=true DD_SERVICE= ``` -
The EXPERIMENTAL_ prefix is retained for backwards compatibility; the provider itself is stable.
+The provider is enabled by default. Access `tracer.openfeature` and register it with OpenFeature, as shown below, to begin CDN polling. Installing or initializing `dd-trace` alone does not create Feature Flags CDN traffic. + +The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. CDN requests contribute to server Feature Flags billing. -The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. +Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider, CDN polling, and the Feature Flags Remote Configuration subscription.
In Node.js 5.116.0 and 6.5.0, agentless mode supports flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events.
@@ -88,31 +87,35 @@ The SDK polls every 30 seconds by default and evaluates flags locally from the l To retain Agent-managed delivery, configure: ```shell -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config DD_REMOTE_CONFIGURATION_ENABLED=true ``` This mode requires Datadog Agent 7.55 or later with Remote Configuration enabled and the API key configured on the Agent. +Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription without requiring application code to access the provider. Remote Configuration requests contribute to server Feature Flags billing. + +### Migrate from the legacy setting + +`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. The removal version and timeline are communicated separately. During the migration window, setting it to `true` without an explicit source keeps Node.js on Remote Configuration. + +- To stay on Agent delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove the legacy setting. +- To move to agentless delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, move the API key to the application environment, and remove the legacy setting. +- If you use the legacy setting with `false`, replace it with `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false`. + +After the legacy setting is removed, Node.js defaults to agentless delivery unless you explicitly select `remote_config`. See [Migrate from the legacy provider setting][6] for the complete precedence table. + To configure `feature_flag.evaluations`, including the required tracer version and Agent OTLP setup, see [Set Up Server-Side Flag Evaluation Metrics][4]. For more information on available graphing, see [Feature Flag Graphs][5]. -Or enable the provider in code: +Initialize the provider in code: ```javascript import { OpenFeature } from '@openfeature/server-sdk' import tracer from 'dd-trace'; -tracer.init({ - experimental: { - flaggingProvider: { - enabled: true, - // Optional because agentless is the default. - configurationSource: 'agentless', - } - } -}); +tracer.init(); +// Accessing tracer.openfeature activates the default agentless source. // setProviderAndWait resolves after the selected source loads, so flags // evaluate against real configuration data instead of default values. try { @@ -409,3 +412,4 @@ The snippet above uses Vitest for its first-class ESM support. The same pattern [3]: /account_management/api-app-keys/#api-keys [4]: /feature_flags/guide/server_flag_evaluation_metrics/ [5]: /feature_flags/concepts/flag_graphs/ +[6]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting From d4bf0d2fce3a7d2eba68f9312b74212201ee20cb Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Fri, 17 Jul 2026 21:10:03 -0400 Subject: [PATCH 3/3] docs(feature-flags): simplify agentless setup --- .../concepts/configuration_sources.md | 119 +++++++------ .../implementation_patterns/serverless.md | 18 +- content/en/feature_flags/server/_index.md | 23 +-- content/en/feature_flags/server/java.md | 167 +++++++----------- content/en/feature_flags/server/nodejs.md | 112 ++++++------ 5 files changed, 192 insertions(+), 247 deletions(-) diff --git a/content/en/feature_flags/concepts/configuration_sources.md b/content/en/feature_flags/concepts/configuration_sources.md index 0690547e28f..e130a611095 100644 --- a/content/en/feature_flags/concepts/configuration_sources.md +++ b/content/en/feature_flags/concepts/configuration_sources.md @@ -15,14 +15,9 @@ further_reading: Datadog Feature Flags server SDKs evaluate flags locally from Universal Flag Configuration (UFC). The _configuration source_ determines how the SDK receives UFC; it does not change OpenFeature evaluation semantics. -## Configuration source modes +## Get started with agentless delivery -| Mode | Configuration delivery | Activation | Agent requirement | -|---|---|---|---| -| `agentless` (default) | The SDK periodically fetches UFC from the Datadog-managed CDN over HTTPS. | Polling begins when application code initializes or accesses the Datadog OpenFeature provider. | No Datadog Agent is required for flag configuration. | -| `remote_config` | The Datadog Agent receives UFC through Remote Configuration and delivers it to the SDK. | Setting `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` enables the Feature Flags Remote Configuration subscription. | Requires an Agent with Remote Configuration enabled. | - -Agentless delivery is available in these SDK versions: +Agentless delivery is the default in supported server SDKs. To get started, use one of these minimum versions: | SDK | Minimum version | |---|---| @@ -30,53 +25,47 @@ Agentless delivery is available in these SDK versions: | Node.js `dd-trace` v5 | 5.116.0 | | Node.js `dd-trace` v6 | 6.5.0 | -Earlier Java and Node.js releases continue to use Agent Remote Configuration. Upgrade the language-specific dependencies to the listed minimums before using agentless delivery. +Configure only the API key and environment in the application process: -
The initial agentless releases support configuration delivery and local flag evaluation. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+{{< code-block lang="bash" >}} +DD_API_KEY= +DD_ENV= +{{< /code-block >}} -## Activation and billing +Then initialize or access the Datadog OpenFeature provider in application code. See the [Java][2] or [Node.js][3] setup instructions. -Server Feature Flags billing is based on configuration requests made through Remote Configuration or the CDN. Installing the tracer does not activate either delivery path by itself. +No configuration-source or provider-enable setting is required. Polling begins only when application code initializes or accesses the provider; installing or initializing the tracer alone does not create Feature Flags CDN traffic. -- The default source is `agentless`, but CDN polling starts only when application code initializes or accesses the Datadog OpenFeature provider. -- Explicitly selecting `remote_config` starts the existing Agent `FFE_FLAGS` subscription. It does not require application code to initialize the provider. -- `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` defaults to `true`. This setting allows the provider to operate, but setting it to `true` does not activate a delivery path by itself. -- Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider, CDN polling, and the Feature Flags Remote Configuration subscription. +
The initial agentless releases support configuration delivery and local flag evaluation only. They do not send exposure events or aggregate flagevaluation events in agentless mode.
-The SDK resolves these settings once during initialization. You cannot change configuration sources without restarting the application. +## Advanced configuration -### Configuration precedence +### Choose a configuration source -| Configuration | Result | -|---|---| -| `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` | Disables the provider and both delivery paths, regardless of other settings. | -| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` | Selects CDN delivery. Polling begins when application code initializes or accesses the provider. | -| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` | Selects Agent delivery and enables the Feature Flags Remote Configuration subscription. | -| No source and `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` | Preserves Remote Configuration during the migration window. | -| No source and `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false` | Keeps the provider and both delivery paths disabled. | -| Neither setting is present | Selects agentless delivery. Polling begins when application code initializes or accesses the provider. | - -## Agentless delivery - -Agentless mode is the default in SDK versions that support it. You do not need to set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` unless you want to make the selection explicit. +| Mode | Configuration delivery | Activation | Agent requirement | +|---|---|---|---| +| `agentless` (default) | The SDK periodically fetches UFC from the Datadog-managed CDN over HTTPS. | Polling begins when application code initializes or accesses the Datadog OpenFeature provider. | No Datadog Agent is required for flag configuration. | +| `remote_config` | The Datadog Agent receives UFC through Remote Configuration and delivers it to the SDK. | Selecting `remote_config` enables the Feature Flags Remote Configuration subscription. | Requires an Agent with Remote Configuration enabled. | -Configure the application process with: +Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` only when you want to select a source explicitly: {{< code-block lang="bash" >}} -# Required for agentless configuration delivery -DD_API_KEY= -DD_ENV= - -# Optional: Defaults to datadoghq.com -DD_SITE= - -# Optional: Agentless is the default DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless {{< /code-block >}} -Initialize or access the Datadog OpenFeature provider in application code to start polling. Tracer installation and tracer initialization alone do not create Feature Flags CDN traffic. +The SDK resolves the source once during initialization. Restart the application to change sources. -
For a new agentless setup, do not set DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true. During the migration window, that legacy setting selects Remote Configuration when no explicit source is set.
+### Configure Agentless delivery + +If your organization is not on the default `datadoghq.com` site, set `DD_SITE` in the application process. The agentless source also supports these operational settings: + +| Environment variable | Default | Description | +|---|---|---| +| `DD_SITE` | `datadoghq.com` | Datadog site used to derive the agentless endpoint. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL` | Datadog-managed endpoint | Overrides the agentless backend URL. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Time between completed polling attempts. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `2` | Timeout for an individual configuration request. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_EXTRA_HEADERS` | None | Adds headers to agentless configuration requests. | The SDK fetches configuration in the background and evaluates flags locally. Individual flag evaluations do not make network requests. The agentless source: @@ -86,42 +75,60 @@ The SDK fetches configuration in the background and evaluates flags locally. Ind - preserves the last accepted configuration during temporary network or payload errors; and - prevents overlapping polls. -You can change the operational defaults with these environment variables: - -| Environment variable | Default | Description | -|---|---|---| -| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Time between completed polling attempts. | -| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `2` | Timeout for an individual configuration request. | - Keep `DD_API_KEY` in a secret manager and expose it only to the application process that loads flag configuration. Agentless configuration delivery sends the API key directly from the application to Datadog over HTTPS. Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Applications on that site continue to use caller-provided default values unless they use Agent Remote Configuration. -## Agent remote configuration +### Enable or disable feature flags + +`DD_FEATURE_FLAGS_ENABLED` defaults to `true`, so new setups do not need to set it. Set it to `false` to disable the provider and both configuration delivery paths: + +{{< code-block lang="bash" >}} +DD_FEATURE_FLAGS_ENABLED=false +{{< /code-block >}} + +### Activation and billing + +Server Feature Flags billing is based on configuration requests made through Remote Configuration or the CDN. Installing the tracer does not activate either delivery path by itself. + +- With the default agentless source, CDN polling starts only when application code initializes or accesses the Datadog OpenFeature provider. +- Explicitly selecting `remote_config` starts the Agent Feature Flags subscription. It does not require application code to initialize the provider. + +### Configuration precedence + +| Configuration | Result | +|---|---| +| `DD_FEATURE_FLAGS_ENABLED=false` | Disables the provider and both delivery paths, regardless of other settings. | +| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` | Selects CDN delivery. Polling begins when application code initializes or accesses the provider. | +| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` | Selects Agent delivery and enables the Feature Flags Remote Configuration subscription. | +| No source and `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` | Preserves Remote Configuration during the migration window. | +| No source and `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false` | Keeps the provider and both delivery paths disabled. | +| Neither setting is present | Selects agentless delivery. Polling begins when application code initializes or accesses the provider. | + +### Use Agent remote configuration Set the source to `remote_config` to use Agent-managed delivery: {{< code-block lang="bash" >}} DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config -DD_REMOTE_CONFIGURATION_ENABLED=true {{< /code-block >}} -Configure the API key on the Agent, not in the application process. See [Remote Configuration][1] for Agent setup and network requirements. +Configure the API key on the Agent, not in the application process. If Remote Configuration has been disabled on the Agent, re-enable it. See [Remote Configuration][1] for Agent setup and network requirements. -## Migrate from the legacy provider setting +### Migrate an existing remote configuration setup -`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. During a migration window, the SDK preserves the behavior of existing customers who explicitly set it. The removal release and timeline are communicated separately. +Existing customers who set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` remain on Remote Configuration during a migration window. The setting is deprecated, and its removal version and timeline are communicated separately. If you set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true`, choose one of these paths: - **Stay on Agent Remote Configuration:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. Your API key remains on the Agent. -- **Move to agentless delivery:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, configure `DD_API_KEY`, `DD_ENV`, and `DD_SITE` in the application, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. CDN polling begins when application code initializes or accesses the provider. +- **Move to agentless delivery:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, configure `DD_API_KEY` and `DD_ENV` in the application, and set `DD_SITE` if your organization is not on the default site. Then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. CDN polling begins when application code initializes or accesses the provider. -If you set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false`, replace it with `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false`. +If you set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false`, replace it with `DD_FEATURE_FLAGS_ENABLED=false`. Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` values take precedence over the legacy setting. After the legacy setting is removed, an application without an explicit source uses agentless delivery. Set `remote_config` explicitly before that release if you want to remain on Agent delivery. -## Future offline mode +### Future offline mode Offline mode is planned for applications that provide UFC JSON bytes at startup and do not make CDN or Remote Configuration network requests. It is not available in the initial agentless releases. @@ -130,3 +137,5 @@ Offline mode is planned for applications that provide UFC JSON bytes at startup {{< partial name="whats-next/whats-next.html" >}} [1]: /remote_configuration/ +[2]: /feature_flags/server/java/ +[3]: /feature_flags/server/nodejs/ diff --git a/content/en/feature_flags/implementation_patterns/serverless.md b/content/en/feature_flags/implementation_patterns/serverless.md index 884b5998fa1..e3f74ea211a 100644 --- a/content/en/feature_flags/implementation_patterns/serverless.md +++ b/content/en/feature_flags/implementation_patterns/serverless.md @@ -32,27 +32,23 @@ Agentless configuration delivery is available in: Other server SDKs require Agent Remote Configuration for flag delivery. Earlier Java and Node.js releases also require it. -
Flag evaluation only: The initial agentless releases load configuration and evaluate flags. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+
Flag evaluation only: The initial agentless releases load configuration and evaluate flags locally. They do not send exposure events or aggregate flagevaluation events in agentless mode.
## Default Agentless architecture Use agentless delivery when the serverless runtime can make outbound HTTPS requests to Datadog: 1. Use a Java or Node.js SDK version listed in [Overview](#overview). -2. Configure the API key, site, and environment in the serverless application: +2. Configure the API key and environment in the serverless application: {{< code-block lang="bash" >}} DD_API_KEY= DD_ENV= - - # Optional: Defaults to datadoghq.com - DD_SITE= - - # Optional: Agentless is the default in supported versions - DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless {{< /code-block >}} -3. Initialize or access the Datadog OpenFeature provider as described on the [Java][3] or [Node.js][4] setup page. This starts CDN polling. + If your organization is not on the default `datadoghq.com` site, also set `DD_SITE`. + +3. Initialize or access the Datadog OpenFeature provider as described on the [Java][3] or [Node.js][4] setup page. This starts CDN polling. No Feature Flags enablement or source setting is required. 4. Store `DD_API_KEY` in the serverless platform's secret manager and expose it only to the application process. The SDK polls the Datadog-managed CDN every 30 seconds by default and uses ETags for unchanged configuration. It preserves the last accepted configuration during temporary errors. If no configuration has been accepted, OpenFeature evaluations return the caller-provided default value. @@ -92,7 +88,7 @@ Explicitly selecting `remote_config` enables the Feature Flags Remote Configurat - **Flag updates**: Delivery is eventually consistent. Allow for the SDK polling interval and application startup time when testing changes. - **Last-known-good behavior**: After a configuration has been accepted, temporary network failures or malformed responses do not replace it. - **Runtime support**: Agentless configuration removes the Agent requirement, but it does not make an otherwise unsupported Java or Node.js runtime compatible with the tracer. Check the language tracer's compatibility requirements. -- **Kill switch**: Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider and both configuration delivery paths. +- **Kill switch**: `DD_FEATURE_FLAGS_ENABLED` defaults to `true`. Set it to `false` to disable the provider and both configuration delivery paths. Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Use Agent Remote Configuration on that site. @@ -142,4 +138,4 @@ Before enabling agentless Feature Flags in production: [3]: /feature_flags/server/java/ [4]: /feature_flags/server/nodejs/ [5]: /api/latest/feature-flags/ -[6]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting +[6]: /feature_flags/concepts/configuration_sources/#migrate-an-existing-remote-configuration-setup diff --git a/content/en/feature_flags/server/_index.md b/content/en/feature_flags/server/_index.md index ebbd2deecfe..e34320c245f 100644 --- a/content/en/feature_flags/server/_index.md +++ b/content/en/feature_flags/server/_index.md @@ -32,8 +32,6 @@ Datadog Feature Flags is built on the [OpenFeature standard](https://openfeature Agentless configuration delivery is the default in server SDK versions that support it. The SDK fetches UFC directly from the Datadog-managed CDN over HTTPS, then evaluates flags locally. A Datadog Agent is not required for flag configuration. -Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` to explicitly use Agent Remote Configuration instead. See [Server SDK Configuration Sources][6] for architecture, security, and operational details. - The default source does not activate Feature Flags traffic for every tracer installation. Agentless polling begins only when application code initializes or accesses the Datadog OpenFeature provider. Explicitly selecting `remote_config` activates the Feature Flags Remote Configuration subscription. Requests through either source contribute to server Feature Flags billing. | SDK | Minimum agentless version | @@ -42,7 +40,7 @@ The default source does not activate Feature Flags traffic for every tracer inst | Node.js `dd-trace` v5 | 5.116.0 | | Node.js `dd-trace` v6 | 6.5.0 | -
The initial agentless releases support configuration delivery and local flag evaluation. They do not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+
The initial agentless releases support configuration delivery and local flag evaluation only. They do not send exposure events or aggregate flagevaluation events in agentless mode.
Agentless delivery is available for Java and Node.js in the versions listed. Other server SDKs use Agent Remote Configuration until their language pages list an agentless minimum version. @@ -85,15 +83,9 @@ For Java 1.65.0 and Node.js 5.116.0 or 6.5.0, configure the application process: # Required for direct configuration delivery DD_API_KEY= DD_ENV= - -# Optional: Defaults to datadoghq.com -DD_SITE= - -# Optional: Agentless is the default -DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless {{< /code-block >}} -See the Java and Node.js pages for dependency versions and language-specific initialization. Initializing or accessing the provider starts CDN polling; tracer installation and initialization alone do not. +No Feature Flags enablement or source setting is required. If your organization is not on the default `datadoghq.com` site, also set `DD_SITE`. See the Java and Node.js pages for dependency versions and language-specific initialization. Initializing or accessing the provider starts CDN polling; tracer installation and initialization alone do not. ## Agent remote configuration @@ -101,7 +93,6 @@ Set the source explicitly to retain Agent-managed delivery: {{< code-block lang="bash" >}} DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config -DD_REMOTE_CONFIGURATION_ENABLED=true {{< /code-block >}} Remote Configuration is enabled by default in Agent 7.47.0 and later. If your Agent has Remote Configuration disabled, re-enable it by setting `DD_REMOTE_CONFIGURATION_ENABLED=true` or adding `remote_configuration.enabled: true` to your `datadog.yaml`. @@ -119,7 +110,7 @@ The Agent polls Datadog for configuration updates at a configurable interval: DD_REMOTE_CONFIGURATION_REFRESH_INTERVAL=10s {{< /code-block >}} -## Common application configuration +## Advanced application configuration Configure your application with the standard Datadog environment variables. These are common across all server-side SDKs: @@ -129,14 +120,14 @@ DD_SERVICE= DD_ENV= DD_VERSION= -# Optional: Disable the provider and both delivery paths -# DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false +# Optional: Disable Feature Flags and both delivery paths +# DD_FEATURE_FLAGS_ENABLED=false # Optional: Enable flag evaluation metrics # See "Set Up Server-Side Flag Evaluation Metrics" documentation {{< /code-block >}} -
In the Java and Node.js versions listed above, DD_FEATURE_FLAGGING_PROVIDER_ENABLED defaults to true. Setting it to false is the global kill switch for the provider, CDN polling, and the Feature Flags Remote Configuration subscription. Other server SDKs continue to use the activation settings documented on their language pages.
+
In the Java and Node.js versions listed above, DD_FEATURE_FLAGS_ENABLED defaults to true, so you do not need to set it. Setting it to false disables the provider, CDN polling, and the Feature Flags Remote Configuration subscription. Other server SDKs continue to use the activation settings documented on their language pages.
See Set Up Server-Side Flag Evaluation Metrics to enable the experimental feature_flag.evaluations metric. See Feature Flag Graphs for more information on available graphing. @@ -199,4 +190,4 @@ For percentage-based rollouts and deterministic bucketing, see [Traffic Splittin [4]: /tracing/guide/#tutorials-enabling-tracing [5]: /feature_flags/implementation_patterns/serverless/ [6]: /feature_flags/concepts/configuration_sources/ -[7]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting +[7]: /feature_flags/concepts/configuration_sources/#migrate-an-existing-remote-configuration-setup diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 875e1db07db..b17dd2a06b7 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -19,35 +19,26 @@ further_reading: text: "Server SDK Configuration Sources" --- -
Java 1.65.0 enables the stable Feature Flags provider by default. Agentless polling begins only when application code initializes or accesses the Datadog OpenFeature provider. The legacy DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED setting is deprecated and preserves Remote Configuration behavior during a migration window.
- -See Set Up Server-Side Flag Evaluation Metrics to enable the experimental feature_flag.evaluations metric. See Feature Flag Graphs for more information on available graphing. - ## Overview 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 Java tracer (`dd-trace-java`) and implements the [OpenFeature](https://openfeature.dev/) standard for maximum flexibility and compatibility. Starting in version 1.65.0, the SDK loads flag configuration directly from the Datadog-managed CDN by default. Agent Remote Configuration remains available through explicit opt-in. +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. Starting in version 1.65.0, the SDK loads flag configuration directly from the Datadog-managed CDN by default. -
Java 1.65.0 agentless mode supports configuration delivery and local flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+
Java 1.65.0 supports agentless configuration delivery and local flag evaluation only. It does not send exposure events or aggregate flagevaluation events in agentless mode.
-## Compatibility requirements +## Getting started + +For the default agentless setup, you need: -The Datadog Feature Flags SDK for Java requires: - **Java 11 or higher** -- **Datadog Java SDK** (`dd-java-agent`, added with `-javaagent`): Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) -- **Datadog OpenFeature provider** (`com.datadoghq:dd-openfeature`, added as a build dependency): Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) -- **Agentless configuration delivery**: Version **1.65.0** or later for both `dd-java-agent` and `dd-openfeature` +- **Datadog Java SDK** (`dd-java-agent`, added with `-javaagent`): Version **1.65.0** or later +- **Datadog OpenFeature provider** (`com.datadoghq:dd-openfeature`, added as a build dependency): Version **1.65.0** or later - **OpenFeature SDK**: Version **1.20.1** or later -- **Datadog Agent**: Version **7.55 or later** with [Remote Configuration][1] enabled, only when `remote_config` is selected -- **Datadog [API key][7]**: Configured in the application for agentless delivery, or on the Agent for Remote Configuration +- A Datadog [API key][7] For a full list of Datadog's Java version and framework support, read [Compatibility Requirements](/tracing/trace_collection/compatibility/java/). -## Getting started - -Before you begin, choose a [configuration source][9]. Agentless is the default starting in Java 1.65.0 and does not require an Agent for flag configuration. Use `remote_config` to explicitly retain Agent-managed delivery. - ## Installation Feature flagging is integrated into the Datadog Java SDK. You need the SDK JAR and the OpenFeature SDK dependencies. @@ -104,99 +95,20 @@ Add the following dependencies to your `pom.xml`: {{% /tab %}} {{< /tabs >}} -The Gradle and Maven installation examples pin specific versions of `dd-openfeature` and the OpenFeature SDK. See [Compatibility requirements](#compatibility-requirements) for the minimum supported versions. - -To emit flag evaluation metrics (the `feature_flag.evaluations` metric), add the OpenTelemetry SDK dependencies and configure the OTLP endpoint. See [Set Up Server-Side Flag Evaluation Metrics][8]. - -## Configuration +The Gradle and Maven installation examples pin the minimum supported versions of `dd-openfeature` and the OpenFeature SDK listed in [Getting started](#getting-started). -### Agentless configuration (default) +## Configure Agentless delivery -Java 1.65.0 and later use agentless configuration delivery by default. Configure the API key, site, and environment in the application process. A Datadog Agent is not required for flag configuration. +Java 1.65.0 and later use agentless configuration delivery by default. Configure the API key and environment in the application process: -{{< tabs >}} -{{% tab "Environment Variables" %}} {{< code-block lang="bash" >}} -# Required for agentless configuration delivery export DD_API_KEY= export DD_ENV= -# Optional: Defaults to datadoghq.com -export DD_SITE= - -# Optional: Agentless is the default -export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless - -# Optional: Agentless polling controls -export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS=30 -export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS=2 - -# Required: Service name -export DD_SERVICE= - -# Optional: Version -export DD_VERSION= - -# Start your application with the SDK java -javaagent:path/to/dd-java-agent.jar -jar your-application.jar {{< /code-block >}} -{{% /tab %}} - -{{% tab "System Properties" %}} -{{< code-block lang="bash" >}} -# API keys are accepted from environment variables or files, not JVM system properties. -export DD_API_KEY= - -java -javaagent:path/to/dd-java-agent.jar \ - -Ddd.env= \ - -Ddd.site= \ - -Ddd.feature.flags.configuration.source=agentless \ - -Ddd.service= \ - -Ddd.version= \ - -jar your-application.jar -{{< /code-block >}} -{{% /tab %}} -{{< /tabs >}} - -The provider is enabled by default. Initialize it as shown in [Initialize the OpenFeature provider](#initialize-the-openfeature-provider) to begin CDN polling. Installing or initializing the Java tracer alone does not create Feature Flags CDN traffic. - -The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. CDN requests contribute to server Feature Flags billing. - -Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider, CDN polling, and the Feature Flags Remote Configuration subscription. - -
In Java 1.65.0, agentless mode supports flag evaluation but does not provide agentless delivery for exposure events or aggregate flagevaluation events.
- -### Agent remote configuration - -To retain Agent-managed delivery, set the source to `remote_config`: - -{{< code-block lang="bash" >}} -export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config -export DD_REMOTE_CONFIGURATION_ENABLED=true -{{< /code-block >}} -Configure your Datadog Agent to enable Remote Configuration: - -{{< code-block lang="yaml" filename="datadog.yaml" >}} -remote_configuration: - enabled: true - -api_key: -{{< /code-block >}} - -Remote Configuration is enabled by default on Agent 7.47.0 and later. Agent 7.55 or later is required for Feature Flags. - -Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription without requiring application code to initialize the provider. Remote Configuration requests contribute to server Feature Flags billing. - -### Migrate from the legacy setting - -`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. The removal version and timeline are communicated separately. During the migration window, setting it to `true` without an explicit source keeps Java on Remote Configuration. - -- To stay on Agent delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove the legacy setting. -- To move to agentless delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, move the API key to the application environment, and remove the legacy setting. -- If you use the legacy setting with `false`, replace it with `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false`. - -After the legacy setting is removed, Java defaults to agentless delivery unless you explicitly select `remote_config`. See [Migrate from the legacy provider setting][10] for the complete precedence table. +No Feature Flags enablement or source setting is required. Next, [initialize the OpenFeature provider](#initialize-the-openfeature-provider) to begin polling. Installing or initializing the Java tracer alone does not create Feature Flags CDN traffic. ### Add the Java tracer to the JVM @@ -404,6 +316,51 @@ if (details.getErrorCode() != null) { ## Advanced configuration +### Agentless delivery settings + +Feature Flags are enabled by default. You do not need to set `DD_FEATURE_FLAGS_ENABLED` unless you want to disable Feature Flags explicitly. + +| Environment variable | Default | Description | +|---|---|---| +| `DD_FEATURE_FLAGS_ENABLED` | `true` | Set to `false` to disable the provider and both configuration delivery paths. | +| `DD_SITE` | `datadoghq.com` | Datadog site used to derive the agentless endpoint. Set this when your organization uses another site. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` | `agentless` | Selects `agentless` or `remote_config` delivery. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL` | Datadog-managed endpoint | Overrides the agentless backend URL. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Time between completed polling attempts. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `2` | Timeout for an individual configuration request. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_EXTRA_HEADERS` | None | Adds headers to agentless configuration requests. | + +The SDK polls in the background and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. CDN requests contribute to server Feature Flags billing. + +### Use Agent remote configuration + +To retain Agent-managed delivery, select `remote_config`: + +{{< code-block lang="bash" >}} +export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +{{< /code-block >}} + +Configure the API key on a Datadog Agent 7.55 or later. Remote Configuration is enabled by default on Agent 7.47.0 and later; if it is disabled, enable it in `datadog.yaml`: + +{{< code-block lang="yaml" filename="datadog.yaml" >}} +remote_configuration: + enabled: true + +api_key: +{{< /code-block >}} + +Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription without requiring application code to initialize the provider. Remote Configuration requests contribute to server Feature Flags billing. + +### Migrate an existing remote configuration setup + +Existing customers who set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` remain on Remote Configuration during a migration window. The setting is deprecated, and its removal version and timeline are communicated separately. + +- **Stay on Agent delivery:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. +- **Move to agentless delivery:** Upgrade both `dd-java-agent` and `dd-openfeature` to 1.65.0 or later, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, move the API key and environment to the application process, then remove the legacy setting. +- **Keep Feature Flags disabled:** Replace `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false` with `DD_FEATURE_FLAGS_ENABLED=false`. + +After the legacy setting is removed, Java defaults to agentless delivery unless you explicitly select `remote_config`. See [Server SDK Configuration Sources][10] for the complete precedence table. + ### Custom initialization timeout Configure how long the provider waits for initial configuration: @@ -598,17 +555,17 @@ Before checking infrastructure, confirm the flag itself is set up correctly: #### Agentless 1. Confirm both `dd-java-agent` and `dd-openfeature` are version 1.65.0 or later. -2. Confirm `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` is not set to `false`. +2. Confirm `DD_FEATURE_FLAGS_ENABLED` is not set to `false`. 3. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` is set, or that both source and legacy provider settings are absent. 4. Confirm application code initializes or accesses the Datadog OpenFeature provider. -5. Confirm `DD_API_KEY`, `DD_ENV`, and `DD_SITE` are configured in the application process. +5. Confirm `DD_API_KEY` and `DD_ENV` are configured in the application process. If your organization is not on the default site, confirm `DD_SITE` is also configured. 6. Confirm the application can make outbound HTTPS requests to Datadog. 7. Enable `DD_TRACE_DEBUG=true` and check for authentication, timeout, or malformed-payload messages from the Feature Flagging agentless endpoint. #### Agent remote configuration 1. Confirm `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` is set. During the migration window, legacy `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` with no explicit source also selects Remote Configuration. -2. Confirm `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` is not set to `false`. +2. Confirm `DD_FEATURE_FLAGS_ENABLED` is not set to `false`. 3. Confirm Agent 7.55 or later is running and reachable. See [APM Connection Errors][2]. 4. Confirm Remote Configuration is enabled on the Agent. If it has been disabled, set `remote_configuration.enabled: true` in `datadog.yaml` or `DD_REMOTE_CONFIGURATION_ENABLED=true`. See [Remote Configuration][1]. 5. Confirm `DD_API_KEY` is valid on the Agent and belongs to the target organization. @@ -626,7 +583,7 @@ All feature flagging startup messages are emitted at DEBUG level. Set `DD_TRACE_ [dd.trace] Feature Flagging system started ``` -If these messages are absent, confirm `DD_FEATURE_FLAGGING_PROVIDER_ENABLED` is not `false` and verify the activation step for the selected source. +If these messages are absent, confirm `DD_FEATURE_FLAGS_ENABLED` is not `false` and verify the activation step for the selected source. #### Monitor provider state changes @@ -713,4 +670,4 @@ When using a delivery path that supports exposures, exposures appear in Datadog [7]: /account_management/api-app-keys/#api-keys [8]: /feature_flags/guide/server_flag_evaluation_metrics/ [9]: /feature_flags/concepts/configuration_sources/ -[10]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting +[10]: /feature_flags/concepts/configuration_sources/#configuration-precedence diff --git a/content/en/feature_flags/server/nodejs.md b/content/en/feature_flags/server/nodejs.md index a0f331322e2..fd7eadf2f97 100644 --- a/content/en/feature_flags/server/nodejs.md +++ b/content/en/feature_flags/server/nodejs.md @@ -24,18 +24,16 @@ further_reading: ## 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. Starting in `dd-trace` 5.116.0 and 6.5.0, it loads flag configuration directly from the Datadog-managed CDN by default. Agent Remote Configuration remains available through explicit opt-in. +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. Starting in `dd-trace` 5.116.0 and 6.5.0, it loads flag configuration directly from the Datadog-managed CDN by default. -
Agentless mode in Node.js 5.116.0 and 6.5.0 supports configuration delivery and local flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events. No-Agent deployments do not send those events.
+
Node.js 5.116.0 and 6.5.0 support agentless configuration delivery and local flag evaluation only. They do not send exposure events or aggregate flagevaluation events in agentless mode.
-## Prerequisites +## Getting started -Before setting up the Node.js Feature Flags SDK, verify these requirements: +For the default agentless setup, you need: -- **Datadog Node.js SDK** `dd-trace` version 5.80.0 or later for Feature Flags -- **Agentless configuration delivery**: `dd-trace` version **5.116.0 or later on the v5 release line**, or **6.5.0 or later on the v6 release line** -- **Datadog Agent** version 7.55 or later with [Remote Configuration](/agent/remote_config/) enabled, only when `remote_config` is selected -- **Datadog [API key][3]** configured in the application for agentless delivery, or on the Agent for Remote Configuration +- **Datadog Node.js SDK** `dd-trace` version **5.116.0 or later on the v5 release line**, or **6.5.0 or later on the v6 release line** +- A Datadog [API key][3] - **@openfeature/server-sdk** version ~1.20.0 ## Installing and initializing @@ -48,64 +46,16 @@ npm install dd-trace @openfeature/server-sdk If your application stays on the v5 release line, use `dd-trace@^5.116.0`. On the v6 release line, use `dd-trace@^6.5.0`. -### Agentless configuration (default) +### Configure Agentless delivery -Configure the application process with: +Configure the API key and environment in the application process: ```shell -# Required for agentless configuration delivery DD_API_KEY= DD_ENV= - -# Optional: Defaults to datadoghq.com -DD_SITE= - -# Optional: Agentless is the default -DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless - -# Optional: Agentless polling controls -DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS=30 -DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS=2 - -# Optional: Enable flag evaluation metrics -DD_METRICS_OTEL_ENABLED=true - -# Required: Service identification -DD_SERVICE= ``` -The provider is enabled by default. Access `tracer.openfeature` and register it with OpenFeature, as shown below, to begin CDN polling. Installing or initializing `dd-trace` alone does not create Feature Flags CDN traffic. - -The SDK polls every 30 seconds by default and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. CDN requests contribute to server Feature Flags billing. - -Set `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false` to disable the provider, CDN polling, and the Feature Flags Remote Configuration subscription. - -
In Node.js 5.116.0 and 6.5.0, agentless mode supports flag evaluation. It does not provide agentless delivery for exposure events or aggregate flagevaluation events.
- -### Agent remote configuration - -To retain Agent-managed delivery, configure: - -```shell -DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config -DD_REMOTE_CONFIGURATION_ENABLED=true -``` - -This mode requires Datadog Agent 7.55 or later with Remote Configuration enabled and the API key configured on the Agent. - -Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription without requiring application code to access the provider. Remote Configuration requests contribute to server Feature Flags billing. - -### Migrate from the legacy setting - -`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. The removal version and timeline are communicated separately. During the migration window, setting it to `true` without an explicit source keeps Node.js on Remote Configuration. - -- To stay on Agent delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove the legacy setting. -- To move to agentless delivery, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, move the API key to the application environment, and remove the legacy setting. -- If you use the legacy setting with `false`, replace it with `DD_FEATURE_FLAGGING_PROVIDER_ENABLED=false`. - -After the legacy setting is removed, Node.js defaults to agentless delivery unless you explicitly select `remote_config`. See [Migrate from the legacy provider setting][6] for the complete precedence table. - -To configure `feature_flag.evaluations`, including the required tracer version and Agent OTLP setup, see [Set Up Server-Side Flag Evaluation Metrics][4]. For more information on available graphing, see [Feature Flag Graphs][5]. +No Feature Flags enablement or source setting is required. Access `tracer.openfeature` and register it with OpenFeature, as shown below, to begin polling. Installing or initializing `dd-trace` alone does not create Feature Flags CDN traffic. Initialize the provider in code: @@ -343,6 +293,48 @@ console.log(details.errorMessage); // A more detailed message of the error that console.log(details.flagMetadata); // Additional information about the evaluation ``` +## Advanced configuration + +### Agentless delivery settings + +Feature Flags are enabled by default. You do not need to set `DD_FEATURE_FLAGS_ENABLED` unless you want to disable Feature Flags explicitly. + +| Environment variable | Default | Description | +|---|---|---| +| `DD_FEATURE_FLAGS_ENABLED` | `true` | Set to `false` to disable the provider and both configuration delivery paths. | +| `DD_SITE` | `datadoghq.com` | Datadog site used to derive the agentless endpoint. Set this when your organization uses another site. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` | `agentless` | Selects `agentless` or `remote_config` delivery. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL` | Datadog-managed endpoint | Overrides the agentless backend URL. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Time between completed polling attempts. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `2` | Timeout for an individual configuration request. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_EXTRA_HEADERS` | None | Adds headers to agentless configuration requests. | + +The SDK polls in the background and evaluates flags locally from the last accepted configuration. Individual evaluations do not make network requests. CDN requests contribute to server Feature Flags billing. + +### Use Agent remote configuration + +To retain Agent-managed delivery, configure: + +```shell +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +``` + +This mode requires Datadog Agent 7.55 or later with Remote Configuration enabled and the API key configured on the Agent. If Remote Configuration has been disabled on the Agent, re-enable it. + +Explicitly selecting `remote_config` enables the Feature Flags Remote Configuration subscription without requiring application code to access the provider. Remote Configuration requests contribute to server Feature Flags billing. + +### Migrate an existing remote configuration setup + +Existing customers who set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` remain on Remote Configuration during a migration window. The setting is deprecated, and its removal version and timeline are communicated separately. + +- **Stay on Agent delivery:** Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. +- **Move to agentless delivery:** Upgrade `dd-trace` to 5.116.0 or later on v5, or 6.5.0 or later on v6, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`, move the API key and environment to the application process, then remove the legacy setting. +- **Keep Feature Flags disabled:** Replace `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=false` with `DD_FEATURE_FLAGS_ENABLED=false`. + +After the legacy setting is removed, Node.js defaults to agentless delivery unless you explicitly select `remote_config`. See [Server SDK Configuration Sources][6] for the complete precedence table. + +To configure `feature_flag.evaluations`, including the required tracer version and Agent OTLP setup, see [Set Up Server-Side Flag Evaluation Metrics][4]. For more information on available graphing, see [Feature Flag Graphs][5]. + ## Testing You can test against a dedicated Datadog test environment with the real `tracer.openfeature` provider, or swap it for OpenFeature's `TypedInMemoryProvider` to control flag values directly in test code. This section shows the in-memory approach, which keeps tests hermetic and offline. `TypedInMemoryProvider` ships with `@openfeature/server-sdk`, so no additional dependency is required. @@ -412,4 +404,4 @@ The snippet above uses Vitest for its first-class ESM support. The same pattern [3]: /account_management/api-app-keys/#api-keys [4]: /feature_flags/guide/server_flag_evaluation_metrics/ [5]: /feature_flags/concepts/flag_graphs/ -[6]: /feature_flags/concepts/configuration_sources/#migrate-from-the-legacy-provider-setting +[6]: /feature_flags/concepts/configuration_sources/#configuration-precedence