feat: add channel frequency labels to metrics (#228)

Co-authored-by: Dennis Braun <itsDNNS@users.noreply.github.com>

Author: itsDNNS

app/prometheus.py

@@ -9,6 +9,46 @@
 _HEALTH_MAP = {"good": 0, "tolerated": 1, "marginal": 2, "critical": 3}
 
 
+def _frequency_label(value):
+    """Normalize channel frequency for Prometheus labels.
+
+    Returns a string in MHz where possible, without the trailing unit.
+    """
+    if value is None:
+        return None
+
+    text = str(value).strip()
+    if not text:
+        return None
+
+    lowered = text.lower()
+    if lowered.endswith("mhz"):
+        text = text[:-3].strip()
+        return text or None
+
+    try:
+        numeric = float(text)
+    except ValueError:
+        return text
+
+    if abs(numeric) >= 1_000_000:
+        numeric /= 1_000_000
+
+    if numeric.is_integer():
+        return str(int(numeric))
+
+    return f"{numeric:.3f}".rstrip("0").rstrip(".")
+
+
+def _channel_labels(channel):
+    """Build Prometheus labels for a DOCSIS channel metric."""
+    labels = {"channel_id": str(channel["channel_id"])}
+    frequency = _frequency_label(channel.get("frequency"))
+    if frequency is not None:
+        labels["frequency"] = frequency
+    return labels
+
+
 def _metric(lines, help_text, metric_type, name, value, labels=None):
     """Append HELP, TYPE, and a single value line to lines list."""
     lines.append(f"# HELP {name} {help_text}")
@@ -102,7 +142,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
             ch_id = ch["channel_id"]
             if ch.get("power") is not None:
                 _metric_value(lines, "docsight_downstream_power_dbmv", ch["power"],
-                              {"channel_id": str(ch_id)})
+                              _channel_labels(ch))
 
         _metric_family_open(
             lines,
@@ -113,7 +153,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
         for ch in ds_channels:
             if ch.get("snr") is not None:
                 _metric_value(lines, "docsight_downstream_snr_db", ch["snr"],
-                              {"channel_id": str(ch["channel_id"])})
+                              _channel_labels(ch))
 
         _metric_family_open(
             lines,
@@ -124,7 +164,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
         for ch in ds_channels:
             _metric_value(lines, "docsight_downstream_corrected_errors_total",
                           ch.get("correctable_errors", 0),
-                          {"channel_id": str(ch["channel_id"])})
+                          _channel_labels(ch))
 
         _metric_family_open(
             lines,
@@ -135,7 +175,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
         for ch in ds_channels:
             _metric_value(lines, "docsight_downstream_uncorrected_errors_total",
                           ch.get("uncorrectable_errors", 0),
-                          {"channel_id": str(ch["channel_id"])})
+                          _channel_labels(ch))
 
         _metric_family_open(
             lines,
@@ -147,7 +187,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
             qam = _parse_qam_order(ch.get("modulation", ""))
             if qam is not None:
                 _metric_value(lines, "docsight_downstream_modulation", qam,
-                              {"channel_id": str(ch["channel_id"])})
+                              _channel_labels(ch))
 
     # --- Upstream channel metrics ---
     us_channels = analysis.get("us_channels", []) if analysis else []
@@ -162,7 +202,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
         for ch in us_channels:
             if ch.get("power") is not None:
                 _metric_value(lines, "docsight_upstream_power_dbmv", ch["power"],
-                              {"channel_id": str(ch["channel_id"])})
+                              _channel_labels(ch))
 
         _metric_family_open(
             lines,
@@ -174,7 +214,7 @@ def format_metrics(analysis, device_info, connection_info, last_poll_timestamp):
             qam = _parse_qam_order(ch.get("modulation", ""))
             if qam is not None:
                 _metric_value(lines, "docsight_upstream_modulation", qam,
-                              {"channel_id": str(ch["channel_id"])})
+                              _channel_labels(ch))
 
     # --- Device info ---
     if device_info is not None:

tests/test_prometheus.py

@@ -106,23 +106,23 @@ def _has_metric_approx(output, prefix):
 class TestDownstreamChannelMetrics:
     def test_ds_power_dbmv(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="1"} 3.0')
