Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Hosts and Items

Zabbix Value Types and Item Preprocessing: Rates, JSONPath, Regex, Discard

Learn Zabbix types of information and preprocessing steps: change per second, multiplier, regular expressions, JSONPath, XPath, discard unchanged, custom scripts and error handling.

Raw values from the world are rarely in the form you want to store. A network counter must become a rate, a JSON document must yield one number, a temperature in tenths of a degree must be divided by ten, and a web page must be reduced to one status. Zabbix does these conversions in item preprocessing, a pipeline of steps that runs on the server (or proxy) after a value is collected and before it is stored or checked by triggers.

Zabbix does not run on this site. The TryIt blocks are Python stand-ins that implement the same operations so you can see exactly what each step does.

Types of information

Every item has a type of information that defines how the value is stored:

Type Stores Typical use
Numeric (unsigned) Integers 0 to 2^64-1 Counters, byte counts, status codes
Numeric (float) Decimal numbers CPU load, percentages, temperatures
Character Text up to 255 characters Short states, versions
Log Log lines with timestamp, severity and source log[...] items
Text Long text (up to 64 KB) Command output, configuration
Binary (7.0) Binary data (for example from browser items) Screenshots in browser monitoring

If the collected value does not fit, the item becomes Not supported. Numeric (unsigned) cannot hold -3 or 0.5. When unsure, use Numeric (float) for numbers. Text and Character items are stored in history only; they have no trends.

The preprocessing pipeline

On the item's Preprocessing tab you add steps; they run in order, and each step's output is the next step's input. Common steps:

Step Effect
Custom multiplier Multiply by a number (e.g. 8 for bytes to bits, 0.1 for tenths)
Right/Left trim, Trim Remove characters from the ends
Regular expression Match a regex and output a pattern like \1
Replace Replace text
Boolean/Octal/Hexadecimal to decimal Convert numeral formats
Change per second (new - old) / seconds; for counters
Simple change new - old; for event counts per interval
JSONPath Extract from JSON: $.status.cpu
XML XPath Extract from XML
CSV to JSON, XML to JSON Convert formats
SNMP walk value / walk to JSON Extract from SNMP walk results
JavaScript Custom code for anything else
Check for error in JSON/XML/regex Detect an error message in a response
Discard unchanged Drop the value if equal to the previous one
Discard unchanged with heartbeat Same, but store at least once per heartbeat period
Throttling (7.0 additions) Limit the rate of stored values
Prometheus pattern / to JSON Read Prometheus exporter text

Preprocessing runs before storage, so history already contains the transformed value. Test the whole pipeline in the item form: paste a sample raw value and the dialog shows the result of every step.

Counters: change per second

For cumulative counters, such as net.if.in[eth0,bytes], the useful value is the rate. Set a step Change per second, then Custom multiplier 8 to get bits per second. The order matters: rate first, then multiplier. Zabbix handles the first sample (no previous value, no output) and counter resets (a negative difference is discarded).

Python Stand-in: change per second and multiplier

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

JSONPath

Many APIs return JSON. JSONPath selects parts of it: $.data.items[0].value, $.users[?(@.active==true)].name, $..cpu. A typical pattern is one HTTP agent master item returning a big JSON document, and a number of dependent items, each with one JSONPath step.

Python Stand-in: JSON extraction

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Regular expressions

The Regular expression step takes a pattern and an output template (\1 is the first group). Example: the output of a command is uptime: 15 days, load 0.52 and you want the load. Pattern load ([0-9.]+), output \1 returns 0.52. If the pattern does not match, the step fails (item becomes Not supported) unless you choose Custom on fail to discard or set a default value.

Error handling per step

Every step has Custom on fail:

  • Discard value: skip this value silently (no new history).
  • Set value to: store a fixed value, such as 0.
  • Set error to: make the item unsupported with your message.

Use Discard for known-noisy sources and Set value when a missing match legitimately means zero.

Discard unchanged

If a status item changes rarely (a software version, a mounted flag), storing a value every minute wastes space. Discard unchanged with heartbeat keeps only changes, plus one value every N hours so the graphs and the "no data" checks stay alive. This can shrink the database considerably. Note that triggers using last() still work, but count or avg over time need the stored values, so choose carefully.

Python Stand-in: discard unchanged with heartbeat

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Which side does the work?

Prefer preprocessing over doing math in triggers, so the stored history already has the right meaning and graphs are correct. Use JavaScript preprocessing only if no standard step fits; it is flexible (parsing odd formats, combining fields) but slower and harder to maintain. Each JavaScript step receives value and returns the new value.

JavaScript
var data = JSON.parse(value);
return data.items.filter(function (i) { return i.state === 'failed'; }).length;

Units, multipliers and value mapping

  • Units only affect display: with B, a value of 2048 is shown as 2 KB. With %, s, bps and uptime Zabbix has special formatting (uptime shows days and hours).
  • Value mapping translates numeric codes into text for display (1 = Up, 2 = Down) in Latest data, graphs and problem names, but triggers still compare the numbers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which preprocessing step converts a growing byte counter into a rate?

    Change per second divides the difference between two samples by the elapsed seconds.
  2. 2. How do you turn a bytes-per-second rate into bits per second?

    Eight bits per byte; apply the multiplier after the rate.
  3. 3. Which type of information should you choose for a CPU load such as 0.52?

    Unsigned cannot hold decimals; float can.
  4. 4. What does Discard unchanged with heartbeat do?

    It saves space for rarely changing items while keeping the item alive.

Summary

  • Pick the right type of information; unsupported conversions make items Not supported.
  • Preprocessing steps run in order on the server before storage.
  • Use Change per second for counters, JSONPath for APIs, Regex for text, JavaScript as a last resort.
  • Set Custom on fail deliberately: discard, default value or error.
  • Discard unchanged (with heartbeat) saves database space for slow-changing data.

Next: History, trends and housekeeping