feat(snmp): let a health profile mark a value unknown #72

Merged
christianmanivong merged 4 commits from feat/health-profile-unknown into main 2026-11-01 23:01:41 +00:00
8 changed files with 105 additions and 55 deletions

No files matched your search

+8
View File
@@ -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,
@@ -29,6 +33,10 @@ recorded here; their history is the git log.
and how many there are), and `ClusterNodeDict.votes`. All `NotRequired`, so
drivers written before stay valid; None means could not be read, `[]` read and
empty.
- `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).
- `VMProvisionIncomplete` (`napalm_device_types.provisioning`): what
`create_vm_from_cloud_init` raises when it fails after the VM was created. A
`RuntimeError` with the failure as its cause and the half-built VM's `vmid` and
+3
View File
@@ -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
+6 -4
View File
@@ -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
@@ -196,6 +192,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,
)
+2 -2
View File
@@ -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.
+6 -47
View File
@@ -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,53 +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.
"""
oids: list[str]
table: str
fold: Literal["first", "average", "max"]
pattern: str
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. 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."""
@@ -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
+1 -1
View File
@@ -32,7 +32,7 @@
},
"mypy_relaxed": [],
"python_file_lines": {
"napalm_device_types/models.py": 1504
"napalm_device_types/models.py": 1463
},
"untyped_public": []
}
+19 -1
View File
@@ -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,24 @@ 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_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