docs: add distributed trace propagation section to tracing guide

[ankurs]

Summary

Add "Distributed Trace Propagation (W3C)" section to the tracing howto guide. This was meant to be part of #45 but was pushed after the PR was already merged.

Content

• Table of automatic propagation flows (incoming gRPC/HTTP, gateway, outgoing gRPC)
• Outgoing HTTP call examples with NewHTTPExternalSpan
• Manual injection for plain http.Client usage
• Verification tips for tracing backends

Summary by CodeRabbit

• Documentation
  • Added a guide on W3C distributed trace propagation and how it differs from app-level trace IDs.
  • Documented automatic trace propagation paths across HTTP and gRPC and how outgoing HTTP spans are created.
  • Added a warning and manual-injection example for requests made without the helper.
  • Included a verification checklist to confirm trace linkage in backends.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 321920ec-33f7-4165-b74d-9edf1513ece7

📥 Commits

Reviewing files that changed from the base of the PR and between 77394eb and e60663f.

📒 Files selected for processing (1)

• howto/Tracing.md

✅ Files skipped from review due to trivial changes (1)

• howto/Tracing.md

---

📝 Walkthrough

Walkthrough

Added a new "Distributed Trace Propagation (W3C)" section to howto/Tracing.md documenting OpenTelemetry W3C traceparent/tracestate propagation, automatic propagation points across HTTP/gRPC/gateway boundaries, examples for creating outgoing HTTP external spans, manual-injection guidance, and a verification checklist.

Changes

Cohort / File(s)

Summary

Distributed Trace Propagation Documentation howto/Tracing.md

New section describing W3C traceparent/tracestate propagation, distinctions from ColdBrew app trace ID, automatic propagation paths (incoming gRPC via OTEL stats handler, incoming HTTP via gateway tracing middleware, HTTP→gRPC W3C linking, gRPC server→client injection), tracing.NewHTTPExternalSpan outgoing HTTP example, manual injection warning with otel.GetTextMapPropagator().Inject(...), and verification checklist.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• docs: update for OTEL migration — remove OpenTracing references #44 — Updates howto/Tracing.md with OpenTelemetry W3C traceparent/tracestate propagation details and related tracing documentation changes.

Poem

🐰 I hop through headers, tiny and spry,
traceparent tucked under my eye,
From HTTP to gRPC I carry the string,
Linking each span as I softly spring.
🌿✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding documentation about distributed trace propagation (W3C) to the tracing guide, which is confirmed by the +52 lines of documentation content in howto/Tracing.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/trace-propagation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

howto/Tracing.md (1)

219-240: Consider making the HTTP snippets copy/paste ready.

Nice examples. As a small docs usability improvement, include imports and minimal error handling so readers can run them directly.

📌 Optional docs tweak

 ```go
+import (
+    "net/http"
+
+    "github.com/go-coldbrew/tracing"
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/propagation"
+)
+
 span, ctx := tracing.NewHTTPExternalSpan(ctx, "other-service", "/api/data", nil)
 defer span.End()

-req, _ := http.NewRequestWithContext(ctx, "GET", "https://other-service/api/data", nil)
+req, err := http.NewRequestWithContext(ctx, "GET", "https://other-service/api/data", nil)
+if err != nil {
+    return err
+}
 // Inject trace headers into the outgoing request
 otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))

 resp, err := http.DefaultClient.Do(req)
+if err != nil {
+    return err
+}

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @howto/Tracing.md around lines 219 - 240, Add missing imports and minimal
error handling so the HTTP examples are copy/paste runnable: include the
standard net/http import plus "github.com/go-coldbrew/tracing",
"go.opentelemetry.io/otel" and "go.opentelemetry.io/otel/propagation" at the
top, and check/handle errors returned by http.NewRequestWithContext and
http.DefaultClient.Do (do not ignore the err values); when using the hdr variant
ensure req.Header = hdr is used and still validate the request creation and
response error before proceeding, keeping references to NewHTTPExternalSpan,
otel.GetTextMapPropagator().Inject, propagation.HeaderCarrier,
http.NewRequestWithContext and req.Header so reviewers can locate the changes.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @howto/Tracing.md:

• Around line 219-240: Add missing imports and minimal error handling so the
  HTTP examples are copy/paste runnable: include the standard net/http import plus
  "github.com/go-coldbrew/tracing", "go.opentelemetry.io/otel" and
  "go.opentelemetry.io/otel/propagation" at the top, and check/handle errors
  returned by http.NewRequestWithContext and http.DefaultClient.Do (do not ignore
  the err values); when using the hdr variant ensure req.Header = hdr is used and
  still validate the request creation and response error before proceeding,
  keeping references to NewHTTPExternalSpan, otel.GetTextMapPropagator().Inject,
  propagation.HeaderCarrier, http.NewRequestWithContext and req.Header so
  reviewers can locate the changes.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `2bbaace5-bded-4e9b-a823-fe3177fd33c0`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 366b8ca88864168f4fdda2ff41d4d188ee97e188 and 77394ebfdd4672942422703d83eeff22f960acbd.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `howto/Tracing.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[Copilot]

Pull request overview

Adds a new section to the tracing how-to explaining W3C trace-context propagation (traceparent/tracestate) and how it relates to ColdBrew’s application-level trace ID.

Changes:

• Documented which propagation flows are handled automatically across HTTP/gRPC boundaries.
• Added outgoing HTTP examples using NewHTTPExternalSpan, including manual header injection.
• Added tips for verifying propagation in a tracing backend.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.