docs: clearer distributed tracing setup and troubleshooting

[thomhurst]

Summary

• Adds a symptom-driven Troubleshooting section to docs/examples/opentelemetry.md covering the five most common pain points reported in HTML report generation failed #5479 (mixed traces, orphan spans, propagator mismatch, missing HTTP propagation, no spans at all). Each entry leads with the symptom in plain English, gives a one-block fix, and only then explains why.
• Adds a new Distributed Tracing guide at docs/guides/distributed-tracing.md consolidating per-backend setup (Seq, Jaeger/Tempo, Aspire, generic OTLP), correlation strategies, propagator alignment, and limitations. Surfaced in the Integrations sidebar next to the existing OpenTelemetry guide.
• Moves the "use TestWebApplicationFactory<T>, not the vanilla WebApplicationFactory<T>" guidance into a top-of-page warning callout in docs/examples/aspnet.md so users see it before silently losing trace correlation.
• Adds a short note to docs/guides/html-report.md explaining why the same Activity data renders differently in the HTML report vs. an OTel backend.

Cross-references the planned automation work in:

• Auto-suppress ExecutionContext flow when starting IHostedService in TestWebApplicationFactory #5589 — IHostedService flow suppression
• Auto-register IHttpMessageHandlerBuilderFilter for IHttpClientFactory in TUnit.AspNetCore #5590 — IHttpMessageHandlerBuilderFilter auto-registration
• Ship opt-in OpenTelemetry ActivityProcessor that tags spans with tunit.test.id #5591 — opt-in TUnitTagProcessor for spans whose parent chain is broken
• Auto-align DistributedContextPropagator to W3C in test and SUT processes #5592 — propagator alignment to W3C
• New TUnit.OpenTelemetry package: auto-start TracerProvider in test process #5593 — new TUnit.OpenTelemetry package, auto-start in test process
• Auto-wire OpenTelemetry inside TestWebApplicationFactory's SUT #5594 — TestWebApplicationFactory SUT-side OTel auto-wire
• Generalize TUnit.Aspire's OTLP receiver for use outside Aspire #5595 — generalize the OTLP receiver beyond Aspire
• Roslyn analyzer + code fix: convert WebApplicationFactory<T> to TestWebApplicationFactory<T> #5596 — Roslyn analyzer + code fix for WebApplicationFactory<T> → TestWebApplicationFactory<T>

Each of those issues has a "Documentation" section listing which of these pages to revise when the automation lands, so the manual recipes added here can be trimmed in step.

Test plan

• Build the docs site (docs/) and confirm the new page appears in the Integrations sidebar.
• Verify all cross-page links resolve (./aspnet.md, ./distributed-tracing.md, anchors).
• Skim render in the docs site preview to check callouts and tables.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

[claude]

Documentation Review

Overall this is well-structured, practical documentation. The symptom-driven troubleshooting format is exactly right for this kind of guide — users arrive with a problem, not a curiosity, so leading with the symptom and putting the explanation second is the correct priority order. The tag-reference tables are clear and the cross-references are tight. Good work.

A few things worth addressing:

---

1. TracedWebApplicationFactory<T> is documented before it exists

Both aspnet.md and opentelemetry.md present TracedWebApplicationFactory<T> as a usable escape hatch today:

var traced = new TracedWebApplicationFactory<Program>(myExistingFactory);
var client = traced.CreateClient(); // tracing + logging now wired up

But per the PR description, the actual implementation is tracked in #5594 (not yet merged). A user hitting the "My HTTP calls don't carry the test trace" symptom right now will find working-looking code that doesn't compile.

Suggested fix: Either defer those specific code blocks until #5594 ships, or wrap them in an :::caution admonition:

:::caution Coming soon
`TracedWebApplicationFactory<T>` is not yet available. Tracking: [#5594](https://github.com/thomhurst/TUnit/issues/5594). Until it ships, use `TestWebApplicationFactory<T>` directly.
:::

This is the most user-visible issue in the PR.

---

2. Propagator setup code is duplicated verbatim across two pages

The full CompositeTextMapPropagator block appears identically in both opentelemetry.md (troubleshooting) and distributed-tracing.md (cross-process section). If the recommended propagator set ever changes (e.g., adding B3Propagator for Zipkin compatibility), both pages drift independently.

Docusaurus supports MDX import for shared snippets:

<!-- docs/src/snippets/propagator-setup.mdx -->
```csharp
Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator([
    new TraceContextPropagator(),
    new BaggagePropagator(),
]));

Then in each page:
```md
import PropagatorSetup from '@site/src/snippets/propagator-setup.mdx';
<PropagatorSetup />

Not blocking, but will pay off when the propagator alignment automation (#5592) lands and changes the recommended setup.

---

3. Sidebar placement mixes guides/ into the Integrations category

guides/distributed-tracing is placed inside the "Integrations" sidebar category alongside examples/* entries. The project already does this (e.g., guides/performance in "Running Tests"), so it's not a new pattern, but it does mean a user browsing "Guides" in the sidebar won't find this page.

Given that this guide is explicitly about a cross-cutting concern (not a single integration), it might sit better as the last item in "Integrations" rather than sandwiched between two unrelated examples (opentelemetry → distributed-tracing → filebased-csharp). Minor, but the current position reads as if it's a sub-page of the OTel example rather than a standalone guide.

---

Minor

• distributed-tracing.md links to /docs/examples/opentelemetry#spans-from-test-a-are-showing-up-under-test-b but the actual heading is "Spans from test A are showing up under test B" (with surrounding quotes). Docusaurus strips quotes for anchor generation so the link should resolve correctly, but worth verifying in the docs build.
• The html-report.md callout note is a nice touch — exactly the kind of "same data, different view" confusion users hit and search for.