Extending Zabbix agents

This section provides step-by-step instructions for extending the functionality of a Zabbix agent using a user parameter.

The example below retrieves the number of statements executed by a MySQL server. The steps apply to both Zabbix agent and Zabbix agent 2.

Step 1: Prepare access to MySQL

The agent runs as the zabbix operating system user. Do not use the MySQL root account, as it may use socket-based authentication, which can prevent the agent from connecting. Instead, create a dedicated MySQL user:

CREATE USER 'zbx_monitor'@'localhost' IDENTIFIED BY '<password>';

Store the credentials in a file readable only by the zabbix user, for example /etc/zabbix/mysql_monitor.cnf (the path depends on the operating system and Zabbix installation method):

[client]
user=zbx_monitor
password=<strong password>

Set the file's ownership and permissions:

sudo chown zabbix:zabbix /etc/zabbix/mysql_monitor.cnf
sudo chmod 600 /etc/zabbix/mysql_monitor.cnf

Pass this file explicitly with --defaults-extra-file (which must be the first option passed to the MySQL client) rather than relying on ~/.my.cnf, because the daemon's HOME environment variable may be unset or different from what you expect. If MySQL uses a non-default socket path, add a socket= line to the same file.

Step 2: Write a command

Write a custom script or command to retrieve the required parameter, and make sure it works under the same conditions as the agent daemon.

The following command returns the number of statements executed by the MySQL server:

/usr/bin/mysql --defaults-extra-file=/etc/zabbix/mysql_monitor.cnf -N -B -e "SHOW GLOBAL STATUS LIKE 'Questions'" | /usr/bin/awk '{print $2}'

You can test the command as the zabbix user; it should print a single number:

sudo -u zabbix sh -c "/usr/bin/mysql --defaults-extra-file=/etc/zabbix/mysql_monitor.cnf -N -B -e \"SHOW GLOBAL STATUS LIKE 'Questions'\" | /usr/bin/awk '{print \$2}'"

Step 3: Add the command to the Zabbix agent configuration

Rather than editing the main agent configuration file (zabbix_agentd.conf or zabbix_agent2.conf), create a separate file in the directory included by the Include parameter. Separate files are easier to manage and are less likely to be affected by package upgrades.

For example, create /etc/zabbix/zabbix_agentd.d/mysql.conf (/etc/zabbix/zabbix_agent2.d/mysql.conf for Zabbix agent 2) with the following content:

UserParameter=mysql.questions,/usr/bin/mysql --defaults-extra-file=/etc/zabbix/mysql_monitor.cnf -N -B -e "SHOW GLOBAL STATUS LIKE 'Questions'" | /usr/bin/awk '{print $2}'

mysql.questions is the unique item key. It must be unique within the agent configuration.

You can test the parameter by running the Zabbix agent with -t flag. Run the test as the zabbix user, and specify the configuration file if it is not in the default location:

For Zabbix agent:

sudo -u zabbix zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf -t mysql.questions

For Zabbix agent 2:

sudo -u zabbix zabbix_agent2 -c /etc/zabbix/zabbix_agent2.conf -t mysql.questions

The expected output contains a number, for example:

mysql.questions                               [t|4567]

Step 4: Reload and test the user parameter

Reload user parameters from the configuration file by running the following command:

For Zabbix agent:

sudo zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf -R userparameter_reload

For Zabbix agent 2:

sudo zabbix_agent2 -c /etc/zabbix/zabbix_agent2.conf -R userparameter_reload

Run the command as root or as the operating system user running the agent.

Alternatively, restart the agent to apply the configuration changes.

You can test the parameter against the running agent by using the zabbix_get utility, for example, from the Zabbix server:

zabbix_get -s <IP address> -k mysql.questions

Here, <IP address> is the IP address of the host running the agent that zabbix_get connects to. The IP address of the host running zabbix_get must be listed in the agent's Server parameter.

For this test to work, the agent must accept passive checks (for the Zabbix agent, StartAgents must not be set to 0). If the agent is configured for active checks only, skip this test and verify the item in Monitoring > Latest data after completing the final step.

Step 5: Create an item

Create a new item on the monitored host with the mysql.questions item key.

Select the item type: either Zabbix Agent or Zabbix Agent (active).

For Zabbix agent (passive), the Zabbix server or proxy address must be listed in the agent's Server parameter. For Zabbix agent (active), the ServerActive parameter must specify the Zabbix server or proxy, and the agent's Hostname parameter must match the host name configured in the frontend exactly.

Select the item's Type of information. The agent always returns the value as text; Type of information defines how Zabbix interprets and stores the value after any preprocessing steps.

For the raw cumulative counter, select Numeric (unsigned). To measure the number of statements per second, select Numeric (float) and add the Change per second preprocessing step.