19 Items

An item is a single performance or availability check (metric).

1 Item key

1.1 Flexible and non-flexible parameters

A flexible parameter is a parameter which accepts an argument. For example, vfs.fs.size[*] is a flexible parameter. '*' is any string that will be passed as an argument to the parameter. Correct definition examples:

• vfs.fs.size[/]
• vfs.fs.size[/opt]

1.2 Key format

Item key format, including key parameters, must follow syntax rules. The following illustrations depict supported syntax. Allowed elements and characters at each point can be determined by following the arrows - if some block can be reached through the line, it is allowed, if not - it is not allowed.

Item key

To construct a valid item key, one starts with specifying the key name, then there's a choice to either have parameters or not - as depicted by the two lines that could be followed.

Key name

The key name itself has a limited range of allowed characters, which just follow each other. Allowed characters are:

0-9a-zA-Z_-.

Which means:

• all numbers;
• all lowercase letters;
• all uppercase letters;
• underscore;
• dash;
• dot.

Key parameters

An item key can have multiple parameters that are comma separated.

Individual key parameter

Each key parameter can be either a quoted string, an unquoted string or an array.

The parameter can also be left empty, thus using the default value. In that case, the appropriate number of commas must be added if any further parameters are specified. For example, item key icmpping[,,200,,500] would specify that the interval between individual pings is 200 milliseconds, timeout - 500 milliseconds, and all other parameters are left at their defaults.

Parameter - quoted string

If the key parameter is a quoted string, any Unicode character is allowed, and included double quotes must be backslash escaped.

Parameter - unquoted string

If the key parameter is an unquoted string, any Unicode character is allowed except comma and right square bracket (]).

Parameter - array

If the key parameter is an array, it is again enclosed in square brackets, where individual parameters come following multiple parameters specifying rules and syntax.

1.3 Available encodings

