Items

Common configuration parameters

Naming an item

Choose a simple, descriptive name for each item.

Prefix item names (metric) with object name (metric location):

<metric location>: <metric name>, for example:

• Interface eth0: Bits in
• Interface eth0: Bits out

You may use “#” if the metric location is just a number or index:

• #0: CPU utilization
• #1: CPU utilization

Consider adding suffixes like “per second”, “per hour” etc to describe the metric better.

Consider prefixing your item with “Get” if this a master item to highlight this item is the collector item, not the final metric.

Keys

Keys should use the hierarchical dotted format.

namespace:

Required to split metrics of one template from another. In the simplest case, this may be a short product name.

e.g: nginx, pgsql, pgbouncer, docker

component:

Component or sub-resource of the monitored object. It could be hierarchical as well.

e.g: upstream, pool, db, db.table, db.client

metric_name:

For example: max_reached.

If possible, prefer to name metrics just as they are named in the monitored object itself with an exception if metric format there is completely different or metric name there is totally confusing and not human-friendly.

Every key must start with a letter and must use only Latin letters in the lower case in the base part.

If you need a space, you could simply replace it with underscore “_”., e.g: response_time.

Remember that the max key length is 255 chars (including users params).

e.g: request_time. request_count

Consider appending .get for collectors, items that are responsible for retrieving data to be used in dependent items. (master items)

e.g: pgsql.db.get_connection [...], nginx.get_stub, nginx.get_logs

Consider using .rate for per second metrics.

e.g: nginx.connections.accepted.rate

Consider using .total for accumulators.

params:

In params, first comes mandatory params the optional should follow.

Item description field

Use this field to describe:

• Extended description of the item, for example, taken from vendor description of the metric
• Why it is important
• Provide a reference to the documentation if possible
• Any additional information about how this item collects data or how it can be tuned, configured

Units

Don't forget to provide units wherever possible.

Add your units to the blacklist to stop automatic conversion where conversion is silly.

For example:

Use “!requests/s” to prevent “Krequests/s” to appear.

Use preprocessing to transform GB, MB, KB to B (Bytes).

Use preprocessing to transform ms, minutes, hours to seconds.

Value mapping

Always use value mappings where applicable, for example, when collecting discrete states.

Type of information

Type of information determines the type of data as stored in the database after performing conversions. Available types:

• Numeric (unsigned) - 64-bit unsigned integer
• Numeric (float) - floating-point number, negative values can be stored. Allowed range: -999999999999.9999 to 999999999999.9999. Starting with Zabbix 2.2, receiving values in scientific notation (1e+7, 1e-4, etc.) is also supported.
• Character – short text data
• Log – long text data with optional log related properties (timestamp, source, severity, logeventid)
• Text – long text data.

See Item configuration for more info.

If your item is a rate (i.e., “Change per second” preprocessing is applied) – use Numeric(float).

Additionally, don’t forget to use Numeric(float) if you need to store negative integers.

Update interval, history and trend storage periods

By default, use:

Update interval: 1m History: 7d Trends: 365d

Also, consider using preprocessing steps 'Discard unchanged (with heartbeat)' when collecting items that change rarely such as statuses or configuration data (e.g. serial numbers or hostname):

If the item is a health check:

1m with the heartbeat of 1h

If the item is an inventory item:

15m with the heartbeat of 24h

If the item has a tag “data: raw” (master items or items only needed for other calculated items, see below) - set history to 0 and trends to 0, as you don't need to keep such intermediate values.

Please note: never set update interval to more than 1d, as you will not see such data in the "Latest data" since Zabbix frontend considers values received more than 24h ago as not latest.

Tags

Use tags to logically group items using the recommended tagging model.

Please note that this model might become enforced in the future Zabbix releases. In this case, templates that do not follow specified rules will need to be updated.

Item tags

For example, the item Total swap space should contain the following tags:

component: memory; component: storage

Specific item types

Calculated items

Use newlines and spaces to make long formulas human-readable.

SNMP

SNMP OID field should not use any MIB objects, so templates would be working without MIBs imported. At the same time, provide metric name from MIB as an item key parameter and in the item description.

Leading '.' in OID should not be used.

Leave item field ‘Port’ empty for SNMP items. If left empty, then the port will be used from the SNMP host interface.

Best practices

Minimize external libraries dependencies when writing external scripts/modules if possible

If you need to resort to external scripts – think about making them portable and easy to install as well.

Preprocessing

Prefer to use Zabbix preprocessing in favor of complex data parsing with some scripts on the agent side:

• To keep Zabbix agent presence noticeable as less as possible
• To keep preprocessing rules clearly observable by all future template users
• To keep preprocessing rules as a part of the monitoring solution – easily transferable as part of the template
• To avoid maintaining two sets of preprocessing rules on Windows and Linux platforms

Master item + dependent items/preprocessing

Prefer to use Zabbix master item + dependent items in favor of multiple separate calls:

• To keep Zabbix presence noticeable as less as possible - fewer calls to the monitored objects

Reuse master item contents to create Low-level discovery rules. Then reuse master item values again to be used in future items from prototypes.

Master item history storage period

Master items values may be of a very large size (ZBXNEXT-223), while these values are only needed for preprocessing in dependent items. So, shrink its history storage period to a minimum, non-zero value which is 1h.

But what if we set history = 0? This setting will give you some additional issues:

• master item’s nodata() trigger will give you false positives
• less info available for troubleshooting data collection

So we suggest 1h as a safer choice at this point.