+        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="1",frequency="474"} 3.0')
 
     def test_ds_snr_db(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_snr_db{channel_id="1"} 35.0')
+        assert _has_metric(out, 'docsight_downstream_snr_db{channel_id="1",frequency="474"} 35.0')
 
     def test_ds_corrected_errors_total(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_corrected_errors_total{channel_id="1"} 100')
+        assert _has_metric(out, 'docsight_downstream_corrected_errors_total{channel_id="1",frequency="474"} 100')
 
     def test_ds_uncorrected_errors_total(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_uncorrected_errors_total{channel_id="1"} 5')
+        assert _has_metric(out, 'docsight_downstream_uncorrected_errors_total{channel_id="1",frequency="474"} 5')
 
     def test_ds_modulation_256qam(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_modulation{channel_id="1"} 256')
+        assert _has_metric(out, 'docsight_downstream_modulation{channel_id="1",frequency="474"} 256')
 
     def test_ds_snr_none_omits_line(self):
         analysis = {
@@ -146,7 +146,7 @@ def test_ds_snr_none_omits_line(self):
             "us_channels": [],
         }
         out = format_metrics(analysis, None, None, 0.0)
-        assert not _has_metric_approx(out, 'docsight_downstream_snr_db{channel_id="5"}')
+        assert not _has_metric_approx(out, 'docsight_downstream_snr_db{channel_id="5",frequency="474"}')
 
     def test_ds_modulation_ofdm_omits_line(self):
         """OFDM is not parseable as QAM order, so modulation line must be omitted."""
@@ -171,16 +171,16 @@ def test_ds_modulation_ofdm_omits_line(self):
             "us_channels": [],
         }
         out = format_metrics(analysis, None, None, 0.0)
-        assert not _has_metric_approx(out, 'docsight_downstream_modulation{channel_id="7"}')
+        assert not _has_metric_approx(out, 'docsight_downstream_modulation{channel_id="7",frequency="474"}')
 
     def test_multiple_ds_channels_separate_lines(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="1"} 3.0')
-        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="2"} -1.5')
+        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="1",frequency="474"} 3.0')
+        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="2",frequency="482"} -1.5')
 
     def test_ds_power_negative_value(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="2"} -1.5')
+        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="2",frequency="482"} -1.5')
 
     def test_ds_has_help_comment(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
@@ -200,11 +200,11 @@ def test_ds_has_type_comment(self):
 class TestUpstreamChannelMetrics:
     def test_us_power_dbmv(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_upstream_power_dbmv{channel_id="1"} 42.0')
+        assert _has_metric(out, 'docsight_upstream_power_dbmv{channel_id="1",frequency="30"} 42.0')
 
     def test_us_modulation_64qam(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)
-        assert _has_metric(out, 'docsight_upstream_modulation{channel_id="1"} 64')
+        assert _has_metric(out, 'docsight_upstream_modulation{channel_id="1",frequency="30"} 64')
 
     def test_us_power_none_omits_line(self):
         analysis = {
@@ -225,7 +225,7 @@ def test_us_power_none_omits_line(self):
             }],
         }
         out = format_metrics(analysis, None, None, 0.0)
-        assert not _has_metric_approx(out, 'docsight_upstream_power_dbmv{channel_id="3"}')
+        assert not _has_metric_approx(out, 'docsight_upstream_power_dbmv{channel_id="3",frequency="30"}')
 
     def test_multiple_us_channels_separate_lines(self):
         analysis = {
@@ -257,8 +257,41 @@ def test_multiple_us_channels_separate_lines(self):
             ],
         }
         out = format_metrics(analysis, None, None, 0.0)
-        assert _has_metric(out, 'docsight_upstream_power_dbmv{channel_id="1"} 42.0')
-        assert _has_metric(out, 'docsight_upstream_power_dbmv{channel_id="2"} 45.0')
+        assert _has_metric(out, 'docsight_upstream_power_dbmv{channel_id="1",frequency="30"} 42.0')
+        assert _has_metric(out, 'docsight_upstream_power_dbmv{channel_id="2",frequency="38"} 45.0')
+
+    def test_frequency_label_normalizes_mhz_values(self):
+        analysis = {
+            "summary": {
+                "ds_total": 1, "us_total": 1,
+                "health": "good", "health_issues": [],
+                "ds_correctable_errors": 0, "ds_uncorrectable_errors": 0,
+            },
+            "ds_channels": [{
+                "channel_id": 9,
+                "frequency": "114.0 MHz",
+                "power": 2.5,
+                "modulation": "256QAM",
+                "snr": 36.0,
+                "correctable_errors": 0,
+                "uncorrectable_errors": 0,
+                "docsis_version": "3.0",
+                "health": "good",
+                "health_detail": "",
+            }],
+            "us_channels": [{
+                "channel_id": 2,
+                "frequency": "44 MHz",
+                "power": 43.0,
+                "modulation": "64QAM",
+                "docsis_version": "3.0",
+                "health": "good",
+                "health_detail": "",
+            }],
+        }
+        out = format_metrics(analysis, None, None, 0.0)
+        assert _has_metric(out, 'docsight_downstream_power_dbmv{channel_id="9",frequency="114.0"} 2.5')
+        assert _has_metric(out, 'docsight_upstream_modulation{channel_id="2",frequency="44"} 64')
 
     def test_us_has_help_comment(self):
         out = format_metrics(ANALYSIS_FULL, None, None, 0.0)