nmon/docs/profiles.md

Adding a device profile

A profile tells nmon what to collect from one kind of device. nmon ships profiles for common gear (see Collection coverage). When your device is only partly covered, or not at all, write one. Profiles are YAML files; nmon never reads a MIB while polling, so every metric is a numeric OID.

Where profiles live

Shipped profiles are built into the binary. Your own go in <data-dir>/profiles/*.yaml; they are loaded over the shipped ones, and a profile with the same name replaces the shipped one. Restart nmon serve after changing a file, and run nmon profile test first to catch mistakes: a profile that fails validation is refused with an error naming the file.

Basics

name: acme-switch
extends: generic
priority: 20
match:
  sysObjectID: 1.3.6.1.4.1.99999
  sysDescr: '(?i)^AcmeOS'
interfaces:
  exclude_ifname: ['^Vlan', '^Tunnel']
metrics:
  - name: acmeCpuLoad
    category: health
    label: "CPU load (5 min)"
    oid: 1.3.6.1.4.1.99999.1.1.5
    type: gauge
    unit: percent
    interval: 5m
    index_label: { column: acmeCpuIndex, as: component }

• extends: generic inherits the standard metrics (interfaces, sysUpTime, host resources, entity sensors, LLDP). Always extend generic; your file only adds what is specific to the device.
• match picks the profile for a device at discovery. sysObjectID is an OID prefix (the vendor's enterprise number, or a product branch of it). sysDescr is a regular expression on the system description. Give either or both; both must match when both are present.
• priority: when several profiles match, the highest priority wins. generic is 0. Give a model-specific profile a higher number than the vendor-wide one, and watch overlaps: many devices run Linux and share its sysDescr, and several products share one enterprise number.
• metrics: use numeric OIDs, taken from the vendor MIB, and keep a comment naming where each came from.

Metric fields

Field	Meaning
name	Series name stored in the metric store.
oid	Numeric OID of the column or scalar.
type	counter64, counter32, gauge, status or text.
unit	percent, celsius, octets, bytes, enum, count and so on.
interval	How often to poll, for example 60s or 5m.
category	Where it shows on the device page, for example health, routing. Every metric that is not an interface metric needs one.
label	The human-readable name shown in the UI.
index_label	Which table column identifies the row, and the label it becomes (component, or iface for interfaces).
scale	Multiplier for the raw value, for example 1024 to turn kilobytes into bytes.
enum	For status metrics, the value-to-name map.

Every port is polled. Only interfaces.exclude_ifname (a list of regular expressions on the interface name) drops one. 32-bit counters on fast links are flagged unreliable and left out of totals and rollups.

Testing a profile

nmon profile test 2001:db8::10 --community public --data-dir /var/lib/nmon

profile test runs discovery and one poll against a live device with the matching profile and prints every metric with its resolved unit, so you can check the match, the OIDs and the units before the device is added. Use --version 3 --v3-user USER ... for SNMPv3 (nmon profile test --help lists every option). The --data-dir flag makes it load your profiles from <data-dir>/profiles.

Recording a device

nmon profile record 2001:db8::10 --community public --out acme.snmprec

profile record does a read-only SNMP walk and writes a .snmprec file with communities, sysContact and sysLocation redacted. Keep it: it is the best bug report for a device nmon does not understand, and it lets a profile be tested without the hardware.

Drafting metrics from a MIB

nmon profile new --mib ACME-SYSTEM-MIB

profile new compiles objects from a MIB into draft metric entries with the OID, type and enum filled in, leaving unit, category, label and interval for you. nmon ships the standard MIBs; drop a vendor MIB into the mibs/ folder (the --mibs-dir setting, by default <data-dir>/mibs) first. Review the draft, then test it with nmon profile test.