SNMP interpretation¶
Since v1.9.448
An Interpretation block in the configuration tab of snmp, snmp_oid, and snmp_string — one place for what used to be scattered across several fields.
Short version: An SNMP check returns a raw value — a number or a text. The Interpretation block in the check configuration decides in one step: is this a state (a code with a fixed meaning), a metric (a number that gets converted), or text? And what does the actual value mean?
What it's for¶
SNMP devices answer in their own language: a 2 means "down" on a network interface, "running on battery" on a UPS, "warming up" on a printer — something entirely different depending on the MIB. Without interpretation the check only shows the bare number, and whether it's good or bad is only obvious to someone who knows the MIB by heart.
The interpretation block turns that into a fixed mapping: for every return value it defines a label and a status. It affects three check types, each with the value kinds that make sense for it:
| Check type | Label in the UI | Possible value kinds |
|---|---|---|
snmp |
SNMP query | Metric |
snmp_oid |
SNMP state / single value (OID) | State, Metric |
snmp_string |
SNMP text | State, Metric, Text |
For snmp_oid and snmp_string, a switch at the top of the block picks the value kind; snmp always returns a number.
Step by step: adjusting an SNMP value¶
The block sits on the individual check, not on the profile — what you set here applies to this device. (For every device of a type, the same setting belongs in the device profile; a profile check has the same block.)
- Open the device → tab Checks → click the SNMP check. The panel opens on the right.
- Switch to Configuration (in the check's full screen: the "Configuration" tab).
- The Interpretation block sits below the basic fields (OID, community). At the top it shows the return value — the raw value from the last result, marked "last result". If none has been stored yet ("no raw value stored yet") or the check has no device behind it, the field sample value for the preview appears instead.
- Choose the value kind — state · metric · text (with
snmpthere is no choice: it is always a metric). - Fill in what that kind needs: the mapping (table value / label / status), the conversion (factor, offset, unit, display) or the text evaluation.
- At the bottom stands Result: what becomes of the return value — message, status, metric. If it fits, save.
The change takes effect with the next result of the check; for a check run by the Active-Checker, "Check now" fetches it immediately, otherwise it applies with the next run.
First look at what the device actually delivers
Still looking for the OID? The device scan on the host lists what the device exposes and turns it into ready-made checks. The interpretation block is the second step — it gives the value its meaning.
State: value → label → status¶
For a state value, the block builds a table of value → label → status. A good example is a network interface's operational status, ifOperStatus from the IF-MIB, OID 1.3.6.1.2.1.2.2.1.8.<port number>:
| Value | Label | Status |
|---|---|---|
| 1 | up | OK |
| 2 | down | CRITICAL |
| 3 | testing | WARNING |
If the device returns 2, the check reports CRITICAL with the message down (2). The label is optional — without it the message just shows the bare raw value. A row with a label but no status of its own judges with the status of the other values, never silently OK. On snmp_oid, individual values can only be OK, WARNING or CRITICAL; UNKNOWN is only available via the other values.
Below the table sits a separate row, other values: the status for any value that isn't in the table. What that means is explained below under "State value without a mapping".
Under the hood, the table lands in different fields depending on the check type — for snmp_oid in OK values / WARNING values / CRITICAL values, for snmp_string in Status per value — the block writes the right ones automatically while you edit. It makes no difference for how you use it.
Metric: factor, offset, unit, display¶
When the OID returns a number, the order is: factor (scaling), then offset, then the unit, and finally the display used for the message — value × factor + offset.
Typical examples for factor and offset:
| Goal | Factor | Offset |
|---|---|---|
| bit/s → Mbit/s | 0.000001 | — |
| tenths of a degree → degrees | 0.1 | — |
| Kelvin → °C | 1 | −273.15 |
Not every numeric value accepts a conversion
If the check already computes something itself — percent (value ÷ reference OID or reference column × 100, computed from the raw values) or the number of rows of a table — factor, offset and display have no effect; the block hides them and says why. With the aggregation sum, the offset additionally has no effect (it would be added per row). With max/min/average over a walk, factor and offset apply per row. As its return value, a walk check shows the raw value of the deciding row together with its type and aggregation.
The display turns the already-scaled value into something readable for the message. For bytes and the SI prefix the underlying metric stays unchanged — only for timeticks does it switch to seconds, because thresholds against a raw hundredth of a second wouldn't mean anything:
| Display | Typical for | Message | Metric used for thresholds |
|---|---|---|---|
| Duration from timeticks (1/100 s) | sysUpTime |
2d 1h 58m |
switches to seconds |
| Duration from seconds | already seconds | 2d 1h 58m |
stays seconds |
| Bytes, readable (KB / MB / GB) | storage, traffic counters | 12.3 GB |
stays bytes |
| SI prefix before the unit (k / M / G) | bit rates | 1.0 Gbit/s |
stays in the base unit |
Example: sysUpTime (OID 1.3.6.1.2.1.1.3.0) returns timeticks — 17993930. With the "Duration from timeticks" display, the message reads 2d 1h 58m, and the metric used for a threshold is in seconds (179939.3) — a threshold of "warn above 300" then means five minutes of uptime, not 300 timeticks.
Special case: bitmask¶
Some OIDs return a bitmask in which every set bit stands for its own message — typically hrPrinterDetectedErrorState ("low toner" and "paper jam" at the same time). Such checks judge per set bit via the fields Bitmask: bit → label / severity under "Advanced"; mapping, conversion and text evaluation have no effect there, and the block says so on the spot. The metric is the number of set bits.
Text: evaluating the text¶
Only for snmp_string: an expected text, either an exact match or a regex pattern, plus the reversal option "CRITICAL if it matches" (a match counts as a failure instead of a match counting as OK). Without an expected text the check is always OK and just shows the text it read.
Example: expected text running, match = OK. If the service reports stopped, the check turns CRITICAL with a note about the expected value.
Displaying addresses, dates and truth values¶
Some values arrive as raw bytes: MAC addresses, IP addresses in an OCTET STRING column, timestamps in DateAndTime format. The Display option in the text block turns them into readable text before the evaluation and the message use them:
| Display | Raw value | Message |
|---|---|---|
| MAC address | 6 bytes | 00:11:22:aa:bb:cc |
| IP address | 4 or 16 bytes (also with zone) | 10.0.0.1, 2001:db8::1, 10.0.0.1%3 |
| Date and time | DateAndTime (8 or 11 bytes) |
2026-10-14 13:05:07 +02:00 |
| Truth value | 1 / 2 (TruthValue) |
true / false (the value stays 1 / 2) |
The expected text is compared with the readable form — 00:11:22:aa:bb:cc, not the bytes. If a value does not fit the display (wrong length, invalid date) the text stays as delivered; nothing is guessed. An older collector does not know the new display options yet and shows the text as before.
Preview before saving¶
At the bottom of the block sits Result: message, status and, if there is one, the metric with its unit. It's computed on the server, using the same function that the worker and the collector use for the real evaluation — what's shown here isn't an approximation, it's the actual result for the value you entered.
The return value used for the preview comes automatically from the check's last result, if one already exists. Without a result, or without a device behind the check, there's instead a field Sample value for the preview to see how a value would turn out anyway.
For the interface example above: enter 2 as the return value, and the result immediately shows down (2) · CRITICAL.
OID catalog: apply from catalog¶
Known OIDs don't need to be typed in by hand. If Vesana knows the OID, the state mapping shows an Apply from catalog button next to "Add value" — one click fills the whole table with labels and a suggested status.
The catalog draws on two sources:
- Standard MIBs, maintained by hand (IF-MIB, HOST-RESOURCES-MIB, ENTITY-SENSOR-MIB, UPS-MIB, POWER-ETHERNET-MIB, BRIDGE-MIB).
- Device profiles from the Vesana library — whatever label and status a profile carries for an OID automatically flows into the catalog.
The number of known OIDs grows with every new or updated library profile. For ifOperStatus from the example above, the catalog actually supplies all seven standard states (up / down / testing / unknown / dormant / notPresent / lowerLayerDown), not just the two from the short version above.
If a MIB is available for the OID, Take from MIB sits next to it: it fills the labels of the state values or the factor and unit from the MIB. A value the check type cannot express is left empty by the import — it then falls under the other values.
The suggested statuses are a suggestion based on operational sense (up = OK, down = CRITICAL, testing = WARNING) — nothing stops you from adjusting them after applying. An OID with no entry returns nothing: the catalog never guesses, it only knows what it knows.
Fallback OID when the primary OID is missing¶
Some devices carry the same metric under a different OID depending on firmware version or model line — the best-known example is sysUpTime versus hrSystemUptime. The Fallback OID field (on snmp and snmp_oid, under "Advanced") closes that gap without a second check: if the device answers the primary OID with "not present" (noSuchObject/noSuchInstance/endOfMibView), the check reads the fallback OID instead. A timeout or an error on the primary OID does not trigger a fallback attempt. The field does not exist for a table walk. The message then states that the value came from the fallback OID — interpretation (mapping, conversion, display) applies to the fallback value exactly as it does to the primary one. Without a configured fallback OID, behavior is unchanged.
State value without a mapping is never silently OK¶
Behavior change since v1.9.448
Previously, a state value without a mapping simply stayed OK — an unknown number was silently treated as unremarkable. Now it reports WARNING: a value nobody entered is not a guarantee that everything is fine — it's a blind spot someone should look at.
If the device returns a value that isn't in the mapping table, the status comes from the other values row — default WARNING, adjustable to CRITICAL, UNKNOWN, or OK. The message reads Unbekannter Wert <value> — Zuordnung fehlt (currently always in German).
In the check's status tab, an Add mapping button offers directly to add the missing value as a new row in the interpretation block — with the actual raw value already filled in. One click, set a label and status, save.
OK for other values makes the check silent
Setting "other values" to OK means the check can never turn WARNING or CRITICAL from an unknown value again. The block shows a warning right below the table for exactly that reason.
Interpretation and thresholds¶
Both judge the same check, but in different places — this is the most common mix-up:
| Interpretation | Thresholds | |
|---|---|---|
| What for | giving a state or text its meaning; making a number readable | holding a number against a limit |
| Result | status from the mapping, message in plain words | WARNING / CRITICAL from the limit onwards |
| Where | "Interpretation" block in the configuration | threshold fields, right below the measured value |
How they interact, in one sentence: the conversion decides WHICH number the threshold measures against.
- Factor and offset apply to the metric. If you convert tenths of a degree to degrees (factor 0.1), a threshold "warning from 60" afterwards means degrees — not tenths.
- The display does NOT change the number — except for timeticks: there the metric switches to seconds (thresholds against hundredths of a second would be pointless). Bytes stay bytes, an SI prefix is display only.
- A state value needs no thresholds — and does not get any: on an SNMP state check the threshold fields are locked, with the reason shown in the status tab and the editor ("the status comes from the mapping; the metric is only the code of the state"). Otherwise a
2meaning "down" would have counted as a number against a limit. - If the value is text without a number, there is neither a metric nor a threshold — only the text evaluation.
Where it is computed — and when a change takes effect¶
The interpretation lives in the check configuration, not in the collector binary. So there are two places where it can apply:
- On the collector, if it already knows the rule (current version) — the result arrives fully interpreted.
- On the server on arrival, if the collector only sends the raw value. The outcome is identical: both sides compute with the same rule.
For you that means: a changed mapping takes effect with the next result, even if a collector has not been updated yet. What it does not do is act retroactively: results already stored in the history stay as they were measured.
Library profiles bring the mapping ready-made¶
Device profiles from the Vesana library usually carry the interpretation fully worked out already: every state value has its meaning, every number its unit and display. A profile update picks up a new profile version including a revised mapping, without having to touch the individual checks; profiles not changed locally update automatically.
Common questions and symptoms¶
The check only shows a bare number, e.g. 2.
No mapping is stored. Set the value kind to state and fill the table — or, if Vesana knows the OID, use Apply from catalog.
The check is WARNING with "Unknown value 5 — mapping missing". The device reported a state that is not in your table. The check's status tab offers Add mapping — the button creates the row with that exact value. Then set label and status, save, done.
The check used to be OK and has been WARNING since the update. Exactly this case: previously an unknown state value silently counted as OK. Look at which value the device delivers — either it belongs in the mapping, or the other values row is deliberately set to OK.
The uptime shows up as a huge number in the message (17993930).
Those are timeticks. Set the display to duration from timeticks; the message then shows 2d 1h 58m, and the metric is in seconds.
The threshold does not trigger although the number is above it. Check which number it measures against: factor and offset apply before the threshold, the display (except timeticks) does not change the metric. What the check really carries as its metric is shown in the preview result.
The check can never turn red. If "other values" is set to OK and the mapping only covers harmless values, there is no path to WARNING or CRITICAL. The block warns about this itself.
I saved and nothing changes. The interpretation applies from the next result — with a long interval that can take a while. For a check run by the Active-Checker, "Check now" fetches it immediately.
The value arrives as text although it is a number.
snmp_string reads the value as text; if it is a plain number, that number is additionally carried as a metric. For plain numbers, snmp_oid (or snmp) is still the better type.
The check is UNKNOWN with "… Muster vereinfachen". A custom regex pattern took too long. Simplify the pattern; the preview shows the same hint.
Where do I set this for ALL devices? In the device profile: the same block on the profile check. Devices inherit it; what you change on a single device applies only there and survives a profile update.
Next¶
- Check type reference — every field of
snmp,snmp_oid, andsnmp_string - SNMP sensor picker — find OIDs on the device before interpreting them
- MIBs — upload vendor MIBs so OIDs carry names and value lists
- Vesana library — install device profiles with the interpretation already done