docs: retry log-level parity and observability counters (whatsapp-rust#887)

[jlucaso1]

Tracks whatsapp-rust#887.

Summary

• advanced/metrics.mdx — adds 4 new counters to the metric catalogue:

  • wa_high_retry_total (label: reason) — mirrors WA Web's MessageHighRetryCount WAM event
  • wa_retry_unknown_device_total (label: sender_type = primary/companion) — mirrors MdRetryFromUnknownDevice WAM event
  • wa_retry_refused_total — retries refused at the MAX_RETRY cap
  • wa_base_key_collision_total — base-key collisions that forced a fresh session

• advanced/observability.mdx — notes the new count field on wa.retry.handle_receipt (retry depth, aggregable per sender even when the cap refuses early)

• changelog/2026-06-17-retry-warn-levels-and-telemetry.mdx — new changelog entry covering the counters, span field, and the two WARN→debug/info log-level corrections that match WA Web's own WALogger.LOG level

• docs.json — registers the new changelog page at the top of the list

---

Generated by Claude Code

---

Summary by cubic

Adds four retry observability counters, documents the count field on wa.retry.handle_receipt, and adds a changelog entry that notes WARN→debug/info log-level parity with WA Web.

• New Features
  • Metrics: wa_high_retry_total (reason), wa_retry_unknown_device_total (sender_type), wa_retry_refused_total, wa_base_key_collision_total.
  • Tracing: wa.retry.handle_receipt now records count (retry depth).
  • Changelog: new 2026-06-17 entry covering the counters, span field, and log-level parity; registered in docs.json.

^{Written for commit dc17912. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Added four new low-cardinality metrics counters for monitoring retry flows with safety-focused labels
  • Enhanced tracing spans with retry depth tracking for better observability and aggregation
  • Adjusted logging levels in retry paths to improve log clarity
  • Updated observability documentation; retry logic behavior remains unchanged

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8fee6213-c893-4804-ba9a-a395e0b118d8

📥 Commits

Reviewing files that changed from the base of the PR and between 9232593 and dc17912.

📒 Files selected for processing (4)

• advanced/metrics.mdx
• advanced/observability.mdx
• changelog/2026-06-17-retry-warn-levels-and-telemetry.mdx
• docs.json

---

📝 Walkthrough

Walkthrough

Adds four new wa_* retry-related metric counters to the metrics catalogue, expands the wa.retry.* observability span taxonomy entry to include a count field on wa.retry.handle_receipt, and introduces a new changelog page documenting these additions along with two retry-path log-level corrections. The changelog page is registered in the Mintlify navigation.

Changes

Retry Observability Documentation

Layer / File(s)	Summary
Metric catalogue and span taxonomy updates advanced/metrics.mdx, advanced/observability.mdx	Adds wa_high_retry_total, wa_retry_unknown_device_total, wa_retry_refused_total, and wa_base_key_collision_total counters with their label sets to the Counters table; expands the wa.retry.* span entry to specify retry receipt handling and documents the new count field on wa.retry.handle_receipt.
Changelog entry and nav registration changelog/2026-06-17-retry-warn-levels-and-telemetry.mdx, docs.json	Creates the new changelog page covering the four metric counters, the count span field, two log-level corrections (WARN→debug and WARN→info) with message_id now included in affected log lines, and an explicit no-behavior-change statement; registers the page in the Mintlify nav.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• oxidezap/whatsapp-rust-docs#287: Documents the handle_retry_receipt behavior change for unknown-device resync on the same wa.retry.handle_receipt span path that this PR now adds the count field and metric counters to.

Poem

🐇 Hop, hop, through the retry storm I go,
Counting receipts with a count field in tow,
Four shiny counters now glitter and gleam,
WARN logs turned debug — a quieter dream,
No behavior changed, just the telemetry's glow! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding documentation for retry log-level parity and observability counters related to whatsapp-rust#887. It is specific and directly reflects the PR's primary objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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 claude/eager-cerf-dv72rl

---

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

[cubic-dev-ai]

No issues found across 4 files

<sub>Tip: cubic could auto-approve low-risk PRs like this, if it thinks it's safe to merge. Learn more

Re-trigger cubic</sub>