From 9f6ffa8a25322455dfcbe3fc5dd5c3d33f05955e Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 22:11:19 +0100 Subject: [PATCH 1/2] 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 -- 2.54.0 From f4354f498eade775bba88bec1dcff68e0eba7be8 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 23:05:13 +0100 Subject: [PATCH 2/2] refactor: the SNMP health profile shapes in snmp_health_profile.py models.py is over the file size limit and may not grow; the unknown key pushed it past its recorded length. SnmpHealthProfile, SnmpValueSpec, SnmpMemorySpec and SnmpInterfacesSpec move to napalm_device_types/snmp_health_profile.py. The package exports them as before and models re-exports them, so existing imports keep working. The baseline records the smaller models.py. --- CHANGELOG.md | 4 ++ napalm_device_types/__init__.py | 10 ++-- napalm_device_types/health_metrics.py | 4 +- napalm_device_types/models.py | 58 +++------------------ napalm_device_types/snmp_health_profile.py | 60 ++++++++++++++++++++++ tests/quality_baseline.json | 2 +- tests/test_snmp_health_profile.py | 8 +++ 7 files changed, 87 insertions(+), 59 deletions(-) create mode 100644 napalm_device_types/snmp_health_profile.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f06606..b02fcff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ recorded here; their history is the git log. on 3.12, so 3.10 and 3.11 are no longer tested (NAPALM/driver-standard#6). - The floor on napalm is 5.1: older releases import `pkg_resources`, which a Python 3.12 venv no longer has. +- The SNMP health profile shapes (`SnmpHealthProfile`, `SnmpValueSpec`, + `SnmpMemorySpec`, `SnmpInterfacesSpec`) are defined in + `napalm_device_types.snmp_health_profile`. The package and `models` still export + them, so an existing import keeps working. ### Added - `HypervisorDriver.get_vm_migration_preflight(name)`, `migrate_vm(name, target_node, diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 31df183..3acdac1 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -163,10 +163,6 @@ from napalm_device_types.models import ( PowerAction, PowerStateDict, SnmpAgentSettingsDict, - SnmpHealthProfile, - SnmpInterfacesSpec, - SnmpMemorySpec, - SnmpValueSpec, UpdateProgressDict, ) from napalm_device_types.nat_vpn import NatVpnMixin @@ -195,6 +191,12 @@ from napalm_device_types.service_packages import ( parse_service_packages, ) from napalm_device_types.services import ServiceControlMixin +from napalm_device_types.snmp_health_profile import ( + SnmpHealthProfile, + SnmpInterfacesSpec, + SnmpMemorySpec, + SnmpValueSpec, +) from napalm_device_types.ssh_host_keys import ( KNOWN_KEYS_ARG as SSH_HOST_KEYS_ARG, ) diff --git a/napalm_device_types/health_metrics.py b/napalm_device_types/health_metrics.py index 5066475..de0bd45 100644 --- a/napalm_device_types/health_metrics.py +++ b/napalm_device_types/health_metrics.py @@ -2,8 +2,8 @@ **Deprecated** (docs/STRUCTURE.md): drivers do not collect over SNMP. The application polls; a driver whose device publishes values under its own OIDs -declares them as ``SNMP_HEALTH_PROFILE`` (:class:`~napalm_device_types.models.SnmpHealthProfile`). -This mixin goes in 5.0. +declares them as ``SNMP_HEALTH_PROFILE`` +(:class:`~napalm_device_types.snmp_health_profile.SnmpHealthProfile`). This mixin goes in 5.0. The collection itself is generic: CPU, memory, uptime, load and per-interface counters come from the same standard OIDs on any UCD-MIB/IF-MIB capable device. diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 86828ee..b791092 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -9,6 +9,12 @@ from typing import Literal, NotRequired, get_args from typing_extensions import TypedDict +# The SNMP health profile shapes live in snmp_health_profile.py; re-exported here, where they were. +from napalm_device_types.snmp_health_profile import SnmpHealthProfile as SnmpHealthProfile +from napalm_device_types.snmp_health_profile import SnmpInterfacesSpec as SnmpInterfacesSpec +from napalm_device_types.snmp_health_profile import SnmpMemorySpec as SnmpMemorySpec +from napalm_device_types.snmp_health_profile import SnmpValueSpec as SnmpValueSpec + # --------------------------------------------------------------------------- # Common (shared across device types) # --------------------------------------------------------------------------- @@ -1230,58 +1236,6 @@ class SnmpAgentSettingsDict(TypedDict): listen: NotRequired[str] # the address the agent binds to; absent: every address -class SnmpValueSpec(TypedDict, total=False): - """Where an SNMP agent publishes one value, inside a ``SnmpHealthProfile``. - - Either ``oids``, scalars asked in order (the first non-empty answer wins), or - ``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): - """Memory: ``total`` with ``used`` or ``free``, or ``percent`` alone.""" - - total: SnmpValueSpec - used: SnmpValueSpec - free: SnmpValueSpec - percent: SnmpValueSpec - unit: Literal["KiB", "bytes"] # of total, used and free; KiB, as UCD-MIB counts, by default - - -class SnmpInterfacesSpec(TypedDict, total=False): - """How the IF-MIB counters of a device are to be read.""" - - skip: str # a pattern of interface names whose counters are noise, not signal - tx_errors_are_drops: bool # the device counts dropped packets as TX errors (OPNsense) - - -class SnmpHealthProfile(TypedDict, total=False): - """Where a device's SNMP agent publishes its health values. - - 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, and what it marks ``unknown`` is - not read at all. Uptime is in TimeTicks, CPU in percent busy. - """ - - uptime: SnmpValueSpec - cpu: SnmpValueSpec - memory: SnmpMemorySpec - interfaces: SnmpInterfacesSpec - - class NICConfigDict(TypedDict): """Network interface configuration for VM provisioning.""" diff --git a/napalm_device_types/snmp_health_profile.py b/napalm_device_types/snmp_health_profile.py new file mode 100644 index 0000000..7a01d5f --- /dev/null +++ b/napalm_device_types/snmp_health_profile.py @@ -0,0 +1,60 @@ +"""The shape a driver states its device's SNMP health OIDs in (``SNMP_HEALTH_PROFILE``). + +Apart from ``models.py``, which is over the file size limit; ``models`` still exports them. +""" + +from typing import Literal + +from typing_extensions import TypedDict + + +class SnmpValueSpec(TypedDict, total=False): + """Where an SNMP agent publishes one value, inside a ``SnmpHealthProfile``. + + Either ``oids``, scalars asked in order (the first non-empty answer wins), or + ``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): + """Memory: ``total`` with ``used`` or ``free``, or ``percent`` alone.""" + + total: SnmpValueSpec + used: SnmpValueSpec + free: SnmpValueSpec + percent: SnmpValueSpec + unit: Literal["KiB", "bytes"] # of total, used and free; KiB, as UCD-MIB counts, by default + + +class SnmpInterfacesSpec(TypedDict, total=False): + """How the IF-MIB counters of a device are to be read.""" + + skip: str # a pattern of interface names whose counters are noise, not signal + tx_errors_are_drops: bool # the device counts dropped packets as TX errors (OPNsense) + + +class SnmpHealthProfile(TypedDict, total=False): + """Where a device's SNMP agent publishes its health values. + + 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, and what it marks ``unknown`` is + not read at all. Uptime is in TimeTicks, CPU in percent busy. + """ + + uptime: SnmpValueSpec + cpu: SnmpValueSpec + memory: SnmpMemorySpec + interfaces: SnmpInterfacesSpec diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 82c402c..3b89766 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -32,7 +32,7 @@ }, "mypy_relaxed": [], "python_file_lines": { - "napalm_device_types/models.py": 1504 + "napalm_device_types/models.py": 1463 }, "untyped_public": [] } diff --git a/tests/test_snmp_health_profile.py b/tests/test_snmp_health_profile.py index c0f8054..b4f2a10 100644 --- a/tests/test_snmp_health_profile.py +++ b/tests/test_snmp_health_profile.py @@ -52,6 +52,14 @@ def test_a_value_the_agent_gets_wrong_is_declared_unknown(): assert Driver.SNMP_HEALTH_PROFILE["cpu"].get("unknown") is True +def test_the_shapes_live_in_their_own_module_and_models_still_exports_them(): + from napalm_device_types import models, snmp_health_profile + + for name in ("SnmpHealthProfile", "SnmpValueSpec", "SnmpMemorySpec", "SnmpInterfacesSpec"): + assert getattr(models, name) is getattr(snmp_health_profile, name), name + assert getattr(snmp_health_profile, name).__module__ == snmp_health_profile.__name__ + + def test_the_collector_in_the_base_package_warns_that_it_is_deprecated(): async def get(oid): return None -- 2.54.0