feat(testing): add telemetry recording helpers

[thomhurst]

Closes #98

Adds an opt-in TelemetryRecorder to Kevlar.Testing for deterministic, concurrency-safe metric and callback capture. Records use immutable snapshots, copy tags immediately, preserve callback outcomes, and never retain pooled KevlarContext instances.

Validation:

• dotnet build Kevlar.slnx -c Release
• Kevlar.Tests: 644 passed
• Kevlar.Testing.Tests: 13 passed
• Kevlar.IntegrationTests: 16 passed
• Kevlar.Analyzers.Tests: 38 passed
• Kevlar.Chaos.Tests: 23 passed
• Kevlar.AllocationTests: 2 passed
• dotnet pack + Verify-Packages.ps1 passed
• Verify-DocSnippets.ps1 reaches the new excluded TUnit snippet; current main fails unrelated pre-existing snippets for APIs not yet present

Summary by CodeRabbit

• New Features

  • Added a telemetry recorder for capturing retry, timeout, hedge, fallback, and circuit-state events.
  • Added metric snapshots with instrument names, values, tags, and ordering information.
  • Added asynchronous helpers for waiting on callback or metric counts, including cancellation support.
  • Added callback categories and detailed event records for test assertions.

• Documentation

  • Added usage guidance and an executable example for telemetry recording in tests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b770b925-0c3c-4701-8fa8-3c0321e12276

📥 Commits

Reviewing files that changed from the base of the PR and between 490cbe9 and 123736a.

📒 Files selected for processing (7)

• docs/docs/testing.md
• src/Kevlar.Testing/CallbackKind.cs
• src/Kevlar.Testing/CallbackRecord.cs
• src/Kevlar.Testing/MetricRecord.cs
• src/Kevlar.Testing/PublicAPI.Unshipped.txt
• src/Kevlar.Testing/TelemetryRecorder.cs
• tests/Kevlar.Testing.Tests/TelemetryRecorderTests.cs

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Added TelemetryRecorder with immutable callback and metric snapshots, optional metric capture, asynchronous count waiters, disposal handling, public API declarations, tests, and usage documentation.

Changes

Telemetry recording

Layer / File(s)	Summary
Telemetry contracts src/Kevlar.Testing/CallbackKind.cs, src/Kevlar.Testing/CallbackRecord.cs, src/Kevlar.Testing/MetricRecord.cs, src/Kevlar.Testing/PublicAPI.Unshipped.txt	Added callback categories and immutable public snapshot types for callback and metric data.
Telemetry capture src/Kevlar.Testing/TelemetryRecorder.cs	Added synchronized callback and metric capture, sequence assignment, copied tags, stable snapshots, and optional MeterListener integration.
Waiters and disposal src/Kevlar.Testing/TelemetryRecorder.cs	Added asynchronous count waits with cancellation, disposal checks, signaling, and listener cleanup.
Validation and usage tests/Kevlar.Testing.Tests/TelemetryRecorderTests.cs, docs/docs/testing.md	Added coverage for callback ordering, metric families, concurrency, disposal, cancellation, and documented recorder usage.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 12373

This opt-in testing feature adds telemetry recording helpers with documented deterministic and concurrency-safe behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant ShieldPipeline as Shield pipeline
  participant TelemetryRecorder
  participant MeterListener
  participant TestWaiter as Test waiter
  ShieldPipeline->>TelemetryRecorder: Record callback event
  MeterListener->>TelemetryRecorder: Deliver metric measurement
  TelemetryRecorder->>TelemetryRecorder: Store sequenced snapshots
  TestWaiter->>TelemetryRecorder: WaitForCallbackCountAsync or WaitForMetricCountAsync
  TelemetryRecorder-->>TestWaiter: Complete when count is reached

Loading

Poem

I’m a rabbit with records in a neat little row,
Callbacks and metrics now clearly show.
Waiters wake softly when counts are complete,
Disposal shuts listeners down nice and discreet.
Hop, test, and measure—everything’s fleet!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.74% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 27 functions across 5 files. (2 skipped: 2 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the new telemetry recording helpers in the testing package.
Linked Issues check	✅ Passed	The implementation adds disposable, concurrency-safe telemetry capture, waiters, tests, API baselines, and documentation for issue #98.
Out of Scope Changes check	✅ Passed	The changes are limited to telemetry APIs, supporting documentation, public API baselines, and focused tests required by issue #98.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-98-telemetry-recording

---

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