Add reusable latency histogram helpers

[goldyfruit]

Summary

Add reusable, dependency-free latency histogram primitives to ovos_utils.metrics:

• monotonic timing with pause/resume support;
• thread-safe, fixed cumulative buckets;
• idempotent completion and exception-safe context management;
• a synchronous decorator that preserves wrapped metadata; and
• detached JSON-friendly snapshots for plugin-owned exporters.

Why

OVOS Core, Workshop, and intent pipeline packages need the same low-level timing and histogram storage without importing one another or creating a dependency cycle. This keeps metric ownership in each instrumented package while giving their process-local metrics providers one shared implementation.

The helper intentionally has no Prometheus server, labels, request identifiers, or runtime policy. Export remains the host runtime's responsibility through the existing metrics-provider entry point.

This is the prerequisite proposed in the architecture discussion on OpenVoiceOS/ovos-workshop#509. Consumer PRs can switch to this API after an ovos-utils alpha containing it is published, with explicit minimum-version bumps.

Validation

• ruff check ovos_utils/metrics.py test/unittests/test_metrics.py
• PYTHONPATH=. pytest -q test/unittests/test_metrics.py — 19 passed
• git diff --check

Summary by CodeRabbit

• New Features

  • Added latency tracking with configurable measurement buckets.
  • Added context-manager timing for measuring operations, including pause and resume support.
  • Added function timing support that preserves existing function metadata.
  • Added JSON-friendly latency snapshots with cumulative counts and timing data.

• Bug Fixes

  • Ensured invalid durations and bucket configurations are rejected.
  • Ensured each measurement is recorded exactly once, including when operations exit with errors.

[coderabbitai]

Warning

Review limit reached

@goldyfruit, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 51 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5aa7cb7f-d4c4-4d7c-8d81-cefaf2518322

📥 Commits

Reviewing files that changed from the base of the PR and between b9465a9 and f844514.

📒 Files selected for processing (2)

• ovos_utils/metrics.py
• test/unittests/test_metrics.py

📝 Walkthrough

Walkthrough

Added LatencyHistogram and LatencyMeasurement to collect validated cumulative latency data. The implementation supports thread safety, pause/resume timing, context managers, decorators, detached snapshots, and unit-test coverage.

Changes

Latency metrics

Layer / File(s)	Summary
Histogram configuration and aggregation ovos_utils/metrics.py	Adds default and configurable latency buckets. Validates bucket and duration inputs. Updates cumulative counts and totals under a thread lock.
Measurement APIs and validation ovos_utils/metrics.py, test/unittests/test_metrics.py	Adds pausable measurements, context-manager recording, synchronous decoration, JSON-friendly snapshots, and tests for normal and exceptional execution. Removes an unused stopwatch-test assignment.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 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 and concisely describes the main change: adding reusable latency histogram helpers.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ovos_utils/metrics.py`:
- Around line 120-123: Update the bucket key construction in the metrics method
containing the buckets comprehension to use a round-trip-safe bound
representation such as .17g instead of :g, ensuring distinct close bounds retain
separate dictionary entries. Add a test using bounds like 1.0000001 and
1.0000002 to verify both keys and cumulative counts are preserved.
- Around line 53-59: Update the measurement class’s finish method to synchronize
access to _running, _finished, and _elapsed_ms with a measurement-level lock. In
finish, acquire the lock, return for an already-finished measurement,
pause/update the elapsed state as needed, and set _finished before calling
_histogram.observe_ms so concurrent calls record exactly once.

🪄 Autofix

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 Plus

Run ID: 43dd5b75-a757-449d-bd79-bfb255f7c8ce

📥 Commits

Reviewing files that changed from the base of the PR and between e8f1232 and b9465a9.

📒 Files selected for processing (2)

• ovos_utils/metrics.py
• test/unittests/test_metrics.py