Skip to content

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 OID (generic) 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.)

  1. Open the device → tab Checks → click the SNMP check. The panel opens on the right.
  2. Switch to Configuration (in the check's full screen: the "Configuration" tab).
  3. 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.
  4. Choose the value kind — state · metric · text (with snmp there is no choice: it is always a metric).
  5. Fill in what that kind needs: the mapping (table value / label / status), the conversion (factor, offset, unit, display) or the text evaluation.
  6. 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; if you do not want to wait, trigger it ("Check now" on the active checker, "Collect now" on the device).

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.

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 × 100) 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, the conversion applies to the deciding row.

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.

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).
  • Curated device profiles from the Community Hub — whatever label and status a profile carries for an OID automatically flows into the catalog.

Together that's currently 89 known OID entries (as of v1.9.448) — the number grows with every new or updated hub 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.

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.

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 Unknown value <value> — mapping missing.

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 2 meaning "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:

  1. On the collector, if it already knows the rule (current version) — the result arrives fully interpreted.
  2. 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.

Hub device profiles bring the mapping ready-made

Device profiles from the Community Hub usually carry the interpretation fully worked out already: every state value has its meaning, every number its unit and display. Clicking Update profile picks up a new profile version including a revised mapping, without having to touch the individual checks.

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. "Check now" (active checker) or "Collect now" on the device fetches it immediately.

The value arrives as text although it is a number. snmp_string reads the value as text; if it contains a number, that number is additionally carried as a metric as soon as unit or display are set. For plain numbers, snmp_oid (or snmp) is the better type.

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