docs: update for native stats/opentelemetry migration

[ankurs]

Summary

• Add new env vars to config reference: OTEL_USE_LEGACY_INSTRUMENTATION, ENABLE_OTEL_METRICS, OTEL_METRICS_INTERVAL
• Update OTLP_USE_OPENTRACING_BRIDGE as removed (ignored with warning)
• Remove UseOpenTracingBridge from OTLPConfig struct display and code examples in integrations page
• Update FAQ OpenTracing migration answer — bridge is now removed
• Update howto/Debugging.md profiling table — replace otelgrpc.TagRPC with native stats handler

Companion to core migration in go-coldbrew/core (roadmap item 8.1).

Test plan

• Verify docs site builds locally (bundle exec jekyll serve)
• Check config-reference page renders new env var rows correctly
• Check integrations page code examples compile without UseOpenTracingBridge

Summary by CodeRabbit

• Documentation

  • Migration guidance updated: OpenTracing bridge removed; docs now instruct migrating to native OpenTelemetry and note the old bridge setting is ignored and logs a startup warning.
  • New config entries documented: OTEL_USE_LEGACY_INSTRUMENTATION, ENABLE_OTEL_METRICS, OTEL_METRICS_INTERVAL.
  • Added opt-in OpenTelemetry metrics docs, updated integration examples, and revised gRPC/OpenTelemetry profiling notes.

• Tests

  • External-links test relaxed to accept 2xx/3xx or 429 and report status in errors.

[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: 03340a01-712a-4e5e-9fc5-0f933f83ef0c

📥 Commits

Reviewing files that changed from the base of the PR and between 602cf99 and 1b7f8c9.

📒 Files selected for processing (1)

• tests/links.spec.ts

---

📝 Walkthrough

Walkthrough

Documentation updated to remove the OpenTracing→OpenTelemetry bridge: migration guidance, config references, and examples now require native OpenTelemetry usage; OTLP_USE_OPENTRACING_BRIDGE is ignored (logs a startup warning if true); new env vars documented for legacy gRPC instrumentation and OTLP metrics export.

Changes

Cohort / File(s)	Summary
Migration & FAQ FAQ.md	Removed OpenTracing bridge instructions; instruct replacing opentracing.GlobalTracer() with otel.Tracer("my-service"); state internal span constructors are OpenTelemetry-native; note OTLP_USE_OPENTRACING_BRIDGE=true is ignored and emits a startup warning.
Configuration reference config-reference.md	Mark OTLP_USE_OPENTRACING_BRIDGE as ignored (warns when true); add OTEL_USE_LEGACY_INSTRUMENTATION (bool, default false), ENABLE_OTEL_METRICS (bool, default false), and OTEL_METRICS_INTERVAL (int, default 60); update deprecated-table entry.
Integrations & examples integrations.md	Added "OpenTelemetry Metrics" section; removed UseOpenTracingBridge from OTLPConfig examples/snippets; documented OTLP-exported gRPC metrics and noted promauto custom metrics are not auto-exported via OTLP.
Metrics how-to & production notes howto/Metrics.md, howto/production.md	Changed metrics guidance from Prometheus-only to Prometheus + OTLP metrics; documented env vars (ENABLE_OTEL_METRICS, OTEL_METRICS_INTERVAL, OTLP_ENDPOINT), listed exported gRPC metrics, and noted OTLP runs alongside Prometheus scraping.
Debugging / profiling docs howto/Debugging.md	Renamed otelgrpc.TagRPC reference to "gRPC OpenTelemetry stats handler"; updated CPU/allocation profile wording to reference OpenTelemetry span creation.
Tests tests/links.spec.ts	Relaxed external-links test to accept HTTP 2xx/3xx or 429 rate-limited responses and report captured status in error messages.

Sequence Diagram(s)

(none — changes are documentation and configuration updates without new cross-component runtime control flow requiring visualization.)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: update for OTEL migration — remove OpenTracing references #44: Overlapping removal of the OpenTracing bridge and updates to OTLP examples and docs.
• docs: fix sampling defaults, Log API refs, and deprecation table #52: Prior deprecation/update changes for OTLP_USE_OPENTRACING_BRIDGE in config docs.
• docs: add distributed tracing section to production deployment guide #45: Related production/tracing documentation updates and OTLP environment-variable guidance.

Poem

🐰 I hopped through docs, the old bridge gone,

Otel leaves glow at the break of dawn.
Spans now whisper in native tone,
Metrics travel on a brand-new road.
Hoppity-hop — the meadow's grown!

🚥 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 title accurately reflects the main changes: updating documentation for the OpenTelemetry/stats migration, including removal of the OpenTracing bridge and addition of native metrics configuration.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/otel-migration-8.1

---

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.}

[Copilot]

Pull request overview

Updates ColdBrew documentation to reflect the migration away from legacy OpenTracing bridge support and toward native OpenTelemetry instrumentation (incl. new metrics-related configuration).

Changes:

• Remove UseOpenTracingBridge from OTLPConfig struct display and integrations examples.
• Update OpenTracing→OpenTelemetry migration guidance in the FAQ to reflect bridge removal.
• Expand config reference with new OpenTelemetry env vars and clarify OTLP_USE_OPENTRACING_BRIDGE is now ignored (warning-only), plus adjust debugging docs to reference the gRPC OTel stats handler.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
integrations.md	Removes deprecated bridge field from OTLPConfig docs and code examples.
howto/Debugging.md	Updates profiling table terminology from otelgrpc.TagRPC to the gRPC OTel stats handler.
FAQ.md	Revises migration guidance to reflect bridge removal and native OTel usage.
config-reference.md	Adds new OTel env vars and clarifies deprecated/ignored bridge env var behavior.

---

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

[coderabbitai]

🧹 Nitpick comments (1)

howto/Debugging.md (1)

68-68: Consider minor terminology consistency improvement.

The table entry correctly replaces the deprecated otelgrpc.TagRPC reference with the native stats handler. However, howto/Tracing.md (line 242-251) uses "OTEL gRPC stats handler" while this uses "gRPC OpenTelemetry stats handler". Both are correct, but consistent terminology across documentation files would improve clarity.

📝 Optional consistency fix

To match the terminology in howto/Tracing.md:

-| gRPC OpenTelemetry stats handler | ~1% | OpenTelemetry span creation |
+| OTEL gRPC stats handler | ~1% | OpenTelemetry span creation |

🤖 Prompt for AI Agents

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

In `@howto/Debugging.md` at line 68, Update the terminology in the Debugging.md
table row that currently reads "gRPC OpenTelemetry stats handler" to match the
wording used in howto/Tracing.md ("OTEL gRPC stats handler") for consistency;
locate the table row containing "gRPC OpenTelemetry stats handler" and replace
that phrase with "OTEL gRPC stats handler" so both docs use the same term.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@howto/Debugging.md`:
- Line 68: Update the terminology in the Debugging.md table row that currently
reads "gRPC OpenTelemetry stats handler" to match the wording used in
howto/Tracing.md ("OTEL gRPC stats handler") for consistency; locate the table
row containing "gRPC OpenTelemetry stats handler" and replace that phrase with
"OTEL gRPC stats handler" so both docs use the same term.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 65c32daa-6684-4c8c-9c6e-eb471614538d

📥 Commits

Reviewing files that changed from the base of the PR and between ce2d122 and ad6fa9e.

📒 Files selected for processing (4)

• FAQ.md
• config-reference.md
• howto/Debugging.md
• integrations.md

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

---

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