Zabbix templates and items: import, link, and where to create things

A host in Zabbix does nothing on its own. Items collect the data, triggers decide what is wrong, and both of them normally arrive attached to a template. So the two jobs everyone hits early are getting a template in, and adding something the template does not cover.

The first has one failure mode that stops people cold and takes one line to fix. The second has a choice in it that looks trivial and is the difference between editing something once and editing it four hundred times.

Importing a template

Zabbix ships a large built-in library under Data collection → Templates, and it is worth searching before importing anything - the thing you need is often already there. When it is not, you have a YAML file from a vendor, a community repository, or a generator.

Go to Data collection → Templates → Import, choose the file, and import. The confirmation dialog carries a warning worth actually reading:

The version error, and the one-line fix

The most common import failure is a complaint about an unsupported Zabbix version. It happens because every export declares which Zabbix version produced it, near the top of the file:

zabbix_export:
  version: '7.0'
  template_groups:
    ...

If that number is ahead of the version you are running, the import is refused. Open the file in any text editor, change that one value to your version, save, and import again. That alone clears the large majority of version-related import failures.

It is not magic, and it is worth knowing why. The version string does not transform anything - it just asserts what format the file is in. Editing it works when the template only uses entities your version already understands, which is usually the case. It does not work when the template genuinely relies on something newer, and then the import fails on the specific entity instead, which is a more useful error than the version one.

Items: the decision that costs the most

An item is one thing being collected - CPU utilisation, a service state, a queue depth. You can create one directly on a host, or on a template. The form is identical. The consequence is not.

Create it on a host and it collects data correctly, for that one host. Create it on a template and every host linked to that template gets it.

The asymmetry shows up at edit time, and that is the part worth internalising. Say the item key needs a parameter change eighteen months from now. On a template: one edit, propagated everywhere. On hosts: one edit per host, by hand, and the real cost is not the tedium - it is that somebody will miss three of them, and those three will drift silently until an incident makes the inconsistency visible.

The item form, field by field

Name is free text and appears everywhere; write it for the person reading a problem list, not for you today.

Type is where it gets confusing, because there are many and each behaves differently. The decision is not really about Zabbix, it is about the target: a Linux or Windows box you can install software on means Zabbix agent; a network device means SNMP; a Java application means JMX; an HTTP API means HTTP agent. The question mark next to the field links straight to the item type reference for your version, and that is the right place to read the rest.

Key determines what is actually collected, and it is the field people guess at. Do not - click Select and browse the keys the agent already supports. Taking system.cpu.util as the example, the key accepts several parameters:

system.cpu.util[<cpu>,<type>,<mode>,<logical|physical>]

The useful trick: anything shown in angle brackets in the documentation is optional and can be deleted, brackets included if you drop them all. So system.cpu.util on its own is a complete, working key. People paste the full parameter list and then wonder which values to invent for fields they do not care about.

Update interval, and the urge to make it smaller

One minute is the default and it is right for most things. The temptation is to collect everything every few seconds because more data feels like better monitoring. It is not: it multiplies your write load, your disk, and your history table, and for almost every metric it changes nothing about when you notice a problem.

Custom intervals handle the cases where a flat interval is wrong - collecting only during business hours, or running an expensive check nightly.

Timeout

Three seconds by default. When checks time out, raising this is the obvious move and usually the wrong one: it hides the problem and ties up a poller for longer. The check being slow, or the network between server and agent being slow, is the actual fault, and it is worth fixing rather than accommodating.

History and trends

These two decide your database size, and they are the fields most worth understanding before you have a thousand hosts.

The pattern that works: keep history short enough to cover how far back you actually investigate - days to a few weeks - and trends long enough to answer capacity questions, often a year or more. Keeping a year of raw history "just in case" is the single most common reason a Zabbix database is larger than it needs to be, and the database size calculator will show you what it is costing.

Preprocessing

For when what arrives is not what you want to store - extract a field from JSON, convert units, discard unchanged values, compute a rate. It is a large topic and it is where a lot of the real power sits; the field is there when you need it.

Creating the item

Nine and a half minutes on the item form, the key selector, and reading the agent key documentation:

Watch the walkthrough

Four minutes on the import itself, including the version-mismatch fix.

Related