From eb91e7099ed14249a38422493ab70eafa998c28e Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 08:28:33 -0600 Subject: [PATCH 01/10] [FFL-2653] Document Java flag evaluation metrics setup Reflect the requirements for emitting the feature_flag.evaluations metric from the Java SDK: - Bump dd-openfeature examples to 1.63.0; note the 1.62.0 metrics floor - Document the OpenTelemetry SDK metrics + OTLP exporter dependencies (via the OpenTelemetry BOM) that the released provider needs - Clarify that the OTel SDK on the classpath, not DD_METRICS_OTEL_ENABLED, enables metrics on the Java tracer - Add a Spring Boot ScopeConfigurator startup troubleshooting note - Clarify the OpenTelemetry integration note for the metrics case Co-Authored-By: Claude Opus 4.8 (1M context) --- .../guide/server_flag_evaluation_metrics.md | 59 +++++++++++++++++++ .../implementation_patterns/opentelemetry.md | 2 +- content/en/feature_flags/server/java.md | 10 ++-- .../getting_started/feature_flags/_index.md | 7 +-- 4 files changed, 69 insertions(+), 9 deletions(-) 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 9313e83912b..c3c59d859ae 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -58,6 +58,64 @@ Set the following environment variable on your application, in addition to the s DD_METRICS_OTEL_ENABLED=true {{< /code-block >}} +### Java: add the OpenTelemetry SDK dependencies + +The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter must be on your application's classpath. Add them alongside your [feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: + +{{< tabs >}} +{{% tab "Gradle (Groovy)" %}} +{{< code-block lang="groovy" filename="build.gradle" >}} +dependencies { + implementation platform('io.opentelemetry:opentelemetry-bom:1.47.0') + implementation 'io.opentelemetry:opentelemetry-sdk-metrics' + implementation 'io.opentelemetry:opentelemetry-exporter-otlp' +} +{{< /code-block >}} +{{% /tab %}} + +{{% tab "Gradle (Kotlin)" %}} +{{< code-block lang="kotlin" filename="build.gradle.kts" >}} +dependencies { + implementation(platform("io.opentelemetry:opentelemetry-bom:1.47.0")) + implementation("io.opentelemetry:opentelemetry-sdk-metrics") + implementation("io.opentelemetry:opentelemetry-exporter-otlp") +} +{{< /code-block >}} +{{% /tab %}} + +{{% tab "Maven" %}} +{{< code-block lang="xml" filename="pom.xml" >}} + + + + io.opentelemetry + opentelemetry-bom + 1.47.0 + pom + import + + + + + + io.opentelemetry + opentelemetry-sdk-metrics + + + io.opentelemetry + opentelemetry-exporter-otlp + + +{{< /code-block >}} +{{% /tab %}} +{{< /tabs >}} + +On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath, so adding these dependencies is what enables the metric; setting `DD_METRICS_OTEL_ENABLED` alone does not. This requires the Datadog Java tracer 1.62.0 or later. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`. + +
In Spring Boot applications, Spring Boot's OpenTelemetry autoconfiguration also creates an OpenTelemetrySdk bean. If the OpenTelemetry SDK version it resolves does not match the OpenTelemetry API version on the classpath, startup fails with a BeanCreationException for the openTelemetry bean and NoClassDefFoundError: io/opentelemetry/sdk/internal/ScopeConfigurator. Importing the opentelemetry-bom as shown above keeps the API and SDK on the same version and resolves the error.
+ +### Set the OTLP endpoint + By default, most tracers send OTLP metrics to the Agent at `DD_AGENT_HOST` on port `4318` (HTTP). If your application already sets `DD_AGENT_HOST` to reach the Agent, no endpoint configuration is required. Set an OTLP endpoint explicitly in any of these cases: @@ -151,3 +209,4 @@ The `feature_flag.evaluations` metric is a counter with the following tags: [3]: https://app.datadoghq.com/metric/explorer [4]: https://app.datadoghq.com/metric/summary [5]: /dashboards/ +[6]: /feature_flags/server/java/#installation diff --git a/content/en/feature_flags/implementation_patterns/opentelemetry.md b/content/en/feature_flags/implementation_patterns/opentelemetry.md index d6d6fe243e6..74edae1082f 100644 --- a/content/en/feature_flags/implementation_patterns/opentelemetry.md +++ b/content/en/feature_flags/implementation_patterns/opentelemetry.md @@ -134,7 +134,7 @@ Client client = api.getClient("my-app"); /* Your existing OpenTelemetry API calls continue to work unchanged */ {{< /code-block >}} -**Note**: Depend only on the OpenTelemetry API, not the OpenTelemetry SDK. For more detail, see [OpenTelemetry API Support for Java](/opentelemetry/instrument/dd_sdks/api_support/?prog_lang=java&platform=traces). +**Note**: For tracing, depend only on the OpenTelemetry API, not the OpenTelemetry SDK. To emit flag evaluation metrics, you also need the OpenTelemetry SDK metrics and OTLP exporter dependencies; see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). For more detail, see [OpenTelemetry API Support for Java](/opentelemetry/instrument/dd_sdks/api_support/?prog_lang=java&platform=traces). {{% /tab %}} {{% tab "Node.js" %}} diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index a68c3e8ef8e..22fe1409d0b 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -32,7 +32,7 @@ The Java SDK integrates feature flags directly into the Datadog Java tracer (`dd The Datadog Feature Flags SDK for Java requires: - **Java 11 or higher** -- **Datadog Java SDK**: Version **1.57.0** or later +- **Datadog Java SDK**: Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) - **OpenFeature SDK**: Version **1.18.2** 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 @@ -57,7 +57,7 @@ dependencies { implementation 'dev.openfeature:sdk:1.18.2' // Datadog OpenFeature Provider - implementation 'com.datadoghq:dd-openfeature:1.57.0' + implementation 'com.datadoghq:dd-openfeature:1.63.0' } {{< /code-block >}} {{% /tab %}} @@ -71,7 +71,7 @@ dependencies { implementation("dev.openfeature:sdk:1.18.2") // Datadog OpenFeature Provider - implementation("com.datadoghq:dd-openfeature:1.57.0") + implementation("com.datadoghq:dd-openfeature:1.63.0") } {{< /code-block >}} {{% /tab %}} @@ -92,13 +92,15 @@ Add the following dependencies to your `pom.xml`: com.datadoghq dd-openfeature - 1.57.0 + 1.63.0 {{< /code-block >}} {{% /tab %}} {{< /tabs >}} +To emit flag evaluation metrics (the `feature_flag.evaluations` metric), use `dd-openfeature` 1.62.0 or later and add the OpenTelemetry SDK dependencies to your application. For the required dependencies and endpoint configuration, see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). + ## 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). diff --git a/content/en/getting_started/feature_flags/_index.md b/content/en/getting_started/feature_flags/_index.md index 97ab2d05bff..8f114a26793 100644 --- a/content/en/getting_started/feature_flags/_index.md +++ b/content/en/getting_started/feature_flags/_index.md @@ -158,7 +158,7 @@ dependencies { implementation 'dev.openfeature:sdk:1.18.2' // Datadog OpenFeature Provider - implementation 'com.datadoghq:dd-openfeature:1.57.0' + implementation 'com.datadoghq:dd-openfeature:1.63.0' } {{< /code-block >}} @@ -169,12 +169,11 @@ Enable the provider and start your application with the Java tracer: # The EXPERIMENTAL_ prefix is historical; the provider is no longer experimental. export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true -# Optional: Enable flag evaluation metrics -export DD_METRICS_OTEL_ENABLED=true - java -javaagent:path/to/dd-java-agent.jar -jar your-application.jar {{< /code-block >}} +To emit flag evaluation metrics, add the OpenTelemetry SDK dependencies and configure the OTLP endpoint. See [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). + Register the Datadog OpenFeature provider: {{< code-block lang="java" >}} From dd2600d29784acb6f7060ef0f13821259b0776f6 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 10:22:55 -0600 Subject: [PATCH 02/10] [FFL-2653] Address review: carve Java out of DD_METRICS_OTEL_ENABLED, clarify OTLP HTTP - Note that the Java tracer does not use DD_METRICS_OTEL_ENABLED for flag evaluation metrics, and drop it from the Java OpenTelemetry .env snippets - Document that the Java exporter uses OTLP/HTTP on port 4318 and ignores OTEL_EXPORTER_OTLP_PROTOCOL, so gRPC must not be configured for it Co-Authored-By: Claude Opus 4.8 (1M context) --- .../en/feature_flags/guide/server_flag_evaluation_metrics.md | 4 +++- .../en/feature_flags/implementation_patterns/opentelemetry.md | 2 -- 2 files changed, 3 insertions(+), 3 deletions(-) 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 c3c59d859ae..dd98d1a47e9 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -58,6 +58,8 @@ Set the following environment variable on your application, in addition to the s DD_METRICS_OTEL_ENABLED=true {{< /code-block >}} +If you use the **Java** tracer, `DD_METRICS_OTEL_ENABLED` is not required for flag evaluation metrics; the OpenTelemetry SDK dependencies described in the next section enable them instead. + ### Java: add the OpenTelemetry SDK dependencies The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter must be on your application's classpath. Add them alongside your [feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: @@ -121,7 +123,7 @@ By default, most tracers send OTLP metrics to the Agent at `DD_AGENT_HOST` on po Set an OTLP endpoint explicitly in any of these cases: - The Agent is not reachable at `DD_AGENT_HOST` on the default OTLP port (for example, a remote Agent or a non-default port). -- You use the **Java** tracer. The Java tracer does not derive the endpoint from `DD_AGENT_HOST`; it defaults to `localhost:4318`. Set the endpoint whenever the Agent is not on `localhost`. +- You use the **Java** tracer. The Java flag evaluation metrics exporter sends OTLP over HTTP on port `4318` and ignores `OTEL_EXPORTER_OTLP_PROTOCOL`, so do not configure it for gRPC. It does not derive the endpoint from `DD_AGENT_HOST`; it defaults to `http://localhost:4318`. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint whenever the Agent is not on `localhost`. - You use the **Python** tracer. The Python tracer defaults to gRPC on port `4317`, not HTTP. Enable the gRPC OTLP receiver on the Agent, or override the protocol to use HTTP instead: {{< code-block lang="bash" >}} diff --git a/content/en/feature_flags/implementation_patterns/opentelemetry.md b/content/en/feature_flags/implementation_patterns/opentelemetry.md index 74edae1082f..c129f1dd20c 100644 --- a/content/en/feature_flags/implementation_patterns/opentelemetry.md +++ b/content/en/feature_flags/implementation_patterns/opentelemetry.md @@ -115,7 +115,6 @@ For more detail, see [OpenTelemetry API Support for Go](/opentelemetry/instrumen {{< code-block lang="bash" filename=".env" >}} DD_TRACE_OTEL_ENABLED=true DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true -DD_METRICS_OTEL_ENABLED=true DD_SERVICE= DD_ENV= DD_VERSION= @@ -347,7 +346,6 @@ func main() { {{< code-block lang="bash" filename=".env" >}} DD_APM_TRACING_ENABLED=false DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true -DD_METRICS_OTEL_ENABLED=true DD_SERVICE= DD_ENV= DD_VERSION= From bdc4107bf170f42808dbd5bda1cc10a0a775f83d Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 11:15:35 -0600 Subject: [PATCH 03/10] [FFL-2653] Align OpenFeature SDK examples with dd-openfeature 1.63.0 The dd-openfeature 1.63.0 POM declares dev.openfeature:sdk 1.20.1 (1.57.0 declared 1.18.2). Bump the direct dev.openfeature:sdk examples and the compatibility line to 1.20.1 so a pinned direct dependency does not downgrade the provider's transitive version under Maven mediation. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/en/feature_flags/server/java.md | 8 ++++---- content/en/getting_started/feature_flags/_index.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 22fe1409d0b..37e47dde02f 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -33,7 +33,7 @@ The Java SDK integrates feature flags directly into the Datadog Java tracer (`dd The Datadog Feature Flags SDK for Java requires: - **Java 11 or higher** - **Datadog Java SDK**: Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) -- **OpenFeature SDK**: Version **1.18.2** or later +- **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 @@ -54,7 +54,7 @@ Add the following dependencies to your `build.gradle`: {{< code-block lang="groovy" filename="build.gradle" >}} dependencies { // OpenFeature SDK for flag evaluation - implementation 'dev.openfeature:sdk:1.18.2' + implementation 'dev.openfeature:sdk:1.20.1' // Datadog OpenFeature Provider implementation 'com.datadoghq:dd-openfeature:1.63.0' @@ -68,7 +68,7 @@ Add the following dependencies to your `build.gradle.kts`: {{< code-block lang="kotlin" filename="build.gradle.kts" >}} dependencies { // OpenFeature SDK for flag evaluation - implementation("dev.openfeature:sdk:1.18.2") + implementation("dev.openfeature:sdk:1.20.1") // Datadog OpenFeature Provider implementation("com.datadoghq:dd-openfeature:1.63.0") @@ -85,7 +85,7 @@ Add the following dependencies to your `pom.xml`: dev.openfeature sdk - 1.18.2 + 1.20.1 diff --git a/content/en/getting_started/feature_flags/_index.md b/content/en/getting_started/feature_flags/_index.md index 8f114a26793..d1610525304 100644 --- a/content/en/getting_started/feature_flags/_index.md +++ b/content/en/getting_started/feature_flags/_index.md @@ -155,7 +155,7 @@ Add the OpenFeature SDK and Datadog OpenFeature provider dependencies: {{< code-block lang="groovy" filename="build.gradle" >}} dependencies { // OpenFeature SDK for flag evaluation - implementation 'dev.openfeature:sdk:1.18.2' + implementation 'dev.openfeature:sdk:1.20.1' // Datadog OpenFeature Provider implementation 'com.datadoghq:dd-openfeature:1.63.0' From ddc23e65fc62f787a6bb935881db970f0b002974 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 14:07:01 -0600 Subject: [PATCH 04/10] [FFL-2653] Address PR review comments - Scope the DD_METRICS_OTEL_ENABLED step to non-Java tracers so it no longer reads as contradictory with the Java guidance - List the Datadog OpenFeature provider in the compatibility requirements - Resolve an ambiguous pronoun in the Java OTLP endpoint note - Regroup the OpenTelemetry integration note: tracing guidance and link, then metrics guidance and link Co-Authored-By: Claude Opus 4.8 (1M context) --- .../feature_flags/guide/server_flag_evaluation_metrics.md | 6 ++---- .../feature_flags/implementation_patterns/opentelemetry.md | 2 +- content/en/feature_flags/server/java.md | 1 + 3 files changed, 4 insertions(+), 5 deletions(-) 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 dd98d1a47e9..e47b8709bf9 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -51,15 +51,13 @@ You only need to enable the protocol your application uses (gRPC on port 4317, o ## Step 2: Configure your application -Set the following environment variable on your application, in addition to the standard [server-side feature flag configuration][1]: +Set the following environment variable on non-Java tracers, in addition to the standard [server-side feature flag configuration][1]. The Java tracer enables flag evaluation metrics through the OpenTelemetry SDK dependencies described in the [next section](#java-add-the-opentelemetry-sdk-dependencies), not through this variable. {{< code-block lang="bash" >}} # Enable flag evaluation metrics DD_METRICS_OTEL_ENABLED=true {{< /code-block >}} -If you use the **Java** tracer, `DD_METRICS_OTEL_ENABLED` is not required for flag evaluation metrics; the OpenTelemetry SDK dependencies described in the next section enable them instead. - ### Java: add the OpenTelemetry SDK dependencies The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter must be on your application's classpath. Add them alongside your [feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: @@ -123,7 +121,7 @@ By default, most tracers send OTLP metrics to the Agent at `DD_AGENT_HOST` on po Set an OTLP endpoint explicitly in any of these cases: - The Agent is not reachable at `DD_AGENT_HOST` on the default OTLP port (for example, a remote Agent or a non-default port). -- You use the **Java** tracer. The Java flag evaluation metrics exporter sends OTLP over HTTP on port `4318` and ignores `OTEL_EXPORTER_OTLP_PROTOCOL`, so do not configure it for gRPC. It does not derive the endpoint from `DD_AGENT_HOST`; it defaults to `http://localhost:4318`. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint whenever the Agent is not on `localhost`. +- You use the **Java** tracer. The Java flag evaluation metrics exporter sends OTLP over HTTP on port `4318` and ignores `OTEL_EXPORTER_OTLP_PROTOCOL`, so gRPC is not supported. It does not derive the endpoint from `DD_AGENT_HOST`; it defaults to `http://localhost:4318`. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint whenever the Agent is not on `localhost`. - You use the **Python** tracer. The Python tracer defaults to gRPC on port `4317`, not HTTP. Enable the gRPC OTLP receiver on the Agent, or override the protocol to use HTTP instead: {{< code-block lang="bash" >}} diff --git a/content/en/feature_flags/implementation_patterns/opentelemetry.md b/content/en/feature_flags/implementation_patterns/opentelemetry.md index c129f1dd20c..4320dc993e7 100644 --- a/content/en/feature_flags/implementation_patterns/opentelemetry.md +++ b/content/en/feature_flags/implementation_patterns/opentelemetry.md @@ -133,7 +133,7 @@ Client client = api.getClient("my-app"); /* Your existing OpenTelemetry API calls continue to work unchanged */ {{< /code-block >}} -**Note**: For tracing, depend only on the OpenTelemetry API, not the OpenTelemetry SDK. To emit flag evaluation metrics, you also need the OpenTelemetry SDK metrics and OTLP exporter dependencies; see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). For more detail, see [OpenTelemetry API Support for Java](/opentelemetry/instrument/dd_sdks/api_support/?prog_lang=java&platform=traces). +**Note**: For tracing, depend only on the OpenTelemetry API, not the OpenTelemetry SDK. For more detail, see [OpenTelemetry API Support for Java](/opentelemetry/instrument/dd_sdks/api_support/?prog_lang=java&platform=traces). To emit flag evaluation metrics, you also need the OpenTelemetry SDK metrics and OTLP exporter dependencies; see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). {{% /tab %}} {{% tab "Node.js" %}} diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 37e47dde02f..c53b3222e04 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -33,6 +33,7 @@ The Java SDK integrates feature flags directly into the Datadog Java tracer (`dd The Datadog Feature Flags SDK for Java requires: - **Java 11 or higher** - **Datadog Java SDK**: Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) +- **Datadog OpenFeature provider** (`com.datadoghq:dd-openfeature`): Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) - **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 From 61e32ba8a1d72aebe9c6a7ed516af51ada8db722 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 14:15:44 -0600 Subject: [PATCH 05/10] [FFL-2653] Address second round of PR review comments - Note the Datadog Java tracer 1.62.0+ requirement (not just the provider) - Clarify that examples use the current release 1.63.0 - Lead the env-var step with "all tracers except Java"; tighten wording - Use direct voice and tighten the Java OTLP endpoint bullet Co-Authored-By: Claude Opus 4.8 (1M context) --- .../feature_flags/guide/server_flag_evaluation_metrics.md | 8 ++++---- content/en/feature_flags/server/java.md | 4 +++- 2 files changed, 7 insertions(+), 5 deletions(-) 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 e47b8709bf9..b4b357b5585 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -51,7 +51,7 @@ You only need to enable the protocol your application uses (gRPC on port 4317, o ## Step 2: Configure your application -Set the following environment variable on non-Java tracers, in addition to the standard [server-side feature flag configuration][1]. The Java tracer enables flag evaluation metrics through the OpenTelemetry SDK dependencies described in the [next section](#java-add-the-opentelemetry-sdk-dependencies), not through this variable. +For all tracers except Java, set the following environment variable in addition to the standard [server-side feature flag configuration][1]. The Java tracer enables flag evaluation metrics through the OpenTelemetry SDK dependencies described in the [next section](#java-add-the-opentelemetry-sdk-dependencies). {{< code-block lang="bash" >}} # Enable flag evaluation metrics @@ -60,7 +60,7 @@ DD_METRICS_OTEL_ENABLED=true ### Java: add the OpenTelemetry SDK dependencies -The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter must be on your application's classpath. Add them alongside your [feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: +The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter dependencies must be on your application's classpath. Add them alongside your [Java feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: {{< tabs >}} {{% tab "Gradle (Groovy)" %}} @@ -110,7 +110,7 @@ dependencies { {{% /tab %}} {{< /tabs >}} -On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath, so adding these dependencies is what enables the metric; setting `DD_METRICS_OTEL_ENABLED` alone does not. This requires the Datadog Java tracer 1.62.0 or later. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`. +On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath. Adding these dependencies enables the metric; setting `DD_METRICS_OTEL_ENABLED` alone does not. This requires the Datadog Java tracer 1.62.0 or later. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`.
In Spring Boot applications, Spring Boot's OpenTelemetry autoconfiguration also creates an OpenTelemetrySdk bean. If the OpenTelemetry SDK version it resolves does not match the OpenTelemetry API version on the classpath, startup fails with a BeanCreationException for the openTelemetry bean and NoClassDefFoundError: io/opentelemetry/sdk/internal/ScopeConfigurator. Importing the opentelemetry-bom as shown above keeps the API and SDK on the same version and resolves the error.
@@ -121,7 +121,7 @@ By default, most tracers send OTLP metrics to the Agent at `DD_AGENT_HOST` on po Set an OTLP endpoint explicitly in any of these cases: - The Agent is not reachable at `DD_AGENT_HOST` on the default OTLP port (for example, a remote Agent or a non-default port). -- You use the **Java** tracer. The Java flag evaluation metrics exporter sends OTLP over HTTP on port `4318` and ignores `OTEL_EXPORTER_OTLP_PROTOCOL`, so gRPC is not supported. It does not derive the endpoint from `DD_AGENT_HOST`; it defaults to `http://localhost:4318`. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint whenever the Agent is not on `localhost`. +- You use the **Java** tracer. Its flag evaluation metrics exporter uses OTLP/HTTP on port `4318` only (gRPC is not supported) and does not derive the endpoint from `DD_AGENT_HOST` (it defaults to `http://localhost:4318`). Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint when the Agent is not on `localhost`. - You use the **Python** tracer. The Python tracer defaults to gRPC on port `4317`, not HTTP. Enable the gRPC OTLP receiver on the Agent, or override the protocol to use HTTP instead: {{< code-block lang="bash" >}} diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index c53b3222e04..21926b8da6c 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -100,7 +100,9 @@ Add the following dependencies to your `pom.xml`: {{% /tab %}} {{< /tabs >}} -To emit flag evaluation metrics (the `feature_flag.evaluations` metric), use `dd-openfeature` 1.62.0 or later and add the OpenTelemetry SDK dependencies to your application. For the required dependencies and endpoint configuration, see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). +The examples use the current release, `1.63.0`. See [Compatibility requirements](#compatibility-requirements) for the minimum supported versions. + +To emit flag evaluation metrics (the `feature_flag.evaluations` metric), use `dd-openfeature` and the Datadog Java tracer 1.62.0 or later, and add the OpenTelemetry SDK dependencies to your application. For the required dependencies and endpoint configuration, see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). ## Configuration From 267dab3c90c1fe800cef2fb6b83e8e0c202ec0a9 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 14:40:08 -0600 Subject: [PATCH 06/10] Update content/en/feature_flags/guide/server_flag_evaluation_metrics.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../en/feature_flags/guide/server_flag_evaluation_metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 b4b357b5585..1a15abe1a5d 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -58,7 +58,7 @@ For all tracers except Java, set the following environment variable in addition DD_METRICS_OTEL_ENABLED=true {{< /code-block >}} -### Java: add the OpenTelemetry SDK dependencies +### Java: Add the OpenTelemetry SDK dependencies The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter dependencies must be on your application's classpath. Add them alongside your [Java feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: From 7892c888b406bce1fc62fb6c7d5f95746cf648d6 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 14:55:51 -0600 Subject: [PATCH 07/10] [FFL-2653] Address third round of PR review comments - Drop the temporal word "current" from the version note - Use reference-style links for the metrics guide ([8] in java.md, [9] in getting started) and name the target section in the metrics guide link - Name the opentelemetry-sdk-metrics and opentelemetry-exporter-otlp artifacts inline - Remove version restatements already covered by the prerequisites/ compatibility lists Co-Authored-By: Claude Opus 4.8 (1M context) --- .../feature_flags/guide/server_flag_evaluation_metrics.md | 6 +++--- content/en/feature_flags/server/java.md | 5 +++-- content/en/getting_started/feature_flags/_index.md | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) 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 1a15abe1a5d..7d5a7069faa 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -51,7 +51,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]. The Java tracer enables flag evaluation metrics through the OpenTelemetry SDK dependencies described in the [next section](#java-add-the-opentelemetry-sdk-dependencies). +For all tracers except Java, set the following environment variable in addition to the standard [server-side feature flag configuration][1]. The Java tracer enables flag evaluation metrics through the OpenTelemetry SDK dependencies described in [Java: Add the OpenTelemetry SDK dependencies](#java-add-the-opentelemetry-sdk-dependencies). {{< code-block lang="bash" >}} # Enable flag evaluation metrics @@ -60,7 +60,7 @@ DD_METRICS_OTEL_ENABLED=true ### Java: Add the OpenTelemetry SDK dependencies -The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the OpenTelemetry SDK metrics and OTLP exporter dependencies must be on your application's classpath. Add them alongside your [Java feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: +The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the `opentelemetry-sdk-metrics` and `opentelemetry-exporter-otlp` dependencies must be on your application's classpath. Add them alongside your [Java feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: {{< tabs >}} {{% tab "Gradle (Groovy)" %}} @@ -110,7 +110,7 @@ dependencies { {{% /tab %}} {{< /tabs >}} -On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath. Adding these dependencies enables the metric; setting `DD_METRICS_OTEL_ENABLED` alone does not. This requires the Datadog Java tracer 1.62.0 or later. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`. +On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath. Adding these dependencies enables the metric; setting `DD_METRICS_OTEL_ENABLED` alone does not. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`.
In Spring Boot applications, Spring Boot's OpenTelemetry autoconfiguration also creates an OpenTelemetrySdk bean. If the OpenTelemetry SDK version it resolves does not match the OpenTelemetry API version on the classpath, startup fails with a BeanCreationException for the openTelemetry bean and NoClassDefFoundError: io/opentelemetry/sdk/internal/ScopeConfigurator. Importing the opentelemetry-bom as shown above keeps the API and SDK on the same version and resolves the error.
diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 21926b8da6c..805ffb20da7 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -100,9 +100,9 @@ Add the following dependencies to your `pom.xml`: {{% /tab %}} {{< /tabs >}} -The examples use the current release, `1.63.0`. See [Compatibility requirements](#compatibility-requirements) for the minimum supported versions. +The examples above pin `1.63.0`. See [Compatibility requirements](#compatibility-requirements) for the minimum supported versions. -To emit flag evaluation metrics (the `feature_flag.evaluations` metric), use `dd-openfeature` and the Datadog Java tracer 1.62.0 or later, and add the OpenTelemetry SDK dependencies to your application. For the required dependencies and endpoint configuration, see [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). +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 @@ -691,3 +691,4 @@ Exposures appear in Datadog only for flags associated with an experiment. Standa [5]: https://app.datadoghq.com/feature-flags/settings/environments [6]: /agent/configuration/agent-commands/ [7]: /account_management/api-app-keys/#api-keys +[8]: /feature_flags/guide/server_flag_evaluation_metrics/ diff --git a/content/en/getting_started/feature_flags/_index.md b/content/en/getting_started/feature_flags/_index.md index d1610525304..6d994fda8d1 100644 --- a/content/en/getting_started/feature_flags/_index.md +++ b/content/en/getting_started/feature_flags/_index.md @@ -172,7 +172,7 @@ export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true java -javaagent:path/to/dd-java-agent.jar -jar your-application.jar {{< /code-block >}} -To emit flag evaluation metrics, add the OpenTelemetry SDK dependencies and configure the OTLP endpoint. See [Set Up Server-Side Flag Evaluation Metrics](/feature_flags/guide/server_flag_evaluation_metrics/). +To emit flag evaluation metrics, add the OpenTelemetry SDK dependencies and configure the OTLP endpoint. See [Set Up Server-Side Flag Evaluation Metrics][9]. Register the Datadog OpenFeature provider: From a50309016b0b8c6c45671720003280f33ea8773e Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 2 Jul 2026 15:08:43 -0600 Subject: [PATCH 08/10] [FFL-2653] Address fourth round of PR review comments - Clarify which artifact each compatibility line refers to (dd-java-agent vs com.datadoghq:dd-openfeature) - Note both pinned example versions (dd-openfeature and the OpenFeature SDK) - State explicitly that DD_METRICS_OTEL_ENABLED is not required for Java - Reorder the Java endpoint bullet so protocol and port read independently Co-Authored-By: Claude Opus 4.8 (1M context) --- .../feature_flags/guide/server_flag_evaluation_metrics.md | 4 ++-- content/en/feature_flags/server/java.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) 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 7d5a7069faa..a58fe55f26e 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -110,7 +110,7 @@ dependencies { {{% /tab %}} {{< /tabs >}} -On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath. Adding these dependencies enables the metric; setting `DD_METRICS_OTEL_ENABLED` alone does not. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`. +On the Java tracer, the provider starts its OTLP metrics exporter automatically when the OpenTelemetry SDK is on the classpath. Adding these dependencies enables the metric; `DD_METRICS_OTEL_ENABLED` is not required for Java and setting it alone has no effect. If the dependencies are missing, no metrics are emitted and the tracer logs `OpenTelemetry SDK is not on the classpath`.
In Spring Boot applications, Spring Boot's OpenTelemetry autoconfiguration also creates an OpenTelemetrySdk bean. If the OpenTelemetry SDK version it resolves does not match the OpenTelemetry API version on the classpath, startup fails with a BeanCreationException for the openTelemetry bean and NoClassDefFoundError: io/opentelemetry/sdk/internal/ScopeConfigurator. Importing the opentelemetry-bom as shown above keeps the API and SDK on the same version and resolves the error.
@@ -121,7 +121,7 @@ By default, most tracers send OTLP metrics to the Agent at `DD_AGENT_HOST` on po Set an OTLP endpoint explicitly in any of these cases: - The Agent is not reachable at `DD_AGENT_HOST` on the default OTLP port (for example, a remote Agent or a non-default port). -- You use the **Java** tracer. Its flag evaluation metrics exporter uses OTLP/HTTP on port `4318` only (gRPC is not supported) and does not derive the endpoint from `DD_AGENT_HOST` (it defaults to `http://localhost:4318`). Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint when the Agent is not on `localhost`. +- You use the **Java** tracer. Its flag evaluation metrics exporter supports OTLP/HTTP only (gRPC is not supported) and uses port `4318`. It does not derive the endpoint from `DD_AGENT_HOST` and defaults to `http://localhost:4318`. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the Agent's HTTP endpoint when the Agent is not on `localhost`. - You use the **Python** tracer. The Python tracer defaults to gRPC on port `4317`, not HTTP. Enable the gRPC OTLP receiver on the Agent, or override the protocol to use HTTP instead: {{< code-block lang="bash" >}} diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 805ffb20da7..9b6aec90e66 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -32,8 +32,8 @@ The Java SDK integrates feature flags directly into the Datadog Java tracer (`dd The Datadog Feature Flags SDK for Java requires: - **Java 11 or higher** -- **Datadog Java SDK**: Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) -- **Datadog OpenFeature provider** (`com.datadoghq:dd-openfeature`): Version **1.57.0** or later (**1.62.0** or later for flag evaluation metrics) +- **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) - **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 @@ -100,7 +100,7 @@ Add the following dependencies to your `pom.xml`: {{% /tab %}} {{< /tabs >}} -The examples above pin `1.63.0`. See [Compatibility requirements](#compatibility-requirements) for the minimum supported versions. +The examples above pin `dd-openfeature` `1.63.0` and the OpenFeature SDK `1.20.1`. 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]. From 64b64fc0467100b7baecba95ae4cf5b43a647ed9 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Fri, 3 Jul 2026 18:05:57 -0600 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../en/feature_flags/guide/server_flag_evaluation_metrics.md | 2 +- content/en/feature_flags/server/java.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 a58fe55f26e..a7669d4c54d 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -51,7 +51,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]. The Java tracer enables flag evaluation metrics through the OpenTelemetry SDK dependencies described in [Java: Add the OpenTelemetry SDK dependencies](#java-add-the-opentelemetry-sdk-dependencies). +Set the following environment variable in addition to the standard [server-side feature flag configuration][1]: {{< code-block lang="bash" >}} # Enable flag evaluation metrics diff --git a/content/en/feature_flags/server/java.md b/content/en/feature_flags/server/java.md index 9b6aec90e66..99f2943117d 100644 --- a/content/en/feature_flags/server/java.md +++ b/content/en/feature_flags/server/java.md @@ -100,7 +100,7 @@ Add the following dependencies to your `pom.xml`: {{% /tab %}} {{< /tabs >}} -The examples above pin `dd-openfeature` `1.63.0` and the OpenFeature SDK `1.20.1`. See [Compatibility requirements](#compatibility-requirements) for the minimum supported versions. +The examples above pin `dd-openfeature:1.63.0` and the OpenFeature SDK `1.20.1`. 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]. From 0823ed97a4fb4639eed2d309486d5832a6325fb3 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Fri, 3 Jul 2026 18:13:18 -0600 Subject: [PATCH 10/10] [FFL-2653] Add Java note to the metrics env-var step After simplifying the Step 2 lead-in, add a note that the Java tracer does not use DD_METRICS_OTEL_ENABLED and points readers to the Java OpenTelemetry SDK dependencies section instead. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../en/feature_flags/guide/server_flag_evaluation_metrics.md | 2 ++ 1 file changed, 2 insertions(+) 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 a7669d4c54d..1ef372ac649 100644 --- a/content/en/feature_flags/guide/server_flag_evaluation_metrics.md +++ b/content/en/feature_flags/guide/server_flag_evaluation_metrics.md @@ -58,6 +58,8 @@ Set the following environment variable in addition to the standard [server-side DD_METRICS_OTEL_ENABLED=true {{< /code-block >}} +**Note**: The Java tracer does not use `DD_METRICS_OTEL_ENABLED`. Skip this variable and see [Java: Add the OpenTelemetry SDK dependencies](#java-add-the-opentelemetry-sdk-dependencies) instead. + ### Java: Add the OpenTelemetry SDK dependencies The Java provider records `feature_flag.evaluations` through the OpenTelemetry SDK and exports it over OTLP, so the `opentelemetry-sdk-metrics` and `opentelemetry-exporter-otlp` dependencies must be on your application's classpath. Add them alongside your [Java feature flag dependencies][6]. Import the OpenTelemetry BOM so the OpenTelemetry API and SDK stay on the same version: