printer_supply: use supply toner color metric

The following improvements were made to the plugin:

  - drop generic "pages" metric as it's not relevant to the printer
    supply level data coming from the SNMP address.
  - use a supply toner metric based on the color code provided by the
    data extracted from the service description.
  - improve the summary in the check levels metric and only show
    unit-based summary when the unit is not a percentage.

Note: this change will drop the legacy "pages" metric and the generic
"supply_toner" metric. It's not possible to migrate "supply_toner" to
the new `supply_toner_{color}` metric. Since we'd also need the ability
to translate the metric based on color which isn't possible.

CMK-22267

Change-Id: I4cfc6371471e8765e952b987886faa07564c366a

Author: logan-connolly

.werks/17835.md

@@ -0,0 +1,24 @@
+[//]: # (werk v2)
+# Printer Supply: switch to color-based toner metrics
+
+key        | value
+---------- | ---
+date       | 2025-03-24T14:58:01+00:00
+version    | 2.4.0b3
+class      | feature
+edition    | cre
+component  | checks
+level      | 1
+compatible | yes
+
+Starting in 2.4, the toner color was not shown in `supply_toner` metric. This is now supported by
+migrating these metrics to `supply_toner_{black|cyan|magenta|yellow}` if a color is found.
+Otherwise, the `supply_toner_other` metric will be used.
+
+**Note:** this means that history of the previous `supply_toner` metric will not be connected to the
+new color metric history. However, you will still see its history in the respective service's
+detailed view.
+
+In addition, this change drops the `pages` metric as it's not related to the data derived from the
+SNMP data. The readability of labels for the existing results and metrics were also improved,
+removing any redundant information.

cmk/plugins/collection/agent_based/printer_supply.py

@@ -241,36 +241,33 @@ def check_printer_supply(item: str, params: CheckParams, section: Section) -> Ch
         return
 
     color_info = _get_supply_color_info(item, supply.color)
-
-    warn, crit = params["levels"]
+    metric_name = f"supply_toner_{supply.color or 'other'}"
 
     if supply.has_partial_data:  # no percentage possible
-        yield from _get_partial_data_results(supply, params, color_info)
+        yield from _get_partial_data_results(supply, params, color_info, metric_name)
         return
 
     yield from check_levels_v1(
         _get_fill_level_percentage(supply, params["upturn_toner"]),
-        levels_lower=(warn, crit),
-        label=f"{color_info}Remaining",
+        metric_name=metric_name,
+        levels_lower=params["levels"],
+        label="Supply level remaining",
         render_func=render.percent,
     )
 
-    summary = f"Supply: {supply.level} of max. {supply.max_capacity}{supply.unit}"
-    yield Result(state=State.OK, summary=summary)
-    yield Metric(
-        "pages",
-        supply.level,
-        levels=(0.01 * warn * supply.max_capacity, 0.01 * crit * supply.max_capacity),
-        boundaries=(0, supply.max_capacity),
-    )
+    if supply.unit not in {"", "%"}:
+        yield Result(
+            state=State.OK,
+            summary=f"Supply: {supply.level} of max. {supply.max_capacity}{supply.unit}",
+        )
 
 
 def _get_supply_color_info(item: str, color: Color | None) -> str:
     return f"[{color}] " if color and color not in item.lower() else ""
 
 
 def _get_partial_data_results(
-    supply: PrinterSupply, params: CheckParams, color_info: str
+    supply: PrinterSupply, params: CheckParams, color_info: str, metric_name: str
 ) -> CheckResult:
     if supply.level_unrestricted or supply.capacity_unrestricted:
         summary = "%sThere are no restrictions on this supply" % color_info
@@ -293,8 +290,8 @@ def _get_partial_data_results(
         yield Result(state=State.UNKNOWN, summary="%s Unknown level" % color_info)
 
     elif supply.capacity_unknown:
-        yield Result(state=State.OK, summary="%sLevel: %d" % (color_info, supply.level))
-        yield Metric("pages", supply.level)
+        yield Result(state=State.OK, summary="Supply: %d%s" % (supply.level, supply.unit))
+        yield Metric(metric_name, supply.level)
 
 
 def _get_fill_level_percentage(supply: PrinterSupply, upturn_toner: bool) -> float:

tests/unit/cmk/plugins/collection/agent_based/test_printer_supply.py

@@ -143,7 +143,10 @@ def test_inventory_printer_supply(
                     ["Magenta Ink Cartridge", "15", "-2", "5", "3", "1"],
                 ],
             ],
-            [Result(state=State.OK, summary="Level: 5"), Metric("pages", 5)],
+            [
+                Result(state=State.OK, summary="Supply: 5 tenths of milliliters"),
+                Metric("supply_toner_magenta", 5),
+            ],
         ),
         (
             "Magenta Ink Cartridge",
@@ -156,10 +159,11 @@ def test_inventory_printer_supply(
             ],
             [
                 Result(
-                    state=State.CRIT, summary="Remaining: 5.00% (warn/crit below 20.00%/10.00%)"
+                    state=State.CRIT,
+                    summary="Supply level remaining: 5.00% (warn/crit below 20.00%/10.00%)",
                 ),
+                Metric("supply_toner_magenta", 5.0),
                 Result(state=State.OK, summary="Supply: 5 of max. 100 tenths of milliliters"),
-                Metric("pages", 5, levels=(20.0, 10.0), boundaries=(0, 100)),
             ],
         ),
         (
@@ -173,10 +177,11 @@ def test_inventory_printer_supply(
             ],
             [
                 Result(
-                    state=State.WARN, summary="Remaining: 15.00% (warn/crit below 20.00%/10.00%)"
+                    state=State.WARN,
+                    summary="Supply level remaining: 15.00% (warn/crit below 20.00%/10.00%)",
                 ),
+                Metric("supply_toner_magenta", 15.0),
                 Result(state=State.OK, summary="Supply: 15 of max. 100 tenths of milliliters"),
-                Metric("pages", 15, levels=(20.0, 10.0), boundaries=(0, 100)),
             ],
         ),
         (
@@ -189,9 +194,9 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_magenta", 25.0),
                 Result(state=State.OK, summary="Supply: 25 of max. 100 tenths of milliliters"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
             ],
         ),
         (
@@ -204,9 +209,9 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_magenta", 25.0),
                 Result(state=State.OK, summary="Supply: 25 of max. 100 micrometers"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
             ],
         ),
         (
@@ -219,9 +224,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_magenta", 25.0),
             ],
         ),
         (
@@ -234,9 +238,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_magenta", 25.0),
             ],
         ),
         (
@@ -271,9 +274,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_magenta", 25.0),
             ],
         ),
         (
@@ -287,9 +289,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_other", 25.0),
             ],
         ),
         (
@@ -303,9 +304,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 25.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 25.00%"),
+                Metric("supply_toner_magenta", 25.0),
             ],
         ),
         (
@@ -318,9 +318,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 75.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 75.00%"),
+                Metric("supply_toner_magenta", 75.0),
             ],
         ),
         (
@@ -333,9 +332,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="Remaining: 75.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 75.00%"),
+                Metric("supply_toner_magenta", 75.0),
             ],
         ),
         (
@@ -348,9 +346,8 @@ def test_inventory_printer_supply(
                 ],
             ],
             [
-                Result(state=State.OK, summary="[magenta] Remaining: 75.00%"),
-                Result(state=State.OK, summary="Supply: 25 of max. 100%"),
-                Metric("pages", 25, levels=(20.0, 10.0), boundaries=(0, 100)),
+                Result(state=State.OK, summary="Supply level remaining: 75.00%"),
+                Metric("supply_toner_magenta", 75.0),
             ],
         ),
     ],
