From d2110e387ceac644e623c0488629c45b1745ba6b Mon Sep 17 00:00:00 2001 From: bm1549 Date: Thu, 14 May 2026 18:54:54 -0400 Subject: [PATCH 1/8] Add Java to OpenTelemetry Logs API support page dd-trace-java 1.62.0 ships native OpenTelemetry Logs API support and OTLP/HTTP log export. Update the API support page to remove the "not available" warning for Java logs and add Prerequisites, Setup, Examples, Migrate, and Troubleshooting content alongside the existing supported languages. --- .../instrument/dd_sdks/api_support.mdoc.md | 93 ++++++++++++++++--- 1 file changed, 81 insertions(+), 12 deletions(-) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index d57fdc6eac9..85b297550d7 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -12,6 +12,7 @@ aliases: - /opentelemetry/instrument/api_support/go/metrics - /opentelemetry/instrument/api_support/go/traces - /opentelemetry/instrument/api_support/java + - /opentelemetry/instrument/api_support/java/logs - /opentelemetry/instrument/api_support/java/metrics - /opentelemetry/instrument/api_support/java/traces - /opentelemetry/instrument/api_support/nodejs/ @@ -57,15 +58,6 @@ further_reading: - -{% if equals($prog_lang, "java") %} -{% if equals($platform, "logs") %} -{% alert level="danger" %} -OpenTelemetry API support for logs is not available for this language. Use [Datadog Log Collection][210] instead. -{% /alert %} -{% /if %} -{% /if %} - {% if equals($prog_lang, "php") %} {% if equals($platform, "logs") %} @@ -875,14 +867,14 @@ Here is the minimum version required for each instrument type: {% if equals($platform, "logs") %} -{% if includes($prog_lang, ["dot_net", "node_js", "python", "go", "rust"]) %} +{% if includes($prog_lang, ["dot_net", "node_js", "python", "go", "rust", "java"]) %} ## Overview Use the OpenTelemetry Logs API with Datadog SDKs to send custom application logs. This is an alternative to Datadog's traditional log injection. - -{% if includes($prog_lang, ["dot_net", "node_js", "go", "rust"]) %} + +{% if includes($prog_lang, ["dot_net", "node_js", "go", "rust", "java"]) %} The Datadog SDK provides a native implementation of the OpenTelemetry API. This means you can write code against the standard OTel interfaces without needing the official OpenTelemetry SDK. @@ -924,6 +916,11 @@ If you encounter an issue after upgrading `@opentelemetry/api-logs`, [open an is - **Rust**: MSRV 1.84.1 or later. - **OpenTelemetry Rust SDK**: The SDK provides the logs implementation automatically. {% /if %} +{% if equals($prog_lang, "java") %} +- **Datadog SDK**: `dd-trace-java` version 1.62.0 or later. +- **OpenTelemetry Logs API**: Requires the `io.opentelemetry:opentelemetry-api` artifact version 1.27.0 or later (this is the version that introduced the stable logs API). +- **OTLP transport**: Java exports OTel logs only over OTLP HTTP/protobuf. Your OTLP destination must accept logs on port 4318. +{% /if %} - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel logs. ## Setup @@ -1050,6 +1047,15 @@ Follow these steps to enable OTel Logs API support in your application. ``` {% /if %} +{% if equals($prog_lang, "java") %} +1. Add the Datadog SDK (`dd-trace-java`) to your project and [enable its instrumentation][207]. +2. Make sure you only depend on the OpenTelemetry API (and not the OpenTelemetry SDK). +3. Enable OTel logs export by setting the following environment variable: + ```sh + export DD_LOGS_OTEL_ENABLED=true + ``` +{% /if %} + ## Examples {% if equals($prog_lang, "dot_net") %} @@ -1342,6 +1348,57 @@ logger.emit(log_record); ``` {% /if %} +{% if equals($prog_lang, "java") %} +### Emitting a log {% #emitting-log-java %} + +After the Datadog SDK is initialized, you can use the standard OpenTelemetry Logs API to get a logger and emit log records. + +```java +import io.opentelemetry.api.GlobalOpenTelemetry; +import io.opentelemetry.api.common.AttributeKey; +import io.opentelemetry.api.logs.Logger; +import io.opentelemetry.api.logs.Severity; + +Logger logger = GlobalOpenTelemetry.get().getLogsBridge().get("my-service"); + +logger.logRecordBuilder() + .setBody("User clicked the checkout button.") + .setSeverity(Severity.INFO) + .setSeverityText("INFO") + .setAttribute(AttributeKey.stringKey("cart.id"), "c-12345") + .setAttribute(AttributeKey.stringKey("user.id"), "u-54321") + .emit(); +``` + +### Trace and log correlation {% #trace-log-correlation-java %} + +Trace and log correlation is automatic. When you emit a log using the OTel Logs API within an active Datadog trace, the `trace_id` and `span_id` are automatically added to the log record. + +```java +import io.opentelemetry.api.GlobalOpenTelemetry; +import io.opentelemetry.api.logs.Logger; +import io.opentelemetry.api.logs.Severity; +import io.opentelemetry.api.trace.Span; +import io.opentelemetry.api.trace.Tracer; +import io.opentelemetry.context.Scope; + +Tracer tracer = GlobalOpenTelemetry.getTracer("my-service"); +Logger logger = GlobalOpenTelemetry.get().getLogsBridge().get("my-service"); + +Span span = tracer.spanBuilder("process.user.request").startSpan(); +try (Scope scope = span.makeCurrent()) { + // This log is automatically correlated with the active span + logger.logRecordBuilder() + .setBody("Processing user request for ID: 12345") + .setSeverity(Severity.INFO) + .setSeverityText("INFO") + .emit(); +} finally { + span.end(); +} +``` +{% /if %} + ## Supported configuration To enable this feature, you must set `DD_LOGS_OTEL_ENABLED=true`. @@ -1398,6 +1455,13 @@ The Datadog SDK programmatically configures the OTel SDK for you. 4. Set the `DD_LOGS_OTEL_ENABLED=true` environment variable. {% /if %} +{% if equals($prog_lang, "java") %} +1. Add the Datadog SDK (`dd-trace-java`) to your project and [enable its instrumentation][207]. +2. Remove any code that manually configures `SdkLoggerProvider` or an OTLP log record exporter (such as `OtlpHttpLogRecordExporter`). The Datadog SDK handles this configuration automatically. +3. Remove the `opentelemetry-sdk` and `opentelemetry-exporter-otlp` artifacts from your project's dependencies. Keep `opentelemetry-api`. +4. Set the `DD_LOGS_OTEL_ENABLED=true` environment variable. +{% /if %} + ### Existing Datadog log injection If you are using Datadog's traditional log injection (where `DD_LOGS_INJECTION=true` adds trace context to text logs) and an Agent to tail log files: @@ -1434,6 +1498,11 @@ If you are using Datadog's traditional log injection (where `DD_LOGS_INJECTION=t - Verify `datadog_opentelemetry::logs().init()` is called before using the logger. - Check protocol configuration. Only `grpc` and `http/protobuf` protocols are supported. HTTP/JSON is not supported. {% /if %} +{% if equals($prog_lang, "java") %} +- Verify `DD_LOGS_OTEL_ENABLED=true` is set. Logs are disabled by default in dd-trace-java. +- Verify Datadog automatic instrumentation is active. This feature relies on Datadog's automatic instrumentation to function. +- Verify your application only depends on the OpenTelemetry API. The Datadog SDK provides the OpenTelemetry SDK implementation. +{% /if %} {% /if %} From 22fc46bc1a42422cd9d479c9d107379192f8335a Mon Sep 17 00:00:00 2001 From: bm1549 Date: Thu, 14 May 2026 19:05:20 -0400 Subject: [PATCH 2/8] Align Java logs sections with Java metrics conventions Match the structure of the existing Java metrics content in the same file: - Trim Prerequisites to the Datadog SDK + opentelemetry-api version bullets. - Mirror Setup wording and indentation (3-space) used by Java metrics. - Revert Migrate to mirror Setup, matching how Java metrics handles migration (dd-trace-java is an agent-based implementation, not a manual SDK setup, so there is no SdkLoggerProvider/exporter to remove). - Trim Troubleshooting to the two most relevant bullets. --- .../instrument/dd_sdks/api_support.mdoc.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index 85b297550d7..eda09b2c586 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -917,9 +917,8 @@ If you encounter an issue after upgrading `@opentelemetry/api-logs`, [open an is - **OpenTelemetry Rust SDK**: The SDK provides the logs implementation automatically. {% /if %} {% if equals($prog_lang, "java") %} -- **Datadog SDK**: `dd-trace-java` version 1.62.0 or later. -- **OpenTelemetry Logs API**: Requires the `io.opentelemetry:opentelemetry-api` artifact version 1.27.0 or later (this is the version that introduced the stable logs API). -- **OTLP transport**: Java exports OTel logs only over OTLP HTTP/protobuf. Your OTLP destination must accept logs on port 4318. +- **Datadog SDK**: dd-trace-java version 1.62.0 or later. +- **OpenTelemetry API**: `opentelemetry-api` version 1.27.0 or later (the version that introduced the stable Logs API). {% /if %} - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel logs. @@ -1050,10 +1049,10 @@ Follow these steps to enable OTel Logs API support in your application. {% if equals($prog_lang, "java") %} 1. Add the Datadog SDK (`dd-trace-java`) to your project and [enable its instrumentation][207]. 2. Make sure you only depend on the OpenTelemetry API (and not the OpenTelemetry SDK). -3. Enable OTel logs export by setting the following environment variable: - ```sh - export DD_LOGS_OTEL_ENABLED=true - ``` +3. Enable OTel logs by setting the following environment variable: + ```sh + export DD_LOGS_OTEL_ENABLED=true + ``` {% /if %} ## Examples @@ -1457,9 +1456,8 @@ The Datadog SDK programmatically configures the OTel SDK for you. {% if equals($prog_lang, "java") %} 1. Add the Datadog SDK (`dd-trace-java`) to your project and [enable its instrumentation][207]. -2. Remove any code that manually configures `SdkLoggerProvider` or an OTLP log record exporter (such as `OtlpHttpLogRecordExporter`). The Datadog SDK handles this configuration automatically. -3. Remove the `opentelemetry-sdk` and `opentelemetry-exporter-otlp` artifacts from your project's dependencies. Keep `opentelemetry-api`. -4. Set the `DD_LOGS_OTEL_ENABLED=true` environment variable. +2. Make sure you only depend on the OpenTelemetry API (and not the OpenTelemetry SDK). +3. Set the `DD_LOGS_OTEL_ENABLED=true` environment variable. {% /if %} ### Existing Datadog log injection @@ -1501,7 +1499,6 @@ If you are using Datadog's traditional log injection (where `DD_LOGS_INJECTION=t {% if equals($prog_lang, "java") %} - Verify `DD_LOGS_OTEL_ENABLED=true` is set. Logs are disabled by default in dd-trace-java. - Verify Datadog automatic instrumentation is active. This feature relies on Datadog's automatic instrumentation to function. -- Verify your application only depends on the OpenTelemetry API. The Datadog SDK provides the OpenTelemetry SDK implementation. {% /if %} {% /if %} From 34b8f3d46e3c3137b58b74c1eaea196a5dfaa813 Mon Sep 17 00:00:00 2001 From: bm1549 Date: Thu, 14 May 2026 19:52:07 -0400 Subject: [PATCH 3/8] Drop duplicate DD_LOGS_OTEL_ENABLED bullet from Java troubleshooting The page already lists 'Verify DD_LOGS_OTEL_ENABLED is set to true' as a shared bullet at the top of the Troubleshooting section, so repeating it in the Java-specific block is redundant. --- content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index eda09b2c586..def6e16eab2 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -1497,7 +1497,6 @@ If you are using Datadog's traditional log injection (where `DD_LOGS_INJECTION=t - Check protocol configuration. Only `grpc` and `http/protobuf` protocols are supported. HTTP/JSON is not supported. {% /if %} {% if equals($prog_lang, "java") %} -- Verify `DD_LOGS_OTEL_ENABLED=true` is set. Logs are disabled by default in dd-trace-java. - Verify Datadog automatic instrumentation is active. This feature relies on Datadog's automatic instrumentation to function. {% /if %} From 7fe3cb87f5e69f3f840a9d9b8695bf92b27ea5dc Mon Sep 17 00:00:00 2001 From: bm1549 Date: Thu, 14 May 2026 19:56:17 -0400 Subject: [PATCH 4/8] Address PR feedback from @janine-c - Backtick `dd-trace-java` in the Java prerequisites for consistency with the other languages in the logs section. - Reorder the opentelemetry-api version qualifier so 'or later' attaches directly to 1.27.0 rather than being split by the parenthetical. - Drop the /opentelemetry/instrument/api_support/java/logs alias since no historical page existed at that URL to redirect from. --- .../en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index def6e16eab2..397c81afb81 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -12,7 +12,6 @@ aliases: - /opentelemetry/instrument/api_support/go/metrics - /opentelemetry/instrument/api_support/go/traces - /opentelemetry/instrument/api_support/java - - /opentelemetry/instrument/api_support/java/logs - /opentelemetry/instrument/api_support/java/metrics - /opentelemetry/instrument/api_support/java/traces - /opentelemetry/instrument/api_support/nodejs/ @@ -917,8 +916,8 @@ If you encounter an issue after upgrading `@opentelemetry/api-logs`, [open an is - **OpenTelemetry Rust SDK**: The SDK provides the logs implementation automatically. {% /if %} {% if equals($prog_lang, "java") %} -- **Datadog SDK**: dd-trace-java version 1.62.0 or later. -- **OpenTelemetry API**: `opentelemetry-api` version 1.27.0 or later (the version that introduced the stable Logs API). +- **Datadog SDK**: `dd-trace-java` version 1.62.0 or later. +- **OpenTelemetry API**: `opentelemetry-api` version 1.27.0 (the version that introduced the stable Logs API) or later. {% /if %} - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel logs. From 15e55f536b60406d5054e441ef7d6e5782bee2ba Mon Sep 17 00:00:00 2001 From: Stuart McCulloch Date: Fri, 15 May 2026 09:01:01 +0100 Subject: [PATCH 5/8] Update aliases --- content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index 397c81afb81..68058d2fbb9 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -12,6 +12,7 @@ aliases: - /opentelemetry/instrument/api_support/go/metrics - /opentelemetry/instrument/api_support/go/traces - /opentelemetry/instrument/api_support/java + - /opentelemetry/instrument/api_support/java/logs - /opentelemetry/instrument/api_support/java/metrics - /opentelemetry/instrument/api_support/java/traces - /opentelemetry/instrument/api_support/nodejs/ From b95e9eee1c3c2252d84776457afac761a66d9edb Mon Sep 17 00:00:00 2001 From: Stuart McCulloch Date: Fri, 15 May 2026 09:01:28 +0100 Subject: [PATCH 6/8] Consistency with other signals --- content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index 68058d2fbb9..e204e36e09e 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -182,7 +182,7 @@ The OpenTelemetry Metrics SDK for Ruby is currently in [alpha implementation](ht - **Rust**: MSRV 1.84 or later. {% /if %} {% if equals($prog_lang, "java") %} -- **Datadog SDK**: dd-trace-java version 1.61.0 or later. +- **Datadog SDK**: `dd-trace-java` version 1.61.0 or later. {% /if %} - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel metrics. {% if includes($prog_lang, ["dot_net", "node_js", "python", "ruby", "go", "java"]) %} From 9f88c084657505ca408453b19aef291650306565 Mon Sep 17 00:00:00 2001 From: bm1549 Date: Fri, 15 May 2026 09:52:18 -0400 Subject: [PATCH 7/8] Address PR review feedback: improve Java OTel troubleshooting text and fix prereq spacing - Tighten Java troubleshooting bullets in Metrics and Logs sections to explain why the javaagent is required (replaces vague "automatic instrumentation" phrasing) - Add blank line between Java logs prerequisite bullets for consistent rendering Co-Authored-By: Claude Sonnet 4.6 --- .../en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index e204e36e09e..ed579022a2b 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -830,7 +830,7 @@ If you are currently using the Datadog DogStatsD client and want to migrate to t - Verify `DD_METRICS_OTEL_ENABLED=true` is set before initializing the meter provider. {% /if %} {% if equals($prog_lang, "java") %} -- Verify Datadog automatic instrumentation is active. This feature relies on Datadog's automatic instrumentation to function. +- Verify the `dd-trace-java` javaagent is running. The javaagent registers itself as the global OTel MeterProvider at startup; without it, OTel API calls fall through to no-op providers and no data is sent. {% /if %} {% if equals($prog_lang, "dot_net") %} @@ -918,6 +918,7 @@ If you encounter an issue after upgrading `@opentelemetry/api-logs`, [open an is {% /if %} {% if equals($prog_lang, "java") %} - **Datadog SDK**: `dd-trace-java` version 1.62.0 or later. + - **OpenTelemetry API**: `opentelemetry-api` version 1.27.0 (the version that introduced the stable Logs API) or later. {% /if %} - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel logs. @@ -1497,7 +1498,7 @@ If you are using Datadog's traditional log injection (where `DD_LOGS_INJECTION=t - Check protocol configuration. Only `grpc` and `http/protobuf` protocols are supported. HTTP/JSON is not supported. {% /if %} {% if equals($prog_lang, "java") %} -- Verify Datadog automatic instrumentation is active. This feature relies on Datadog's automatic instrumentation to function. +- Verify the `dd-trace-java` javaagent is running. The javaagent registers itself as the global OTel LoggerProvider at startup; without it, OTel API calls fall through to no-op providers and no data is sent. {% /if %} {% /if %} From 7d052b98597d945a49f903a4b589ef50d812d9b2 Mon Sep 17 00:00:00 2001 From: Brian Marks Date: Fri, 15 May 2026 11:48:08 -0400 Subject: [PATCH 8/8] Update content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md Co-authored-by: Duncan Hewett --- content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md index ed579022a2b..a7b43bdb122 100644 --- a/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md +++ b/content/en/opentelemetry/instrument/dd_sdks/api_support.mdoc.md @@ -919,6 +919,7 @@ If you encounter an issue after upgrading `@opentelemetry/api-logs`, [open an is {% if equals($prog_lang, "java") %} - **Datadog SDK**: `dd-trace-java` version 1.62.0 or later. + - **OpenTelemetry API**: `opentelemetry-api` version 1.27.0 (the version that introduced the stable Logs API) or later. {% /if %} - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel logs.