The parameter "encoding" is used to specify encoding for processing corresponding item checks, so that data acquired will not be corrupted. For a list of supported encodings (code page identifiers), please consult respective documentation, such as documentation for libiconv (GNU Project) or Microsoft Windows SDK documentation for "Code Page Identifiers". If an empty "encoding" parameter is passed, then ANSI with system specific extension (Windows) or UTF-8 (default locale for newer Unix/Linux distributions, see your system's settings) is used by default.

2 Unsupported items

An item can become unsupported if its value can not be retrieved for some reason. Such items are still rechecked at a fixed interval, configurable in Administration section.

3 Supported by Platform

[1] These values for these items are not supported for loopback interfaces on Solaris systems prior to Solaris 10 6/06 as byte, error and utilisation statistics are not stored and/or reported by the kernel. However, if you're monitoring a Solaris system via net-snmp, values may be returned as net-snmp carries legacy code from the cmu-snmp dated as old as 1997 that, upon failing to read byte values from the interface statistics returns the packet counter (which does exist on loopback interfaces) multiplied by an arbitrary value of 308. This makes the assumption that the average length of a packet is 308 octets, which is a very rough estimation as the MTU limit on Solaris systems for loopback interfaces is 8892 bytes.

These values should not be assumed to be correct or even closely accurate. They are guestimates. The Zabbix agent does not do any guess work, but net-snmp will return a value for these fields.

4 Zabbix Agent

List of supported parameters

See this section for the difference of an item being performed as a passive or an active check.

5 Windows-specific parameters

This section contains descriptions of parameters supported by Zabbix Windows agent only.

6 SNMP Agent

Zabbix must be configured with SNMP support in order to be able to retrieve data provided by SNMP agents.

The following steps have to be performed in order to add monitoring of SNMP parameters:

Step 1

Create a host for the SNMP device.

Enter an IP address. Set the host Status to NOT MONITORED. You can use one of the SNMP templates (Template_SNMPv1_Device, Template_SNMPv2_Device), which will automatically add the set of items. However, the template may not be compatible with the host.

Step 2

Find out the SNMP string of the item you want to monitor.

After creating the host, use 'snmpwalk' (part of ucd-snmp/net-snmp software which you should have installed as part of the Zabbix installation) or equivalent tool:

shell> snmpwalk <host or host IP> public

This will give you a list of SNMP strings and their last value. If it doesn't then it is possible that the SNMP 'community' is different from the standard public in which case you will need to find out what it is. You would then go through the list until you find the string you want to monitor, e.g. you wanted to monitor the bytes coming in to your switch on port 3 you would use:

interfaces.ifTable.ifEntry.ifOctetsIn.3 = Counter 32: 614794138

You should now use the snmpget command to find the OID for interfaces.ifTable.ifEntry.ifInOctets.3:

shell> snmpget -On 10.62.1.22 interfaces.ifTable.ifEntry.ifOctetsIn.3

where the last number in the string is the port number you are looking to monitor. This should give you something like the following:

.1.3.6.1.2.1.2.2.1.10.3 = Counter32: 614794138

again the last number in the OID is the port number.

3COM seem to use port numbers in the hundreds, e.g. port 1 = port 101, port 3 = port 103, but Cisco use regular numbers, e.g. port 3 = 3.

Step 3

Create an item for monitoring.

So, now go back to Zabbix and click on Items, selecting the SNMP host you created earlier. Depending on whether you used a template or not when creating your host, you will have either a list of SNMP items associated with your host or just a new item box. We will work on the assumption that you are going to create the item yourself using the information you have just gathered using snmpwalk and snmpget, so enter a plain English description in the 'Description' field of the new item box. Make sure the 'Host' field has your switch/router in it and change the 'Type' field to "SNMPv* agent". Enter the community (usually public) and enter the numeric OID that you retrieved earlier in to the 'SNMP OID' field, i.e. .1.3.6.1.2.1.2.2.1.10.3

Enter the 'SNMP port' as 161 and the 'Key' as something meaningful, e.g. SNMP-InOctets-Bps. Choose a Multiplier if you want one and enter an 'update interval' and 'keep history' if you want it to be different from the default. Set the 'Status' to Monitored, the 'Type of information' to Numeric (float) and the 'Store value' to DELTA (important otherwise you will get cumulative values from the SNMP device instead of the latest change).

Now save the item and go back to the hosts area of Zabbix. From here check that the SNMP device Status shows 'Monitored' and check in Latest data for your SNMP data!

Example 1

General example

Note that OID can be given in either numeric or string form. However, in some cases, string OID must be converted to numeric representation. Utility snmpget may be used for this purpose:

shell> snmpget -On localhost public enterprises.ucdavis.memory.memTotalSwap.0

Monitoring of SNMP parameters is possible if either --with-net-snmp or --with-ucd-snmp flag was specified while configuring Zabbix sources.

Example 2

Monitoring of Uptime

7 Simple checks

Simple checks are normally used for agent-less monitoring or for remote checks of services. Note that Zabbix agent is not needed for simple checks. Zabbix server is responsible for processing of simple checks (making external connections, etc).

All simple checks, except tcp and tcp_perf, accept one optional parameter:

• port - port number. If missing, standard default service port is used.

Examples of using simple checks:

ftp,155
       http
       http_perf,8080 

List of supported simple checks:

Timeout processing

Zabbix will not process a simple check longer than Timeout seconds defined in Zabbix server configuration file.

ICMP pings

Zabbix uses external utility fping for processing of ICMP pings. The utility is not part of Zabbix distribution and has to be additionally installed. If the utility is missing, has wrong permissions or its location does not match FpingLocation defined in configuration file, ICMP pings (icmpping, icmppingsec and icmppingloss) will not be processed.

fping must be executable by user Zabbix daemons run as and setuid root. Run these commands as user root in order to setup correct permissions:

shell> chown root:zabbix /usr/sbin/fping
       shell> chmod 4710 /usr/sbin/fping

After performing the two commands above check ownership of the fping executable. In some cases the ownership can be reset by executing the chmod command.

The default values for ICMP checks parameters:

Zabbix writes addresses to be checked to a temporary file, which is then passed to fping. If items have different parameters, only ones with identical parameters are written to a single file.

8 Internal checks

Internal checks allow monitoring of the internals of Zabbix. Internal checks are calculated by Zabbix server.

9 Aggregated checks

Aggregate checks do not require any agent running on a host being monitored. Zabbix server collects aggregate information by doing direct database queries.

Syntax of an aggregate item's key

groupfunc["Host group","Item key",itemfunc,parameter]

Multiple host groups may be used since Zabbix 1.8.2 by inserting a comma-delimited array.

Supported group functions:

Supported item functions:

Examples of keys for aggregate items:

Example 1

Total disk space of host group 'MySQL Servers'.

grpsum["MySQL Servers","vfs.fs.size[/,total]",last,0]

Example 2

Average processor load of host group 'MySQL Servers'.

grpavg["MySQL Servers","system.cpu.load[,avg1]",last,0]

Example 3

Average (5min) number of queries per second for host group 'MySQL Servers'

grpavg["MySQL Servers",mysql.qps,avg,300]

Example 4

Average CPU load on all hosts in multiple host groups.

grpavg[["Servers A","Servers B","Servers C"],system.cpu.load,last,0]

10 External checks

External check is a check executed by Zabbix Server by running a shell script or a binary.

External checks do not require any agent running on a host being monitored.

Syntax of item's key:

script[parameters]
       * script – name of the script.
       * parameters – list of command line parameters. Parameters will be used in command line without any changes.

If you don't want to pass your parameters to the script you may use:

script[] or
       script   <- this simplified syntax is supported starting from Zabbix 1.8.1

Zabbix server will find and execute the command in the directory defined in configuration parameter ExternalScripts in zabbix_server.conf. The command will be executed as the user Zabbix server runs as, so any access permissions or environment variables should be handled in a wrapper script, if necessary, and permissions on the command should allow that user to execute it. Only commands in the specified directory are available.

First command line parameter is host IP address or DNS name, other parameters are substituted by parameters.

Zabbix uses the first line (trimmed from trailing whitespace) in the standard output of the script as the value. The following lines, standard error and the exit code are discarded.

Example 1

Execute script check_oracle.sh with parameters "-h 192.168.1.4". Host DNS name 'www1.company.com'.

check_oracle.sh[-h 192.168.1.4]

Zabbix will execute:

check_oracle.sh www1.company.com -h 192.168.1.4.

11 SSH checks

Zabbix must be configured with SSH2 support. ::: noteimportant The minimal supported libssh2 library version is 1.0.0. :::

SSH checks are used for agent-less monitoring. Note that Zabbix agent is not needed for SSH checks.

Actual commands to be executed must be placed in the Executed script field in the item configuration. Multiple commands can be executed one after another by placing them on a new line.

12 Telnet checks

Telnet checks are used for agent-less monitoring. Zabbix agent is not needed for Telnet checks.

Actual commands to be executed must be placed in the Executed script field in the item configuration. Multiple commands can be executed one after another by placing them on a new line.

Till version 1.8.1, supported characters that the prompt can end with:

• $
• #

Zabbix version 1.8.2 adds support for additional character:

• %

13 Calculated items

With calculated items you can create calculations on the basis of other items. Thus, calculated items are a way of creating virtual data sources. Item values will be periodically calculated based on an arithmetical expression.

Resulting data will be stored in the Zabbix database as for any other item - this means storing both history and trends values for fast graph generation. Calculated items may be used in trigger expressions, referenced by macros or other entities same as any other item type.

To use calculated items, choose the item type Calculated. The key is a unique item identifier (per host). You can create any key name using supported symbols. Calculation definition should be entered in the Formula field (named Expression in 1.8.1 and 1.8.2). There is virtually no connection between the formula and key. The key parameters are not used in formula in any way - variables may be passed to the formula with user macros.

The correct syntax of a simple formula is:

func(<key>|<hostname:key>,<parameter1>,<parameter2>,...)

Where:

A more complex formula may use a combination of functions, operators and brackets. You could use all functions and operators supported in trigger expressions. Note that syntax is slightly different, however logic and operator precedence are exactly the same.

Supported characters for a hostname:

a..zA..Z0..9 ._-

Supported characters for a key:

a..zA..Z0..9.,_

Supported characters for a function:

a..zA..Z0..9_

Unlike trigger expressions, Zabbix processes calculated items according to item update interval, not upon receiving a new value.

A calculated item may become unsupported in several cases:

1. referenced item(s) not found
2. no data to calculate a function
3. division by zero
4. incorrect syntax used

Example 1

Calculate percentage of free disk space on '/'.

Use of function last:

100*last("vfs.fs.size[/,free]")/last("vfs.fs.size[/,total]")

Zabbix will take the latest values for free and total disk spaces and calculate percentage according to the given formula.

Example 2

Calculate 10 minute average number of values processed by Zabbix.

Use of function avg:

avg("Zabbix Server:zabbix[wcache,values]",600)

Note that extensive use of calculated items with long time periods may affect performance of the Zabbix Server.

Example 3

Calculate total bandwidth on eth0.

Sum of two functions:

last("net.if.in[eth0,bytes]")+last("net.if.out[eth0,bytes]")

Example 4

Calculate percentage of incoming traffic.

More complex expression:

100*last("net.if.in[eth0,bytes]")/(last("net.if.in[eth0,bytes]")+last("net.if.out[eth0,bytes]"))

Example 5

Calculate count of records in a log file for last 10 minutes.

Take note of how double quotes are escaped within the quoted key and first function parameter is required:

count("logrt[\"/tmp/test.log\",\"some words pattern\"]",600)

Example 6

Using aggregated items correctly within a calculated item.

Take note of how double quotes are escaped within the quoted key:

last("grpsum[\"video\",\"net.if.out[eth0,bytes]\",\"last\",\"0\"]") / last("grpsum[\"video\",\"nginx_stat.sh[active]\",\"last\",\"0\"]")