@@ -364,3 +361,39 @@ def test_check_printer_supply(
     section = parse_printer_supply(info)
     result = check_printer_supply(item, params, section)
     assert list(result) == expected_result
+
+
+def _get_section_with_color_in_description(item: str) -> Section:
+    max_capacity, supply_level, container_class = "0", "25", str(SupplyClass.CONTAINER)
+    info = [[["1.1", ""]], [[item, "", max_capacity, supply_level, container_class, ""]]]
+    return parse_printer_supply(info)
+
+
+@pytest.mark.parametrize("item", ["Black", "Schwarz", "Noir", "Negra"])
+def test_check_printer_supply_black_translations(item: str) -> None:
+    section = _get_section_with_color_in_description(item)
+
+    _, value = list(check_printer_supply(item, DEFAULT_PARAMETERS, section))
+    expected = Metric("supply_toner_black", 25.0)
+
+    assert value == expected
+
+
+@pytest.mark.parametrize("item", ["Cyan", "Zyan", "Cian"])
+def test_check_printer_supply_cyan_translations(item: str) -> None:
+    section = _get_section_with_color_in_description(item)
+
+    _, value = list(check_printer_supply(item, DEFAULT_PARAMETERS, section))
+    expected = Metric("supply_toner_cyan", 25.0)
+
+    assert value == expected
+
+
+@pytest.mark.parametrize("item", ["Yellow", "Gelb", "Jaune", "Amarilla"])
+def test_check_printer_supply_yellow_translations(item: str) -> None:
+    section = _get_section_with_color_in_description(item)
+
+    _, value = list(check_printer_supply(item, DEFAULT_PARAMETERS, section))
+    expected = Metric("supply_toner_yellow", 25.0)
+
+    assert value == expected