# 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](/help/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`.