OTel Metrics & Logs API Clarifications #33503
Conversation
| - Remains free of vendor-specific API calls. | ||
| - Does not depend on Datadog SDKs at compile time (only runtime). | ||
|
|
||
| **Important**: Do not include the OpenTelemetry SDK in your application's dependencies. The Datadog SDK provides the implementation of the OpenTelemetry API. Including the OpenTelemetry SDK may cause conflicts or unexpected behavior. |
There was a problem hiding this comment.
This is language specific. User's should avoid using the OpenTelemetry SDK in Java, NodeJS, and .NET but we require the installation of the opentelemetry-sdk to send metrics and logs in Python, Ruby, Golang, PHP, and Rust.
There was a problem hiding this comment.
Thanks! This should be correctly explained in our overview shortcodes already for each affected language.
| - **Datadog SDK**: dd-trace-dotnet version 3.30.0 or later. | ||
| - **An OTLP-compatible destination**: You must have a destination ready to receive OTLP data, such as the Datadog Agent or OpenTelemetry Collector. | ||
| - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel metrics. | ||
| - **DogStatsD (Runtime Metrics)**: If you also use Datadog Runtime Metrics, ensure the Datadog Agent is listening for DogStatsD traffic on port 8125 (UDP). OTel configuration does not route Runtime Metrics through OTLP. |
There was a problem hiding this comment.
Should we link to the runtime metrics page here: https://docs.datadoghq.com/tracing/metrics/runtime_metrics/?
| - **OpenTelemetry API**: `@opentelemetry/api` version 1.0.0 to 1.10.0. (The Datadog SDK provides the implementation for this API). | ||
| - **An OTLP-compatible destination**: You must have a destination ready to receive OTLP data, such as the Datadog Agent or OpenTelemetry Collector. | ||
| - **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel metrics. | ||
| - **DogStatsD (Runtime Metrics)**: If you also use Datadog Runtime Metrics, ensure the Datadog Agent is listening for DogStatsD traffic on port 8125 (UDP). OTel configuration does not route Runtime Metrics through OTLP. |
There was a problem hiding this comment.
This should apply to all SDKs. Should we move this to the _index.md page?
There was a problem hiding this comment.
I think it would be better to leave this on the language-specific pages. That is the most common place a user will land, so I want to make sure they see that info close to the source. The network requirements table now exists on the environment variable config page too. So I want to be careful about putting it in too many places and making a maintenance headache.
|
|
||
| <div class="alert alert-info">You should not install the official OpenTelemetry SDK or any OTLP Exporter packages. The Datadog SDK provides this functionality. Installing both can lead to runtime conflicts and duplicate data.</div> | ||
| - **Do** install the standard OpenTelemetry API packages (`io.opentelemetry:opentelemetry-api`) to instrument your code. | ||
| - **Do Not** install the OpenTelemetry SDK packages (`opentelemetry-sdk`). The Datadog SDK acts as the implementation provider; installing both can lead to runtime conflicts and duplicate telemetry. |
There was a problem hiding this comment.
See above. This is not true any more. Some Datadog SDKs are compatible with the OpenTelemetry SDKs (ex: Java is not). We can call this out in the library specific sections.
There was a problem hiding this comment.
Thanks! Existing guidance should be sufficient. I'm going to revert this.
brett0000FF
force-pushed
the
brett.blue/DOCS-12862
branch
from
30828cc to
38e6119
Compare
|
@mabdinur - Appreciate you taking a look! Cleaned this up some more based on your feedback. This should now address the core confusion we want to clarify. |
What does this PR do? What is the motivation?
Updates to new OTel Metrics and Logs API Support docs following an internal thread noting some confusion. There was an assumption that using the Datadog SDK with the OTel API meant all data would transition to OTLP.
Merge instructions
Merge readiness:
For Datadog employees:
Your branch name MUST follow the
<name>/<description>convention and include the forward slash (/). Without this format, your pull request will not pass CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.If your branch doesn't follow this format, rename it or create a new branch and PR.
[6/5/2025] Merge queue has been disabled on the documentation repo. If you have write access to the repo, the PR has been reviewed by a Documentation team member, and all of the required checks have passed, you can use the Squash and Merge button to merge the PR. If you don't have write access, or you need help, reach out in the #documentation channel in Slack.
Additional notes