Skip to content

fix: compare_windows uses rate-of-change for counter metrics#31

Merged
tallpsmith merged 9 commits into
mainfrom
fix/026-counter-semantics
Mar 9, 2026
Merged

fix: compare_windows uses rate-of-change for counter metrics#31
tallpsmith merged 9 commits into
mainfrom
fix/026-counter-semantics

Conversation

@tallpsmith
Copy link
Copy Markdown
Owner

Summary

Fixes #26.

  • pcp_compare_windows was comparing raw cumulative counter values across windows — counters are monotonic odometers, so comparing means is meaningless (a counter at 1M vs 2M looks like "2x increase" when the rate was identical)
  • Now fetches metric semantics via /series/descs, detects counters, and computes rate-of-change before stats comparison
  • Instant/discrete metrics keep existing raw-value behavior

Changes

  • _compute_rates() in _stats.py — converts timestamped counter samples to per-second rates, clamps to zero on counter wraps, skips zero-dt pairs
  • _fetch_descs() in _fetch.py — fetches metric semantics from /series/descs with graceful fallback to "instant" on error
  • _compare_windows_impl() in comparison.py — builds semantics-by-key map, rate-converts counters, adds "semantics" field to output
  • All existing tests unaffected (they mock /series/descs as [] → defaults to instant)

Test plan

  • _compute_rates: empty, single, monotonic, counter wrap, zero-dt, steady rate
  • _fetch_descs: happy path, empty input, pmproxy error fallback
  • Counter-aware comparison: counter uses rates, instant uses raw, descs failure fallback
  • All 471 tests pass, 89% coverage
  • Pre-push sanity clean
  • E2E not run (no PMPROXY_URL set)

Series API has no rate() — PMAPI has it but is live-only.
@tallpsmith tallpsmith merged commit 83cc573 into main Mar 9, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pcp_scan_changes generates false positives for cumulative counter metrics

1 participant