feat(metrics): add Prometheus text format deserialization by josecelano · Pull Request #1729 · torrust/torrust-tracker

josecelano · 2026-05-04T16:34:06Z

Summary

Adds deserialization from Prometheus exposition text format to MetricCollection, completing the serialization ↔ deserialization symmetry alongside the existing JSON and to_prometheus() paths.

Closes #1582

What changed

`packages/metrics/src/prometheus.rs`

New PrometheusDeserializable trait (mirrors PrometheusSerializable)
New PrometheusDeserializationError enum with fine-grained variants:
- ParseError — syntax error in the input text
- UnsupportedType — known but not yet supported type (Histogram, Summary, …)
- UnknownType — unrecognised metric type
- ValueMismatch — value type does not match the declared metric type
- UnknownValue — PrometheusValue::Unknown sample (no silent zero-returns)
- LabelConversion — label name/value conversion failure
- CollectionError — structural error assembling the MetricCollection

`packages/metrics/src/label/set.rs`

TryFrom<openmetrics_parser::LabelSet<'_>> for LabelSet — replaces ad-hoc inline label conversion

`packages/metrics/src/metric_collection/mod.rs`

Private parse_prometheus_timestamp(t: f64, fallback) -> DurationSinceUnixEpoch — eliminates the duplicated timestamp-parsing block
impl PrometheusDeserializable for MetricCollection — parses Counter and Gauge families; uses openmetrics-parser 0.4.4

`packages/metrics/Cargo.toml`

Added openmetrics-parser = "0.4.4"

Tests

Timestamp helper: 8 edge-case unit tests (negative, NaN, ±Inf, nanosecond-boundary overflow, zero)
TryFrom for LabelSet: 3 unit tests (empty conversion, round-trip, empty-name error)
MetricCollection: round-trip serialize → deserialize, error-path tests for unsupported and malformed input
222 tests pass, 0 failed

Prior art

This is a clean re-implementation based on PR #1611 by @naoNao89, incorporating all maintainer feedback that was pending on that PR. @naoNao89 is preserved as the commit author.

…#1582)

- Add `PrometheusDeserializable` trait to `prometheus.rs` alongside the existing `PrometheusSerializable` trait - Add `PrometheusDeserializationError` with fine-grained variants: ParseError, UnsupportedType, UnknownType, ValueMismatch, UnknownValue, LabelConversion, CollectionError - Implement `TryFrom<openmetrics_parser::LabelSet>` for `LabelSet` - Extract private `parse_prometheus_timestamp` helper to eliminate duplicated timestamp-parsing logic - Implement `PrometheusDeserializable for MetricCollection` using `openmetrics-parser` 0.4.4; no silent zero-returns for unknown or mismatched values - Add unit tests for the timestamp helper, label conversion, and full round-trip serialize → deserialize Closes torrust#1582 Co-authored-by: josecelano <josecelano@users.noreply.github.com>

Copilot

Pull request overview

This PR adds Prometheus exposition text-format deserialization to the packages/metrics crate by introducing a PrometheusDeserializable trait and implementing it for MetricCollection (currently Counter + Gauge families), aiming for symmetry with existing to_prometheus() serialization.

Changes:

Added PrometheusDeserializable + PrometheusDeserializationError to model Prometheus parsing and error reporting.
Implemented Prometheus text parsing for MetricCollection using openmetrics-parser and added unit tests (timestamps, label conversion, round-trip, and error paths).
Introduced TryFrom<openmetrics_parser::LabelSet> for LabelSet and added openmetrics-parser = "0.4.4" dependency.

Reviewed changes

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

Show a summary per file

File	Description
project-words.txt	Adds new spelling whitelist entries used by the implementation/docs.
packages/metrics/src/prometheus.rs	Introduces deserialization trait and structured error type for Prometheus parsing.
packages/metrics/src/metric_collection/mod.rs	Implements `MetricCollection::from_prometheus`, adds timestamp parsing helper + tests.
packages/metrics/src/label/set.rs	Adds `TryFrom` conversion from `openmetrics_parser::LabelSet` + tests.
packages/metrics/Cargo.toml	Adds the `openmetrics-parser` dependency.
docs/issues/1582-add-prometheus-deserialization-metrics/ISSUE.md	Adds design/spec documentation for the feature.
Cargo.lock	Locks new transitive dependencies for `openmetrics-parser`.

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

Copilot

Pull request overview

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

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

codecov · 2026-05-04T17:23:43Z

Codecov Report

❌ Patch coverage is 81.24352% with 181 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.69%. Comparing base (0c9d757) to head (19f98d0).
⚠️ Report is 3 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/metrics/src/metric_collection/serde.rs	56.85%	124 Missing and 5 partials ⚠️
...ckages/metrics/src/metric_collection/prometheus.rs	86.89%	28 Missing and 18 partials ⚠️
packages/metrics/src/prometheus.rs	50.00%	5 Missing ⚠️
packages/metrics/src/metric_collection/error.rs	97.22%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1729      +/-   ##
===========================================
+ Coverage    79.66%   79.69%   +0.02%     
===========================================
  Files          354      359       +5     
  Lines        25597    26411     +814     
  Branches     25597    26411     +814     
===========================================
+ Hits         20392    21047     +655     
- Misses        4969     5117     +148     
- Partials       236      247      +11

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…rde.rs

…ometheus.rs

…baseline

