diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index f294123dcd4..dd7d5858dd4 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -6438,6 +6438,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: Use Cases url: feature_flags/use_cases parent: feature_flags diff --git a/content/en/feature_flags/_index.md b/content/en/feature_flags/_index.md index 32357800af7..9956c044e5e 100644 --- a/content/en/feature_flags/_index.md +++ b/content/en/feature_flags/_index.md @@ -47,7 +47,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 @@ -55,7 +55,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. @@ -68,3 +68,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..8a1ece27d53 --- /dev/null +++ b/content/en/feature_flags/concepts/configuration_sources.md @@ -0,0 +1,160 @@ +--- +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 flag configuration. The _configuration source_ determines how the SDK receives that configuration; it does not change OpenFeature evaluation semantics. + +## Get started with agentless delivery + +Agentless delivery is the default in supported Node.js SDK versions. Other server SDKs use Agent Remote Configuration for flag delivery. To get started with Node.js, use one of these minimum versions: + +| SDK | Minimum version | +|---|---| +| Node.js `dd-trace` v5 | 5.116.0 | +| Node.js `dd-trace` v6 | 6.5.0 | + +Configure only the API key and environment in the application process: + +{{< code-block lang="bash" >}} +DD_API_KEY= +DD_ENV= +{{< /code-block >}} + +Then initialize or access the Datadog OpenFeature provider in application code. See the [Node.js setup instructions][2]. + +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 initial Node.js agentless releases support configuration delivery and local flag evaluation only. They do not support evaluation metrics, exposure logging, or experimentation use cases.
+ +## Advanced configuration + +### Choose a configuration source + +| Mode | Configuration delivery | Activation | Agent requirement | +|---|---|---|---| +| `agentless` (default) | The SDK periodically fetches flag configuration 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 flag configuration 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. | + +Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` only when you want to select a source explicitly: + +{{< code-block lang="bash" >}} +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless +{{< /code-block >}} + +The SDK resolves the source once during initialization. Restart the application to change sources. + +### 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 flag configuration endpoint or base URL. See [Use a custom agentless endpoint](#use-a-custom-agentless-endpoint). | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Positive integer that sets the time between completed polling attempts, capped at 3600 seconds. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `5` | Positive integer that sets the timeout for an individual configuration request. | + +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 5-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. + +The Datadog-managed CDN uses globally distributed points of presence, network peering, and redundant routing. Serving locations are therefore likely to be geographically close to most application workloads. + +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. + +#### Use a custom agentless endpoint + +The Datadog-managed endpoint is recommended for standard deployments. For power-user testing, local development, or an operator-managed proxy, override it with `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL`: + +{{< code-block lang="bash" >}} +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL=http://localhost:8080 +{{< /code-block >}} + +The custom URL must use HTTP or HTTPS. If it contains only an origin or a root path, the SDK appends the standard flag configuration path. If it contains a non-root path, the SDK uses that path as the complete endpoint. + +The SDK sends `DD_API_KEY` only over HTTPS to the default Datadog-managed endpoint. It never forwards the Datadog API key to a custom endpoint. Custom endpoints can use HTTP for controlled local development; use HTTPS for any endpoint outside the local development environment. + +If the custom endpoint setting is invalid, the SDK keeps the provider disabled, logs the configuration error, and evaluations return caller-provided default values. + +Datadog-managed agentless delivery is not available for Datadog for Government in these Node.js versions. Applications on that site continue to use caller-provided default values unless they use 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. | +| Blank or whitespace-only `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` | Treats the source as unset, so the legacy migration setting or the agentless default applies. | +| Explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=offline` or another unsupported nonblank value | Fails closed when application code accesses the provider. The SDK does not select CDN or Remote Configuration delivery. | +| 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 `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` nor `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is set | 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 +{{< /code-block >}} + +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 an existing Remote Configuration setup + +Existing customers who set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` remain on Remote Configuration during a migration window. This deprecated setting is a compatibility bridge, not the long-term configuration. + +When you are ready to use agentless delivery: + +1. Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless`. +2. For the Datadog-managed endpoint, configure `DD_API_KEY` and `DD_ENV` in the application, and set `DD_SITE` if your organization is not on the default site. +3. Initialize the provider and verify that it receives flag updates. +4. Remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. Do not leave the deprecated setting enabled after the migration is complete. + +To remain on Agent Remote Configuration temporarily, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, then remove `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`. Your API key remains on the Agent. + +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, a Node.js application without an explicit source uses agentless delivery. Set `remote_config` explicitly before the deprecated legacy setting is removed if you want to remain on Agent delivery. + +### Future offline mode + +Offline mode is planned for applications that provide flag configuration JSON at startup and do not make CDN or Remote Configuration network requests. It is reserved but not implemented in the initial agentless releases. Setting the source to `offline` fails closed without selecting another delivery path. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /remote_configuration/ +[2]: /feature_flags/server/nodejs/ diff --git a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md index 70d9053253e..bc432845a3b 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -22,13 +22,15 @@ Flag evaluation metrics let you measure how often each variant of a feature flag
The feature_flag.evaluations metric is experimental and may change or be removed in a future release.
+
Node.js agentless limitation: The initial agentless releases in dd-trace 5.116.0 and 6.5.0 support configuration delivery and local flag evaluation only. They do not support evaluation metrics, exposure logging, or experimentation use cases. Do not set DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true to enable these features in agentless mode. The setting is deprecated and preserves Agent Remote Configuration when no explicit configuration source is set; remove it when you migrate to agentless delivery.
+ ## Prerequisites Before setting up flag evaluation metrics, confirm the following: - [Server-side feature flags][1] are already configured. - Datadog Agent 7.32.0 or later is running. -- `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` is set on your application. +- For Agent-backed configurations that use the legacy activation path, `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` is set on your application. Do not use this setting for the initial Node.js agentless releases described above. - Your server-side tracer meets the minimum version for flag evaluation metrics support: | Language | Minimum tracer version | @@ -41,6 +43,8 @@ Before setting up flag evaluation metrics, confirm the following: | Python | 4.7.0 | | Ruby | 2.32.0 | +The Node.js minimum in this table applies to supported Agent-backed evaluation metrics. The initial Node.js agentless releases do not support this metric. + ## Step 1: Enable the Agent OTLP receiver Flag evaluation metrics are emitted over OpenTelemetry (OTLP). The Datadog Agent includes an OTLP receiver that is off by default. For setup instructions, see [OTLP Ingestion by the Datadog Agent][2]. @@ -51,7 +55,7 @@ You only need to enable the protocol your application uses (gRPC on port 4317, o ## Step 2: Configure your application -For all tracers except Java, set the following environment variable in addition to the standard [server-side feature flag configuration][1]. For Java, `DD_METRICS_OTEL_ENABLED` has no effect; see the [Java: Add the OpenTelemetry SDK dependencies](#java-add-the-opentelemetry-sdk-dependencies) section instead. +For supported tracer and delivery-mode combinations except Java, set the following environment variable in addition to the standard [server-side feature flag configuration][1]. For Java, `DD_METRICS_OTEL_ENABLED` has no effect; see the [Java: Add the OpenTelemetry SDK dependencies](#java-add-the-opentelemetry-sdk-dependencies) section instead. {{< code-block lang="bash" >}} # Enable flag evaluation metrics diff --git a/content/en/feature_flags/implementation_patterns/serverless.md b/content/en/feature_flags/implementation_patterns/serverless.md index e7fa77d6b82..a880d0ab869 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. +The Datadog Feature Flags Node.js SDK can receive flag configuration 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 Node.js 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 | +|---|---| +| 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 and earlier Node.js releases require Agent Remote Configuration for flag delivery. -1. Configure the Agent with Remote Configuration enabled. The Agent uses the full-word Remote Configuration variable: +
Flag evaluation only: The initial Node.js agentless releases load configuration and evaluate flags locally. They do not support evaluation metrics, exposure logging, or experimentation use cases.
- {{< 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 Node.js SDK version listed in [Overview](#overview). +2. Configure the API key and environment in the serverless application: -
The EXPERIMENTAL_ prefix is retained for backwards compatibility; the provider itself is stable.
+ {{< code-block lang="bash" >}} + DD_API_KEY= + DD_ENV= + {{< /code-block >}} - 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. + If your organization is not on the default `datadoghq.com` site, also set `DD_SITE`. -1. Configure the standard service tags used by the server SDK: +3. Initialize or access the Datadog OpenFeature provider as described on the [Node.js setup page][3]. 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. - {{< code-block lang="bash" >}} - DD_SERVICE= - DD_ENV= - DD_VERSION= - {{< /code-block >}} +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. -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. +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. -## 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_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. +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. -### Google Cloud Run services +## Operational considerations -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. +- **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 outbound HTTPS access to the Datadog-managed flag configuration service. +- **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 Node.js runtime compatible with the tracer. Check the tracer's compatibility requirements. +- **Kill switch**: `DD_FEATURE_FLAGS_ENABLED` defaults to `true`. Set it to `false` to disable the provider and both configuration delivery paths. Evaluations then return caller-provided default values. -### Google Cloud Run functions and Cloud Functions +Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Use Agent Remote Configuration on that site. -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. +If your deployment uses `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`, see [Migrate from the legacy provider setting][5]. -### Azure Functions +## Environment notes -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. +### AWS Lambda + +Node.js Lambda functions can use agentless configuration delivery when they run a minimum SDK version 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. + +### Google Cloud serverless environments -### AWS Fargate and container tasks +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. + +### 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. +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 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][4] 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 flag configuration 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 a minimum 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 plan experimentation workflows around evaluation metrics or exposure data; these uses are not supported in the initial Node.js agentless 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/nodejs/ +[4]: /api/latest/feature-flags/ +[5]: /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 6a787d1dee8..eff1ef85e8a 100644 --- a/content/en/feature_flags/server/_index.md +++ b/content/en/feature_flags/server/_index.md @@ -17,15 +17,35 @@ 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 flag configuration, 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 flag configuration directly from the Datadog-managed CDN over HTTPS, then evaluates flags locally. A Datadog Agent is not required for flag configuration. + +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 | +|---|---| +| Node.js `dd-trace` v5 | 5.116.0 | +| Node.js `dd-trace` v6 | 6.5.0 | -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). +
The initial Node.js agentless releases support configuration delivery and local flag evaluation only. They do not support evaluation metrics, exposure logging, or experimentation use cases.
-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: +Agentless delivery is available for Node.js in the versions listed. Other server SDKs use Agent Remote Configuration until their language pages list an agentless minimum version. + +## 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 +57,59 @@ 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: +Default Datadog-managed server SDK setups 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 `dd-trace` 5.116.0 or 6.5.0 on Node.js, configure the application process: -## Agent configuration +{{< code-block lang="bash" >}} +# Required for direct configuration delivery +DD_API_KEY= +DD_ENV= +{{< /code-block >}} + +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 Node.js page 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 + +For Node.js, set the source explicitly to retain Agent-managed delivery: -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`. +{{< code-block lang="bash" >}} +DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config +{{< /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`. -See the [Remote Configuration documentation][1] for detailed setup instructions across different deployment environments. +See the [Remote Configuration documentation][1] for detailed setup instructions across deployment environments. -### Polling interval +Existing Node.js 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. -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 +## Advanced application configuration Configure your application with the standard Datadog environment variables. These are common across all server-side SDKs: @@ -73,28 +119,22 @@ 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 +# 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 >}} -
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.
+
In the 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. +For SDKs and delivery modes that support it, see Set Up Server-Side Flag Evaluation Metrics to enable the experimental feature_flag.evaluations metric. The initial Node.js agentless releases do not support evaluation metrics, exposure logging, or experimentation use cases. See Feature Flag Graphs for more information on available graphing. ## Testing with in-memory providers 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. @@ -148,3 +188,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/ +[7]: /feature_flags/concepts/configuration_sources/#migrate-an-existing-remote-configuration-setup diff --git a/content/en/feature_flags/server/nodejs.md b/content/en/feature_flags/server/nodejs.md index 9547ed69fc1..29caa684aa3 100644 --- a/content/en/feature_flags/server/nodejs.md +++ b/content/en/feature_flags/server/nodejs.md @@ -17,65 +17,56 @@ 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. + +
Node.js 5.116.0 and 6.5.0 support agentless configuration delivery and local flag evaluation only. They do not support evaluation metrics, exposure logging, or experimentation use cases.
-## Prerequisites +## Getting started -Before setting up the Node.js Feature Flags SDK, ensure you have: +For the default agentless setup, you need: -- **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.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 -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 ``` -Enable the provider with environment variables: - -```shell -# Required: Enable the feature flags provider -DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +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`. -# Required: Enable Remote Configuration in the tracer -DD_REMOTE_CONFIGURATION_ENABLED=true +### Configure agentless delivery -# Optional: Enable flag evaluation metrics -DD_METRICS_OTEL_ENABLED=true +Configure the API key and environment in the application process: -# Required: Service identification -DD_SERVICE= +```shell +DD_API_KEY= DD_ENV= ``` -
The EXPERIMENTAL_ prefix is retained for backwards compatibility; the provider itself is stable.
- -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. -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, - } - } -}); +tracer.init(); -// setProviderAndWait resolves after Remote Configuration loads, so flags +// 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 { await OpenFeature.setProviderAndWait(tracer.openfeature); @@ -107,7 +98,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 +255,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 = { @@ -302,6 +293,43 @@ 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 + +Datadog Feature Flags is 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. `offline` is reserved but unsupported; unsupported nonblank values fail closed. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL` | Datadog-managed endpoint | Overrides the agentless flag configuration endpoint or base URL. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Positive integer that sets the time between completed polling attempts, capped at 3600 seconds. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS` | `5` | Positive integer that sets the timeout for an individual configuration request. | + +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. + +For power-user testing, local development, or an operator-managed proxy, you can configure a custom HTTP or HTTPS endpoint. The SDK never forwards `DD_API_KEY` to a custom endpoint. See [Use a custom agentless endpoint][7] for path, failure, and security behavior. + +### 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 + +`DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is deprecated. Follow [Migrate an existing Remote Configuration setup][8] to move to agentless delivery, remove the legacy setting, or remain temporarily on Agent Remote Configuration. + +The initial Node.js agentless releases do not support `feature_flag.evaluations`, exposure logging, or experimentation use cases. The [Server-Side Flag Evaluation Metrics][4] guide applies only to supported Agent-backed configurations. 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. @@ -371,3 +399,5 @@ 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/ +[7]: /feature_flags/concepts/configuration_sources/#use-a-custom-agentless-endpoint +[8]: /feature_flags/concepts/configuration_sources/#migrate-an-existing-remote-configuration-setup