Use Cdocs Page Filtering for OTel API Docs #33640
Conversation
github-actions
bot
added
Architecture
brett0000FF
changed the title
|
DOCS-13108 for Docs review |
| <!-- ============================================== --> | ||
|
|
||
| <!-- Languages with only traces: Go, PHP, Java, Rust --> | ||
| {% if or(or(or(equals($prog_lang, "go"), equals($prog_lang, "php")), equals($prog_lang, "java")), equals($prog_lang, "rust")) %} |
There was a problem hiding this comment.
| {% if or(or(or(equals($prog_lang, "go"), equals($prog_lang, "php")), equals($prog_lang, "java")), equals($prog_lang, "rust")) %} | |
| {% if or(equals($prog_lang, "go"), equals($prog_lang, "php"), equals($prog_lang, "java"), equals($prog_lang, "rust")) %} |
and and or can take as many arguments as you need. The Confluence docs probably misled you on this one, because I actually didn't know this was possible until recently! I've added a todo for myself to make this clear in Confluence and include examples.
| {% /if %} | ||
| {% /if %} | ||
|
|
||
| <!-- Ruby has traces and metrics only --> |
There was a problem hiding this comment.
I love the style of these explainers, it's a lot more readable than just "Ruby" etc as I was using.
| {% if equals($platform, "logs") %} | ||
|
|
||
| <!-- Show content only for languages that support logs --> | ||
| {% if or(or(equals($prog_lang, "dot_net"), equals($prog_lang, "node_js")), equals($prog_lang, "python")) %} |
There was a problem hiding this comment.
| {% if or(or(equals($prog_lang, "dot_net"), equals($prog_lang, "node_js")), equals($prog_lang, "python")) %} | |
| {% if or(equals($prog_lang, "dot_net"), equals($prog_lang, "node_js"), equals($prog_lang, "python")) %} |
| @@ -1,167 +1,232 @@ | |||
| --- | |||
There was a problem hiding this comment.
Any generated Cdocs files (formerly the actual markup file for the page) should just be deleted from version control, and should be in the .gitignore from there. This is a common issue in Cdocs PRs so far though, open to ideas around how to make this part of the flow easier for authors. It's just kind of inherently confusing. I've talked to Heston about a pre-commit hook that makes sure no .mdoc.md file has an .md twin present in version control.
| @@ -1,205 +1,312 @@ | |||
| --- | |||
There was a problem hiding this comment.
Delete compiled file from version control
| @@ -1,253 +1,392 @@ | |||
| --- | |||
| @@ -1,170 +1,271 @@ | |||
| --- | |||
| @@ -1,166 +1,270 @@ | |||
| --- | |||
|
|
||
| ## Overview | ||
|
|
||
| There are a few reasons to manually instrument your applications with the OpenTelemetry API: |
There was a problem hiding this comment.
It seems like this Overview copy could also be a partial, but there may be minor differences in it that I'm not aware of.
| - trait_id: prog_lang | ||
| option_group_id: otel_api_support_language_options | ||
| label: "Language" | ||
| - trait_id: platform |
There was a problem hiding this comment.
I'm fine with using platform here, but as you migrate, if you notice it's becoming overloaded (means different things across your pages, which keeps the customer's values from "sticking" as often as they could), feel free to add more traits, like feature, to distinguish them better.
duncanhewett
left a comment
duncanhewett
left a comment
There was a problem hiding this comment.
Looks good, I added a couple of suggestions!
| {% /if %} | ||
| {% /if %} | ||
|
|
||
| Datadog SDKs implement the [OpenTelemetry API][1], allowing you to instrument your code with vendor-neutral APIs while benefiting from Datadog's native implementation and features. Your code remains free of vendor-specific calls and doesn't depend on Datadog SDKs at compile time. |
There was a problem hiding this comment.
I'm not sure it's necessary to have this information (and the diagram below) on each individual API page, since it's on the parent page (https://docs-staging.datadoghq.com/brett.blue/otel-api-cdocs/opentelemetry/instrument/dd_sdks).
I think that content is a bit distracting when you just want to see how to use the API, although I understand sometimes users will navigate directly to the API page.
| {% /if %} | ||
| {% if equals($platform, "logs") %} | ||
| {% alert level="danger" %} | ||
| OpenTelemetry API support for logs is not available for this language. Select **Traces** to see available instrumentation options. |
There was a problem hiding this comment.
Where we don't support an API for a language, rather than directing to other instrumentation types it would be better to redirect to the non-OTel API equivalent. For example if Metrics isn't available for Java, the alternative is DogStatsD not the OTel Logs API.
Also it wasn't that obvious to me that an API wasn't support - I skimmed over the caution box and just looked at the overview/diagram (maybe removing them would solve the issue - see my other comment).
What does this PR do? What is the motivation?
OTel API Support: https://docs-staging.datadoghq.com/brett.blue/otel-api-cdocs/opentelemetry/instrument/dd_sdks/api_support/?platform=traces&prog_lang=java
Tracing (these should basically be the same except for the overviews): https://docs-staging.datadoghq.com/brett.blue/otel-api-cdocs/tracing/trace_collection/custom_instrumentation/java/otel
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