Skip to content

Conversation

brett0000FF
Copy link
Contributor

@brett0000FF brett0000FF commented Aug 11, 2025

What does this PR do? What is the motivation?

Addresses the fragmented user experience for setting up NGINX APM tracing and log correlation. Previously, the instructions were split between the main Instrumenting NGINX page and the more general Ease Troubleshooting With Cross-Product Correlation guide. This required users to navigate between two separate documents to complete a single, common workflow.

This update consolidates all NGINX-specific instructions into the Instrumenting NGINX document.

Changes Made

Modified tracing/trace_collection/proxy_setup.md:

  • Added a new "Correlating traces to logs" section to the end of the document.
  • This section provides clear, tabbed instructions for injecting the trace ID using both the Datadog NGINX module ($datadog_trace_id) and the NGINX OpenTelemetry module ($opentelemetry_trace_id).
  • Introduced a simplified Grok parsing rule that handles the output from both instrumentation methods.

Modified logs/guide/ease-troubleshooting-with-cross-product-correlation.md:

  • Removed the now-redundant, NGINX-specific configuration details from this guide.
  • Replaced the removed content with a concise paragraph that links directly to the updated Instrumenting NGINX page, establishing it as the single source of truth for this procedure.

Merge instructions

Merge readiness:

  • Ready for merge

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

@brett0000FF brett0000FF added the Do Not Merge Just do not merge this PR :) label Aug 11, 2025
@brett0000FF brett0000FF requested a review from a team as a code owner August 11, 2025 22:53
Copy link
Contributor

github-actions bot commented Aug 11, 2025

✅ Documentation Team Review

The documentation team has approved this pull request. Thank you for your contribution!

Copy link
Contributor

github-actions bot commented Aug 11, 2025

@github-actions github-actions bot added the Guide Content impacting a guide label Aug 15, 2025
@brett0000FF brett0000FF requested a review from dmehala August 18, 2025 15:35
Copy link
Contributor

@dmehala dmehala left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC adding the span ID provide granular correlation between logs and spans. I would recommend setting the span ID but in under no circumstances I think it is mandatory. Up to you to add it or not.

LGTM, excellent job. Thank you @brett0000FF !

{{< tabs >}}
{{% tab "Datadog NGINX Module" %}}

If you installed the [Datadog NGINX module][100], use the `$datadog_trace_id` variable. This value is `-` for requests that are not traced.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also suggest to use the span ID with $datadog_span_id. The OTel equivalent is $opentelemetry_span_id.

1. Select [Grok Parser][10] as the processor type.
1. Define the following parsing rule to extract the trace ID attribute from a log event. This rule works for both the Datadog module and OpenTelemetry outputs:
```text
extract_trace_id %{data} dd.trace_id="%{notSpace:dd.trace_id:nullIf("-")}"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you decide to add the span ID, you might also need to update the grok query

@brett0000FF brett0000FF removed the Do Not Merge Just do not merge this PR :) label Aug 20, 2025
Copy link
Contributor

@aliciascott aliciascott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @brett0000FF looks good just one broken link that needs moved from the bottom of the page to the tab content.

@brett0000FF brett0000FF merged commit a0a0f38 into master Aug 20, 2025
17 of 18 checks passed
@brett0000FF brett0000FF deleted the brett.blue/DOCS-11738 branch August 20, 2025 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Guide Content impacting a guide
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants