Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Hosts and Items

Zabbix Items and Item Keys: Types, Intervals, Parameters and Testing

Learn what a Zabbix item is: item types, key syntax with parameters, update intervals and custom intervals, units, the Test button, and troubleshooting unsupported items.

An item is a single metric that Zabbix collects from a host: "the 1-minute CPU load", "free space on /var", "HTTP status of the home page". Every number you graph and every trigger you write is based on an item. If hosts are the nouns of Zabbix, items are the verbs: they say what to collect and how.

Zabbix does not run on this site; forms are described in words and TryIt blocks are Python stand-ins.

Anatomy of an item

In Data collection > Hosts > (host) > Items > Create item the important fields are:

Field Meaning
Name A human-readable label, for example Free disk space on /. Can contain macros like $1 (the key parameter) or {#FSNAME} (discovery).
Type How the value is collected: Zabbix agent, Zabbix agent (active), Simple check, SNMP agent, Zabbix trapper, HTTP agent, Calculated, Dependent item, and more.
Key The identifier of the metric, passed to the agent or evaluated by the server. Unique per host.
Type of information Numeric (unsigned), Numeric (float), Character, Log, Text, Binary. See value types.
Host interface Which interface is used.
Units A suffix such as B, bps, %, s; Zabbix scales it into K, M, G.
Update interval How often to collect, for example 1m or 30s.
Custom intervals Flexible or scheduling rules, e.g. every 10s on weekdays 9-18 and every 5m otherwise.
History / Trends storage period How long to keep raw values and hourly aggregates.
Value mapping Shows 1 as "Up" and 0 as "Down" in the UI.
Tags, Description, Enabled Metadata for filtering and documentation.

Item keys

A key is a short string like system.cpu.load[all,avg1]. It has a name made of dot-separated words and optional parameters in square brackets, separated by commas.

TEXT
vfs.fs.size[/var,pfree]
net.tcp.service[http,,8080]
web.page.regexp[www.example.com,/,80,"Welcome",,]
agent.ping

Rules to remember:

  • Parameters are positional. Skip one by leaving it empty: net.tcp.service[http,,8080] leaves the IP empty, so the host's interface address is used.
  • Quote parameters containing commas, spaces or brackets: ["a,b"].
  • Keys are case-sensitive.
  • A key must be unique per host. Two items with the same key on one host are not allowed (use different parameters).
  • Agent keys are defined by the agent. Server-evaluated keys (simple checks like icmpping, net.tcp.service; internal zabbix[...]; calculated last(...); HTTP agent) are handled by the server. SNMP items use a name of your choice plus an OID field.
Python Stand-in: parse an item key

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.

Update intervals

The update interval decides how often the value is collected. Defaults in templates are often 1m, but you should think about each metric:

  • Fast (10-30 s): things that change quickly and matter quickly, like a service ping.
  • Normal (1 m): CPU, memory, network traffic.
  • Slow (5-60 m): disk space, certificate expiry, software versions.
  • 0 with a custom schedule: collect only at certain times.

Intervals accept suffixes: 30s, 5m, 1h, 1d, 1w. Zabbix spreads items across time, so not all items run at the same second. Custom intervals can be of two kinds: flexible (interval + time period, such as 10s during 1-5,09:00-18:00) and scheduling (cron-like md1h9m0 means every Monday at 9:00).

Shorter intervals mean more load: halving the interval doubles the NVPS contribution of that item. Zabbix also needs a trigger window that makes sense: a trigger over avg(5m) makes no use of values every 5 seconds.

Python Stand-in: interval cost

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.

Testing an item

At the bottom of the item form, Test runs the item right now and shows the value, or the error, without saving it. In the test dialog you can also test preprocessing step by step. Before you save a new item, always test. You can also test from the command line:

Terminal
zabbix_get -s 192.0.2.10 -k "vfs.fs.size[/var,pfree]"

If a key is not supported by an agent you get ZBX_NOTSUPPORTED. In the frontend such an item turns to the Not supported state (a gray cross) and the reason appears in a tooltip or in Latest data. Zabbix retries unsupported items every UnsupportedItemsRefreshPeriod-style interval (default 10 minutes), so fix the cause and wait, or use Execute now to collect immediately.

Common reasons for "Not supported"

  1. Wrong key name or parameter (typo, wrong case).
  2. The agent version does not know the key (use agent.version and check the docs).
  3. The agent cannot read the resource (permissions on /proc, a log file, a Windows counter).
  4. Wrong value type: a text value stored in a numeric item (Value of type "string" is not suitable for value type "Numeric (unsigned)").
  5. The agent is unreachable (in which case you see the host as unavailable instead).
  6. Timeout: a slow command exceeded the agent Timeout (default 3 s, up to 30 s).

Item types in practice

You want to monitor Item type
CPU, memory, disks of a server Zabbix agent (active or passive)
Is port 443 open on a remote host? Simple check net.tcp.service[https,,443]
Interface traffic on a switch SNMP agent
JSON from a REST API HTTP agent + JSONPath preprocessing
A nightly job result Zabbix trapper + zabbix_sender
A ratio of two other items Calculated: last(/h/a)/last(/h/b)*100
Many fields from one request Dependent items from a master item
A custom script External check or UserParameter

Calculated and dependent items

Calculated items compute a value from other items with the same expression syntax used by triggers. For example: 100 * last(//vfs.fs.size[/,used]) / last(//vfs.fs.size[/,total]) (the // means "the same host"). Dependent items take their value from a master item by preprocessing, so one expensive request (an API response with 50 fields) produces 50 items with one collection.

Python Stand-in: calculated and dependent items

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does net.tcp.service[http,,8080] leave empty on purpose?

    Parameters are positional; the empty second parameter means the default (the host's interface address).
  2. 2. What does the Test button do?

    Test collects a value immediately so you can debug keys and preprocessing.
  3. 3. Which item type pushes data from a script via zabbix_sender?

    Trapper items accept values sent to the server.
  4. 4. Why use dependent items?

    A master item fetches once; dependent items extract fields by preprocessing.

Summary

  • An item = name + type + key + value type + interval + storage settings.
  • Keys have a name and positional parameters in brackets; quote tricky parameters.
  • Pick intervals per metric; shorter intervals multiply load.
  • Use Test and zabbix_get; know the usual reasons for Not supported.
  • Calculated and dependent items derive values without extra collection.

Next: Common agent item keys