diff --git a/hugo/content/en/feature_flags/concepts/configuration_sources.md b/hugo/content/en/feature_flags/concepts/configuration_sources.md index bf1959a918b..e8abc96f3e3 100644 --- a/hugo/content/en/feature_flags/concepts/configuration_sources.md +++ b/hugo/content/en/feature_flags/concepts/configuration_sources.md @@ -48,6 +48,7 @@ To get started with agentless delivery, use one of these minimum versions: | Java `dd-openfeature` and `dd-java-agent` | 1.65.0 | | Node.js `dd-trace` v5 | 5.116.0 | | Node.js `dd-trace` v6 | 6.5.0 | +| Python `ddtrace` | 4.14.0 | Java CDN delivery requires `dd-openfeature` and `dd-java-agent`. It does not require a Datadog Agent for flag configuration. @@ -59,11 +60,11 @@ DD_SITE={{< region-param key="dd_site" code="true" >}} DD_ENV= {{< /code-block >}} -Then initialize or access the Datadog OpenFeature provider in application code. See the [Java][4] or [Node.js][2] setup instructions. +Then initialize or access the Datadog OpenFeature provider in application code. See the [Java][4], [Node.js][2], or [Python][5] setup instructions. 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 export evaluation metrics or exposure events. Java agentless delivery changes only the configuration source. Without a supported Datadog Agent or serverless telemetry path, Java also does not export these signals.
+
The initial Node.js agentless releases support configuration delivery and local flag evaluation only. They do not export evaluation metrics or exposure events. Java and Python agentless delivery change only the configuration source. Java and Python do not export these signals without a supported Datadog Agent or serverless telemetry path.
### Configure agentless delivery @@ -72,7 +73,7 @@ Set `DD_SITE` to your organization's Datadog site. For the site selected on this | Environment variable | Default | Description | |---|---|---| | `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. Java does not limit attempts, while Node.js caps values at 3600 seconds. | +| `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` | `30` | Positive integer that sets the time between completed polling attempts. Java does not limit attempts, while Node.js and Python cap values 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 does the following: @@ -170,3 +171,4 @@ Server Feature Flags billing is based on configuration requests made through Rem [2]: /feature_flags/server/nodejs/ [3]: /feature_flags/server/ [4]: /feature_flags/server/java/ +[5]: /feature_flags/server/python/ diff --git a/hugo/content/en/feature_flags/implementation_patterns/serverless.md b/hugo/content/en/feature_flags/implementation_patterns/serverless.md index 61697bcd724..3e550bc7fc9 100644 --- a/hugo/content/en/feature_flags/implementation_patterns/serverless.md +++ b/hugo/content/en/feature_flags/implementation_patterns/serverless.md @@ -18,7 +18,7 @@ further_reading: ## Overview -The Datadog Feature Flags Java and Node.js SDKs can receive flag configuration directly from the Datadog-managed CDN. This _agentless_ configuration source simplifies onboarding because it does not require a Datadog Agent for flag configuration. It also supports serverless applications that cannot connect to a Datadog Agent. +The Datadog Feature Flags Java, Node.js, and Python SDKs can receive flag configuration directly from the Datadog-managed CDN. This _agentless_ configuration source simplifies onboarding because it does not require a Datadog Agent for flag configuration. It also supports serverless applications that cannot connect to a Datadog Agent. After configuration is loaded, flag evaluation happens locally in the application. The SDK does not make a network request for each evaluation. @@ -29,12 +29,13 @@ Agentless configuration delivery is available in: | Java `dd-openfeature` and `dd-java-agent` | 1.65.0 | | Node.js `dd-trace` v5 | 5.116.0 | | Node.js `dd-trace` v6 | 6.5.0 | +| Python `ddtrace` | 4.14.0 | Java CDN delivery requires `dd-openfeature` and `dd-java-agent`. The Java runtime must support loading `dd-java-agent` with the `-javaagent` JVM option. You can pass this option in the Java command or through `JAVA_TOOL_OPTIONS`. Other server SDKs and versions earlier than those listed require Agent Remote Configuration for flag delivery. -
The initial Node.js agentless releases load configuration and evaluate flags locally. They do not export evaluation metrics or exposure events. Java agentless delivery changes only the configuration source. Without a supported Datadog Agent or serverless telemetry path, Java also does not export these signals.
+
The initial Node.js agentless releases load configuration and evaluate flags locally. They do not export evaluation metrics or exposure events. Java and Python agentless delivery change only the configuration source. Java and Python do not export these signals without a supported Datadog Agent or serverless telemetry path.
## Agentless architecture @@ -49,7 +50,7 @@ Use agentless delivery when the serverless runtime can make outbound HTTPS reque DD_SITE={{< region-param key="dd_site" code="true" >}} DD_ENV={{< /code-block >}} -4. Initialize or access the Datadog OpenFeature provider as described in the [Java][6] or [Node.js][3] setup. This starts CDN polling. No Feature Flags enablement or source setting is required. +4. Initialize or access the Datadog OpenFeature provider as described in the [Java][6], [Node.js][3], or [Python][9] setup. This starts CDN polling. No Feature Flags enablement or source setting is required. 5. 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. @@ -90,7 +91,7 @@ Explicitly selecting `remote_config` enables the Feature Flags Remote Configurat - **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**: Java requires Java 11 or later. For Node.js, check the tracer's runtime compatibility requirements. +- **Runtime support**: Java requires Java 11 or later. For Node.js and Python, check the tracer's runtime 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. Datadog-managed agentless delivery is not available for Datadog for Government in these versions. Use Agent Remote Configuration on that site. @@ -101,15 +102,15 @@ If your deployment uses `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED`, see [Migrat ### AWS Lambda -Java and Node.js Lambda functions can use agentless configuration delivery when they run a minimum SDK version and can reach Datadog over HTTPS. Java functions must load `dd-java-agent` with `-javaagent`, either directly or through `JAVA_TOOL_OPTIONS`. A Java tracing layer can provide this setup. The Datadog Lambda Extension is not required for flag configuration. +Java, Node.js, and Python Lambda functions can use agentless configuration delivery when they run a minimum SDK version and can reach Datadog over HTTPS. Java functions must load `dd-java-agent` with `-javaagent`, either directly or through `JAVA_TOOL_OPTIONS`. A Java tracing layer can provide this setup. The Datadog Lambda Extension is not required for flag configuration. ### Google Cloud serverless environments -Java workloads can use agentless configuration delivery on Java 11 or later when the runtime can load `dd-java-agent`. The Java setup for [Cloud Run Functions][7] and [Cloud Run containers][8] uses `JAVA_TOOL_OPTIONS` to set `-javaagent`. Node.js workloads require a supported tracer runtime. Both runtimes require outbound HTTPS access. +Java workloads can use agentless configuration delivery on Java 11 or later when the runtime can load `dd-java-agent`. The Java setup for [Cloud Run Functions][7] and [Cloud Run containers][8] uses `JAVA_TOOL_OPTIONS` to set `-javaagent`. Node.js and Python workloads require a supported tracer runtime. All runtimes require outbound HTTPS access. ### Azure Functions -Java function apps can use agentless configuration delivery on Java 11 or later when the runtime can load `dd-java-agent`. Node.js function apps require a supported tracer runtime. Both runtimes require outbound HTTPS access. An external Datadog Agent is only required when `remote_config` is selected. +Java function apps can use agentless configuration delivery on Java 11 or later when the runtime can load `dd-java-agent`. Node.js and Python function apps require a supported tracer runtime. All runtimes require outbound HTTPS access. An external Datadog Agent is only required when `remote_config` is selected. ### Edge runtimes @@ -130,7 +131,7 @@ Before enabling Feature Flags in production: 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 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. For Node.js, do not plan experimentation workflows around evaluation metrics or exposure data. For Java, configure a supported Datadog Agent or serverless telemetry path before you use these signals. +6. For Node.js, do not plan experimentation workflows around evaluation metrics or exposure data. For Java and Python, configure a supported Datadog Agent or serverless telemetry path before you use these signals. ## Further reading @@ -144,3 +145,4 @@ Before enabling Feature Flags in production: [6]: /feature_flags/server/java/ [7]: /serverless/google_cloud_run/functions/java/?tab=maven [8]: /serverless/google_cloud_run/containers/in_container/java/ +[9]: /feature_flags/server/python/ diff --git a/hugo/content/en/feature_flags/server/_index.md b/hugo/content/en/feature_flags/server/_index.md index 518eb7eb606..472fb98e3c8 100644 --- a/hugo/content/en/feature_flags/server/_index.md +++ b/hugo/content/en/feature_flags/server/_index.md @@ -39,10 +39,11 @@ The default source does not activate Feature Flags traffic for every tracer inst | Java `dd-openfeature` and `dd-java-agent` | 1.65.0 | | Node.js `dd-trace` v5 | 5.116.0 | | Node.js `dd-trace` v6 | 6.5.0 | +| Python `ddtrace` | 4.14.0 | Java CDN delivery requires `dd-openfeature` and `dd-java-agent`. It does not require a Datadog Agent for flag configuration. -
The initial Node.js agentless releases support configuration delivery and local flag evaluation only. They do not export evaluation metrics or exposure events. Java agentless delivery changes only the configuration source. Without a supported Datadog Agent or serverless telemetry path, Java also does not export these signals.
+
The initial Node.js agentless releases support configuration delivery and local flag evaluation only. They do not export evaluation metrics or exposure events. Java and Python agentless delivery change only the configuration source. Java and Python do not export these signals without a supported Datadog Agent or serverless telemetry path.
Agentless delivery is available for the SDKs and versions listed. Other server SDKs use Agent Remote Configuration. @@ -89,11 +90,11 @@ DD_SITE={{< region-param key="dd_site" code="true" >}} DD_ENV= {{< /code-block >}} -No Feature Flags enablement or source setting is required. See [Java Feature Flags][10] or [Node.js Feature Flags][9] 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. See [Java Feature Flags][10], [Node.js Feature Flags][9], or [Python Feature Flags][11] 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 Java and Node.js, set the source explicitly to retain Agent-managed delivery: +For Java, Node.js, and Python, set the source explicitly to retain Agent-managed delivery: {{< code-block lang="bash" >}} DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config @@ -103,7 +104,7 @@ 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 Java and Node.js implementations with `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. +Existing Java, Node.js, and Python implementations with `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 @@ -131,9 +132,9 @@ DD_VERSION= # See "Set Up Server-Side Flag Evaluation Metrics" documentation {{< /code-block >}} -
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.
+
In the Java, Node.js, and Python 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.
-For SDKs and delivery modes that support it, see Set Up Server-Side Flag Evaluation Metrics to enable the feature_flag.evaluations metric. The initial Node.js agentless releases do not export evaluation metrics or exposure events. Java requires a supported Datadog Agent or serverless telemetry path to export these signals. 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 feature_flag.evaluations metric. The initial Node.js agentless releases do not export evaluation metrics or exposure events. Java and Python require a supported Datadog Agent or serverless telemetry path to export these signals. See Feature Flag Graphs for more information on available graphing. ## Testing with in-memory providers @@ -197,3 +198,4 @@ For percentage-based rollouts and deterministic bucketing, see [Traffic Splittin [8]: /feature_flags/concepts/configuration_sources/ [9]: /feature_flags/server/nodejs/ [10]: /feature_flags/server/java/ +[11]: /feature_flags/server/python/ diff --git a/hugo/content/en/feature_flags/server/python.md b/hugo/content/en/feature_flags/server/python.md index d63036c3a47..92eeed18a5c 100644 --- a/hugo/content/en/feature_flags/server/python.md +++ b/hugo/content/en/feature_flags/server/python.md @@ -14,38 +14,44 @@ 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 Python application with the Datadog Feature Flags SDK. The Python SDK integrates with [OpenFeature][1], an open standard for feature flag management, and receives flag updates through Remote Configuration in the Datadog Python tracer (`ddtrace`). +This page describes how to instrument your Python application with the Datadog Feature Flags SDK. The Python SDK integrates with [OpenFeature][1], an open standard for feature flag management. Starting in `ddtrace` 4.14.0, it loads flag configuration directly from the Datadog-managed CDN by default. This guide explains how to install and enable the SDK, create an OpenFeature client, and evaluate feature flags in your application. +
Python agentless delivery changes only the configuration source. Without a supported Datadog Agent or serverless telemetry path, the SDK does not export evaluation metrics or exposure events.
+ ## Prerequisites Before setting up the Python Feature Flags SDK, ensure you have: -- **Datadog Agent** version 7.55 or later with [Remote Configuration][2] enabled -- **Datadog [API key][3]** configured on the Agent -- **Datadog Python SDK** `ddtrace` version 3.19.0 or later +- **Datadog Python SDK** `ddtrace` version 4.14.0 or later - **OpenFeature Python SDK** `openfeature-sdk`: version 0.5.0 or later (version 0.7.0 or later required if you use provider event handlers to wait for initialization) +- A Datadog [API key][3] +- Your Datadog site Set the following environment variables: {{< code-block lang="bash" >}} -# Required: Enable the feature flags provider -export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true +# Required: Agentless configuration delivery +export DD_API_KEY= +export DD_SITE={{< region-param key="dd_site" code="true" >}} +export DD_ENV= # Optional: Enable flag evaluation metrics export DD_METRICS_OTEL_ENABLED=true -# Required: Service identification +# Recommended: Service identification export DD_SERVICE= -export DD_ENV= {{< /code-block >}} -
The EXPERIMENTAL_ prefix is retained for backwards compatibility; the provider itself is stable.
+No Feature Flags enablement or source setting is required. Register the provider as shown in [Initialize the SDK](#initialize-the-sdk) to begin polling. Installing or initializing `ddtrace` alone does not create Feature Flags CDN traffic. 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]. @@ -60,7 +66,7 @@ pip install ddtrace openfeature-sdk Or add them to your `requirements.txt`: {{< code-block lang="text" filename="requirements.txt" >}} -ddtrace>=3.19.0 +ddtrace>=4.14.0 openfeature-sdk>=0.5.0 {{< /code-block >}} @@ -79,16 +85,12 @@ opentelemetry-exporter-otlp-proto-grpc>=1.41.0 ## Initialize the SDK -Register the Datadog OpenFeature provider with the OpenFeature API. The provider connects to the Datadog Python tracer's Remote Configuration system to receive flag configurations. +Register the Datadog OpenFeature provider with the OpenFeature API. The provider starts the selected configuration source and waits up to 10 seconds for its first configuration. {{< code-block lang="python" >}} -from ddtrace import tracer from openfeature import api from ddtrace.openfeature import DataDogProvider -# Initialize the tracer (required for Remote Configuration) -tracer.configure() - # Create and register the Datadog provider provider = DataDogProvider() api.set_provider(provider) @@ -209,7 +211,7 @@ if maintenance_mode: ## Waiting for provider initialization -By default, the provider initializes asynchronously and flag evaluations return default values until the first Remote Configuration payload is received. If your application requires flags to be ready before handling requests, you can wait for the provider to initialize using event handlers: +Provider registration waits up to 10 seconds for the selected source to deliver its first configuration. If configuration arrives, the provider emits `PROVIDER_READY`. If the wait times out, registration completes with the provider in an error state, and evaluations return caller-provided default values until configuration arrives. Use an event handler to wait for a later ready event: {{< code-block lang="python" >}} import threading @@ -230,7 +232,7 @@ api.add_handler(ProviderEvent.PROVIDER_READY, on_ready) provider = DataDogProvider() api.set_provider(provider) -# Wait for provider to be ready (with optional timeout) +# Wait for the provider to be ready if registration timed out if ready_event.wait(timeout=30): print("Provider is ready") else: @@ -240,7 +242,20 @@ else: client = api.get_client() {{< /code-block >}} -
Waiting for provider initialization requires OpenFeature SDK 0.7.0 or later. Most applications don't need to wait for initialization, as flag evaluations work immediately with default values.
+
Provider event handlers require OpenFeature SDK 0.7.0 or later. Most applications can use the default 10-second initialization timeout and handle caller-provided default values if configuration is unavailable.
+ +Set `DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS` to a positive number of milliseconds to change the initialization timeout. + +## Advanced configuration + +Use [Server SDK Configuration Sources][6] as the canonical reference for source selection and operational settings: + +- [Configure agentless delivery][10], including polling, request timeout, and endpoint settings +- [Use a custom agentless endpoint][7] for advanced testing, local development, or an operator-managed proxy +- [Use Agent Remote Configuration][9] to retain Agent-managed delivery +- [Migrate an existing Remote Configuration setup][8] and remove the deprecated `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` setting + +Agentless mode changes only flag configuration. It does not configure or enable `feature_flag.evaluations`, exposure logging, or experimentation use cases. These features require a supported Datadog Agent or serverless telemetry path. ## Cleanup @@ -297,27 +312,41 @@ def test_missing_flag_returns_default(client): ## Troubleshooting -### Provider not enabled +### Agentless configuration not working -If you receive warnings about the provider not being enabled, ensure `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` is set in your environment: +Verify the following: -{{< code-block lang="bash" >}} -export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true -{{< /code-block >}} +- `ddtrace` is version 4.14.0 or later. +- `DD_FEATURE_FLAGS_ENABLED` is unset or set to `true`. +- `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE` is unset or set to `agentless`. +- `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` is unset. Setting it to `true` selects Agent Remote Configuration during the migration window when no explicit source is set. +- Application code registers `DataDogProvider` with the OpenFeature API. +- `DD_API_KEY`, `DD_SITE`, and `DD_ENV` are configured in the application process. +- The application can make outbound HTTPS requests to Datadog. + +Set `DD_TRACE_DEBUG=true` and check for authentication, timeout, or malformed-payload messages from the Feature Flags agentless endpoint. + +### Agent Remote Configuration not working -### Remote Configuration not working +Verify the following: -Verify the following to ensure that Remote Configuration is working: -- Datadog Agent is version 7.55 or later -- Remote Configuration is enabled on the Agent -- `DD_SERVICE` and `DD_ENV` environment variables are set -- The SDK can communicate with the Agent +- `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config` is set. During the migration window, `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` also selects Remote Configuration when no explicit source is set. +- Datadog Agent is version 7.55 or later. +- [Remote Configuration][2] is enabled on the Agent. +- The Agent has a valid API key for the target organization. +- `DD_SERVICE` and `DD_ENV` are configured in the application process. +- The SDK can communicate with the Agent. [1]: https://openfeature.dev/ [2]: /agent/remote_config/ [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/ +[7]: /feature_flags/concepts/configuration_sources/#use-a-custom-agentless-endpoint +[8]: /feature_flags/concepts/configuration_sources/#migrate-an-existing-remote-configuration-setup +[9]: /feature_flags/concepts/configuration_sources/#use-agent-remote-configuration +[10]: /feature_flags/concepts/configuration_sources/#configure-agentless-delivery ## Further reading