docs: fix sampling defaults, Log API refs, and deprecation table

[ankurs]

Summary

• Fix NEW_RELIC_OPENTELEMETRY_SAMPLE and OTLP_SAMPLING_RATIO defaults from 0.2 to 0.1 in config-reference.md (code changed in OTEL sampling reduction)
• Replace loggers.AddToLogContext with log.AddToContext (public API) throughout Log.md
• Add missing deprecated entries to config-reference.md: DISABLE_PORMETHEUS, OTLP_USE_OPENTRACING_BRIDGE, GRPCClientInterceptor()
• Add slog migration note for deprecated gokit/logrus backends in Log.md

Test plan

• All 56 Playwright tests pass
• No stale 0.2 defaults remain in config-reference.md
• No loggers.AddToLogContext references remain in Log.md

Summary by CodeRabbit

Documentation

• Updated trace sampling defaults in reference docs (default ratio adjusted from 0.2 to 0.1).
• Added deprecation guidance, including mapping a common typo variant to the correct prometheus setting and guidance to remove the legacy OpenTracing bridge option.
• Revised logging how‑to examples to use the current context-aware logging approach, simplified example code, and clarified migration guidance for logging backend selection.

[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: 9d754565-6132-4b18-ac7e-1a17575f946c

📥 Commits

Reviewing files that changed from the base of the PR and between 178ee7d and 5d4ec06.

📒 Files selected for processing (2)

• config-reference.md
• howto/Log.md

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

• config-reference.md

🚧 Files skipped from review as they are similar to previous changes (1)

• howto/Log.md

---

📝 Walkthrough

Walkthrough

Documentation-only updates: default trace sampling ratios lowered from 0.2 to 0.1; added deprecation entry for DISABLE_PORMETHEUS typo; marked OTLP_USE_OPENTRACING_BRIDGE for removal; replaced deprecated logging helper in examples with the current log.AddToContext usage.

Changes

Cohort / File(s)	Summary
Config reference config-reference.md	Lowered documented defaults for NEW_RELIC_OPENTELEMETRY_SAMPLE and OTLP_SAMPLING_RATIO from 0.2 → 0.1; added DISABLE_PORMETHEUS typo mapping to DISABLE_PROMETHEUS; marked OTLP_USE_OPENTRACING_BRIDGE as removable.
Logging how-to howto/Log.md	Replaced loggers.AddToLogContext examples with log.AddToContext; removed github.com/go-coldbrew/log/loggers import from snippets; clarified migration requires removing explicit backend selection so default slog is used; minor heading/text edits.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: update for OTEL migration — remove OpenTracing references #44: Also updates OTLP_USE_OPENTRACING_BRIDGE deprecation/removal entries.
• docs: add distributed tracing section to production deployment guide #45: Related changes to documented OpenTelemetry sampling env vars (OTLP_SAMPLING_RATIO, NEW_RELIC_OPENTELEMETRY_SAMPLE).
• docs: update for slog default backend and deprecations #42: Related logging doc updates reflecting slog default backend and logging API migration.

Poem

🐰 I hopped through docs at break of day,
Trimmed sampling rates to find the way,
Swapped old log hooks for a newer call,
Fixed a typo tumbling from the wall,
ColdBrew bounces — tidy, light, and gay!

🚥 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 summarizes all three main documentation fixes: sampling defaults adjustment, Log API reference updates, and deprecation table additions.
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/fix-config-defaults-and-api-refs

---

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

This PR updates the documentation to align with recent observability/logging API changes, clarifies deprecations, and adds guidance for registering custom (non-gRPC) HTTP routes on the grpc-gateway mux.

Changes:

• Update documented default sampling ratios for NEW_RELIC_OPENTELEMETRY_SAMPLE and OTLP_SAMPLING_RATIO to 0.1 and extend the deprecated settings table.
• Replace loggers.AddToLogContext references with the public log.AddToContext API and add a slog migration note.
• Add a new “Custom HTTP Routes” section (with examples) and an FAQ entry pointing to it.

Reviewed changes

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

File	Description
howto/Log.md	Updates context-aware logging examples to use log.AddToContext and adds slog migration guidance.
howto/APIs.md	Documents registering custom HTTP routes via runtime.ServeMux.HandlePath with several examples.
FAQ.md	Adds an FAQ entry linking to the new custom HTTP routes section.
config-reference.md	Adjusts sampling defaults and expands the deprecated settings table.

---

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

howto/Log.md (2)

68-83: ⚠️ Potential issue | 🟡 Minor

Fix missing imports and variable declaration.

The code example has compilability issues:

1. Missing net/http import for http.ResponseWriter and http.Request
2. Missing context import for context.Context
3. Line 73 should use := to declare ctx on first assignment

🔧 Proposed fix

 import (
+    "context"
+    "net/http"
+
     "github.com/go-coldbrew/log"
 )

 func handler(w http.ResponseWriter, r *http.Request) {
-    ctx = r.Context()
+    ctx := r.Context()
     ctx = log.AddToContext(ctx, "request-id", "1234")

🤖 Prompt for AI Agents

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

In `@howto/Log.md` around lines 68 - 83, The code sample fails to compile because
handler uses types from net/http and context but doesn't import them and it
reassigns an undeclared ctx variable; update the imports to include "net/http"
and "context", and in handler declare the context variable on first use (ctx :=
r.Context()) before calling log.AddToContext; keep the rest of the flow
(log.AddToContext calls and helloWorld(ctx) and helloWorld's signature using
context.Context and log.Info) unchanged.

---

147-178: ⚠️ Potential issue | 🟡 Minor

Fix missing imports and variable declaration.

The code example has the same compilability issues as the earlier example:

1. Missing net/http import for http.ResponseWriter and http.Request
2. Missing context import for context.Context
3. Line 160 should use := to declare ctx on first assignment

🔧 Proposed fix

 import (
+    "context"
+    "net/http"
+
     "github.com/go-coldbrew/log"
     "github.com/go-coldbrew/log/loggers"
 )

 func init() {
     // set global log level to info
     // this is typically set by the ColdBrew cookiecutter using the LOG_LEVEL environment variable
     log.SetLevel(loggers.InfoLevel)
 }

 func handler(w http.ResponseWriter, r *http.Request) {
-    ctx = r.Context()
+    ctx := r.Context()
     ctx = log.AddToContext(ctx, "request-id", "1234")

🤖 Prompt for AI Agents

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

In `@howto/Log.md` around lines 147 - 178, The example is missing required imports
and mis-declares ctx: add imports for "net/http" and "context" to the import
block alongside "github.com/go-coldbrew/log" and
"github.com/go-coldbrew/log/loggers", and in handler change the first assignment
to ctx so it is declared (use ctx := r.Context()) before using log.AddToContext
and log.OverrideLogLevel; update references to log.AddToContext,
log.OverrideLogLevel, handler, and helloWorld accordingly.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@howto/Log.md`:
- Line 61: Change the section header "Context aware logs" to the hyphenated form
"Context-aware logs" in howto/Log.md; locate the heading text "Context aware
logs" and update it so the compound adjective is hyphenated when modifying the
noun.

---

Outside diff comments:
In `@howto/Log.md`:
- Around line 68-83: The code sample fails to compile because handler uses types
from net/http and context but doesn't import them and it reassigns an undeclared
ctx variable; update the imports to include "net/http" and "context", and in
handler declare the context variable on first use (ctx := r.Context()) before
calling log.AddToContext; keep the rest of the flow (log.AddToContext calls and
helloWorld(ctx) and helloWorld's signature using context.Context and log.Info)
unchanged.
- Around line 147-178: The example is missing required imports and mis-declares
ctx: add imports for "net/http" and "context" to the import block alongside
"github.com/go-coldbrew/log" and "github.com/go-coldbrew/log/loggers", and in
handler change the first assignment to ctx so it is declared (use ctx :=
r.Context()) before using log.AddToContext and log.OverrideLogLevel; update
references to log.AddToContext, log.OverrideLogLevel, handler, and helloWorld
accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e9082fab-3551-49bd-a653-e2c4be5e72d0

📥 Commits

Reviewing files that changed from the base of the PR and between 5b49a67 and 178ee7d.

📒 Files selected for processing (2)

• config-reference.md
• howto/Log.md

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 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.