- Tighten nanosecond overflow assertion from approx epsilon 1e-3 to exact equality, catching the 'nanos - 1_000_000_000 → /' mutant. - Add it_should_accept_a_counter_value_that_is_a_whole_number_float to exercise the float-counter match guard (value.is_finite() && >= 0.0 && fract() == 0.0 && < MAX), killing four related guard mutations. - Add it_should_reject_a_float_counter_value_equal_to_first_unrepresentable_u64 to verify the strict-less-than bound (< not <=) for 2^64. - Exclude mutants.out / mutants.out.old from cspell to prevent 'xyzzy' false-positive failures from cargo-mutants artefacts. Result: 35 mutants tested — 24 caught, 11 unviable, 0 survived.

…ple.rs

…heus.rs

…ue trait

…eline Extract family-iteration logic into exposition_to_metric_collection helper function and refactor from_prometheus to coordinate three distinct stages: - Stage 1 (Normalize): ensure_trailing_newline - Stage 2 (Parse): openmetrics_parser::prometheus::parse_prometheus - Stage 3 (Convert): exposition_to_metric_collection The conversion stage encapsulates the dispatch logic for Counter/Gauge types, improving testability and extensibility. Future metric type support only needs to modify the conversion stage. All 253 tests pass. No behavior changes.

josecelano · 2026-05-05T09:53:15Z

ACK 19f98d0

josecelano and others added 2 commits May 4, 2026 16:57

docs(metrics): add issue spec for Prometheus deserialization (torrust…

014f517

…#1582)

josecelano temporarily deployed to coverage May 4, 2026 16:34 — with GitHub Actions Inactive

josecelano requested a review from Copilot May 4, 2026 16:35

Copilot started reviewing on behalf of josecelano May 4, 2026 16:36 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

refactor(metrics): extract Prometheus deserialization helpers

94c53b9

josecelano temporarily deployed to coverage May 4, 2026 16:48 — with GitHub Actions Inactive

josecelano requested a review from Copilot May 4, 2026 16:48

josecelano self-assigned this May 4, 2026

Copilot AI reviewed May 4, 2026

View reviewed changes

fix(metrics): address Copilot PR review feedback

9b3277e

josecelano temporarily deployed to coverage May 4, 2026 17:02 — with GitHub Actions Inactive

docs(metrics): add refactor plan for metric_collection module split

c3c42a1

josecelano added 4 commits May 4, 2026 18:24

refactor(metrics): extract Error into metric_collection/error.rs

15cdb7e

refactor(metrics): extract MetricKindCollection into kind_collection.rs

9ca54dd

refactor(metrics): extract JSON serde impls into metric_collection/se…

f85911e

…rde.rs

refactor(metrics): extract Prometheus impls into metric_collection/pr…

7ba33c2

…ometheus.rs

josecelano temporarily deployed to coverage May 4, 2026 17:59 — with GitHub Actions Inactive

josecelano added 2 commits May 4, 2026 20:31

docs(metrics): add unit test coverage improvement plan with llvm-cov …

8b38a65

…baseline

test(metrics): add tests to close llvm-cov coverage gaps

b8a131d

josecelano temporarily deployed to coverage May 4, 2026 19:56 — with GitHub Actions Inactive

josecelano added 6 commits May 4, 2026 21:04

docs(metrics): add mutation testing plan for the metrics package

92965d3

test(metrics): kill surviving mutants in metric_collection/mod.rs

333e124

test(metrics): kill surviving mutants in counter.rs and gauge.rs

4644ec8

test(metrics): kill surviving mutants in sample_collection.rs and sam…

2bb5610

…ple.rs

test(metrics): kill surviving mutants in label/set.rs

0140113

josecelano mentioned this pull request May 5, 2026

metrics: parse Prometheus text exposition with best practices #1611

Closed

test(metrics): kill surviving mutants in remaining files

886761f

josecelano temporarily deployed to coverage May 5, 2026 07:16 — with GitHub Actions Inactive

josecelano added 11 commits May 5, 2026 08:45

docs(metrics): add refactoring proposals for metric_collection/promet…

ffa6c27

…heus.rs

refactor(metrics): extract parse_family_samples via FromPrometheusVal…

bbedebd

…ue trait

refactor(metrics): extract is_whole_u64_representable predicate

3e91f69

refactor(metrics): add MetricDescription From conversions

04b0d74

refactor(metrics): extract description_from_help helper

9de6444

refactor(metrics): use Cow for input normalization in from_prometheus

43b4c57

refactor(metrics): parse_prometheus_timestamp returns Option

d1f219b

refactor(metrics): use From conversions for collection errors

0ccddc7

docs(metrics): add follow-up refactor proposals 9-12

e2fa3fc

refactor(metrics): implement proposals 9-12 in prometheus pipeline

19f98d0

josecelano marked this pull request as ready for review May 5, 2026 09:52

josecelano temporarily deployed to coverage May 5, 2026 09:53 — with GitHub Actions Inactive

josecelano merged commit 0e71e40 into torrust:develop May 5, 2026
26 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(metrics): add Prometheus text format deserialization#1729

feat(metrics): add Prometheus text format deserialization#1729
josecelano merged 29 commits into
torrust:developfrom
josecelano:1582-add-prometheus-deserialization-metrics

josecelano commented May 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented May 4, 2026 •

edited

Loading

Uh oh!

josecelano commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

josecelano commented May 4, 2026

Summary

What changed

packages/metrics/src/prometheus.rs

packages/metrics/src/label/set.rs

packages/metrics/src/metric_collection/mod.rs

packages/metrics/Cargo.toml

Tests

Prior art

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

josecelano commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`packages/metrics/src/prometheus.rs`

`packages/metrics/src/label/set.rs`

`packages/metrics/src/metric_collection/mod.rs`

`packages/metrics/Cargo.toml`

codecov Bot commented May 4, 2026 •

edited

Loading