From 9f6ffa8a25322455dfcbe3fc5dd5c3d33f05955e Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 22:11:19 +0100 Subject: [PATCH] feat(snmp): let a health profile mark a value unknown SnmpValueSpec gains `unknown`. A driver whose device's agent answers a value wrongly says so in its SNMP_HEALTH_PROFILE, and the application reports no value for it instead of the standard reading or a default. OpenBSD's net-snmp reports the CPU as never idle, so a reading of ssCpuIdle shows every OpenBSD host at 100 % (NAPALM/napalm-bsd#7). --- CHANGELOG.md | 4 ++++ README.md | 3 +++ napalm_device_types/models.py | 9 +++++++-- tests/test_snmp_health_profile.py | 12 +++++++++++- 4 files changed, 25 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad65a9..a946659 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ recorded here; their history is the git log. 3.12 venv no longer has. ### Added +- `SnmpValueSpec.unknown`: a driver whose device's agent answers a value wrongly says + so in its `SNMP_HEALTH_PROFILE` (`"cpu": {"unknown": True}`), and the application + reports no value for it -- not the standard reading, not 0. OpenBSD's net-snmp, + which reports the CPU as never idle, is the case (NAPALM/napalm-bsd#7). - `HypervisorDriver.get_clusters()` and its shapes `ClusterDict`, `ClusterNodeDict`, `ClusterStorageDict`, `ClusterNetworkDict`: every cluster the connection can see, with its nodes (offline ones included, `local` on the node the connection is), diff --git a/README.md b/README.md index 8a4c22e..8d4f788 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,9 @@ class MySwitchDriver(SwitchDriver): A value is `oids` (the first that answers wins) or a `table` folded by `first`, `average` or `max`, with an optional `pattern` for an agent that answers with text. What the profile does not name, the application reads from the standard UCD-MIB and IF-MIB. +A value the agent gets wrong is `{"unknown": True}`: the application then reports no value +for it, rather than the standard reading or a default (OpenBSD's net-snmp reports its CPU +as never idle). `KernelFactsMixin` (`get_kernel_facts`) is the exception that is mixed in by a driver rather than by a role base: what a Linux kernel has built and loaded is read the same way diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 112a57c..86828ee 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1237,12 +1237,17 @@ class SnmpValueSpec(TypedDict, total=False): ``table``, a column walked and folded to one value by ``fold``. ``pattern`` is a regular expression whose first group is the number, for an agent that answers with text. + + ``unknown`` says the agent answers this value wrongly, or not at all, where it + should: the application reports no value -- neither the standard reading nor a + default. It stands alone, without ``oids`` or ``table``. """ oids: list[str] table: str fold: Literal["first", "average", "max"] pattern: str + unknown: bool class SnmpMemorySpec(TypedDict, total=False): @@ -1267,8 +1272,8 @@ class SnmpHealthProfile(TypedDict, total=False): A driver declares it as ``SNMP_HEALTH_PROFILE`` when its device does not answer the standard UCD-MIB and IF-MIB; the application polls and computes. What a - profile does not name is read the standard way. Uptime is in TimeTicks, CPU in - percent busy. + profile does not name is read the standard way, and what it marks ``unknown`` is + not read at all. Uptime is in TimeTicks, CPU in percent busy. """ uptime: SnmpValueSpec diff --git a/tests/test_snmp_health_profile.py b/tests/test_snmp_health_profile.py index c5b306b..c0f8054 100644 --- a/tests/test_snmp_health_profile.py +++ b/tests/test_snmp_health_profile.py @@ -22,7 +22,7 @@ from napalm_device_types import ( def test_a_profile_says_where_each_value_lives(): assert set(get_type_hints(SnmpHealthProfile)) == {"uptime", "cpu", "memory", "interfaces"} - assert set(get_type_hints(SnmpValueSpec)) == {"oids", "table", "fold", "pattern"} + assert set(get_type_hints(SnmpValueSpec)) == {"oids", "table", "fold", "pattern", "unknown"} assert set(get_type_hints(SnmpMemorySpec)) == {"total", "used", "free", "percent", "unit"} assert set(get_type_hints(SnmpInterfacesSpec)) == {"skip", "tx_errors_are_drops"} @@ -42,6 +42,16 @@ def test_a_driver_declares_its_profile_as_a_class_attribute(): assert Driver.SNMP_HEALTH_PROFILE["cpu"]["oids"][0] == "1.3.6.1.4.1.9.1" +def test_a_value_the_agent_gets_wrong_is_declared_unknown(): + """Neither the standard reading nor a default: the application reports none.""" + assert get_type_hints(SnmpValueSpec)["unknown"] is bool + + class Driver: + SNMP_HEALTH_PROFILE: ClassVar[SnmpHealthProfile] = {"cpu": {"unknown": True}} + + assert Driver.SNMP_HEALTH_PROFILE["cpu"].get("unknown") is True + + def test_the_collector_in_the_base_package_warns_that_it_is_deprecated(): async def get(oid): return None