Testing and Troubleshooting

If you have any problem with the template, please read this section first. If you don't find your problem here, please check the open issues - may be it's already reported and the work is in progress to fix it. Otherwise open a new issue there.

1. Template import failure on Zabbix server

To view the import errors, please click the "Details" section in the Zabbix GUI. It should be on the same import page near the error message:

Then check the Zabbix server log, for Debian/Ubuntu it's located at /var/log/zabbix/zabbix_server.log.

Most common errors:

• Prototype "X" contains item prototypes from multiple discovery rules. This problem means that you have a conflict of names: this template you are trying to import uses names of discovery rules, items, etc. that are already defined in your Zabbix server in some existing template. Usually it happens when you tried different PHP-FPM templates from different vendors, so they may use the same naming conventions. You should remove (using Delete and Clear button) the conflicting template prior to importing this one. Note: using Delete button instead of Delete and Clear does not completely remove all data associated with the template, as a result it does not solve the conflict. Please use Delete and Clear button only.

2. The template does not work

If the template imported successfully and you assigned it to your host, but do not see the data (it's partially or completely missing) from this template in Zabbix, then please follow the steps below to find the cause of the problem and the related solution.

2.1. Check auto discovery

This step checks that the script to discover PHP-FPM pools works on your machine. Run the following command (replace POOL_PATH with the status path of PHP-FPM that you set in pm.status_path in the installation step, the default value is /php-fpm-status) on your monitored host:

root@server:/etc/zabbix#bash /etc/zabbix/zabbix_php_fpm_discovery.sh POOL_PATH

Important: please make sure that you use bash in the command above, not sh or other alternatives, otherwise you may get a script syntax error message.

The output should be a valid JSON with a list of pools and their sockets, something like below (you may want to use online JSON tool for pretty formatting of the response):

{
   "data":[
      {
         "{#POOLNAME}":"web1",
         "{#POOLSOCKET}":"/var/lib/php7.3-fpm/web1.sock"
      },
      {
         "{#POOLNAME}":"web4",
         "{#POOLSOCKET}":"/var/lib/php7.3-fpm/web4.sock"
      },
      {
         "{#POOLNAME}":"www",
         "{#POOLSOCKET}":"127.0.0.1:9000"
      }
   ]
}

For further investigation you can run the script above with debug option to get more details, example:

root@server:/etc/zabbix#bash /etc/zabbix/zabbix_php_fpm_discovery.sh POOL_PATH debug
Debug mode enabled
Success: found socket /var/lib/php7.3-fpm/web1.sock for pool web1, raw process info: php-fpm7. 5094 web1 11u unix 0x00000000dd9ea858 0t0 104495372 /var/lib/php7.3-fpm/web1.sock type=STREAM
Success: found socket /var/lib/php7.3-fpm/web4.sock for pool web4, raw process info: php-fpm7. 5096 web4 11u unix 0x00000000562748dd 0t0 104495374 /var/lib/php7.3-fpm/web4.sock type=STREAM
Success: found socket /run/php/php7.3-fpm.sock for pool www, raw process info: php-fpm7. 5098 www-data 11u unix 0x00000000ef5ef2fb 0t0 104495376 /run/php/php7.3-fpm.sock type=STREAM
Resulting JSON data for Zabbix:
{"data":[{"{#POOLNAME}":"web1","{#POOLSOCKET}":"/var/lib/php7.3-fpm/web1.sock"},{"{#POOLNAME}":"web4","{#POOLSOCKET}":"/var/lib/php7.3-fpm/web4.sock"},{"{#POOLNAME}":"www","{#POOLSOCKET}":"/run/php/php7.3-fpm.sock"}]}

Any warning or error messages will be displayed here.

Note: having a warning messages when debug mode is enabled does not necessarily mean that you have a error here, because different OS may provide data about processes differently. So, if you don't see any error messages here, then the script works fine.

The script can show you the list of utilities that are missing on your system and must be installed. We require the following utilities to be installed:

• awk
• ps
• grep
• sort
• head
• lsof
• jq
• dirname
• printf
• whoami

If some pools are missing, then you can manually check that they do really exist and are running, for example, using command:

ps aux | grep "php-fpm"

In the list you should see your pool. If it's not there, then it means it's not running (not functional).

2.2. Test with zabbix_get

If auto discovery script works correctly, but Zabbix server still does not recieve data from Zabbix agent, then this step will help to test the connection between the Zabbix server and the Zabbix agent. Please, use the zabbix_get utility from your Zabbix Server to test that you can get the data from the Zabbix Agent (host).

Installation

Please, install this utility first, because usually it's not installed automatically:

apt-get install zabbix-get

Command examples

In the examples below we use the following parameter names:

• ZABBIX_HOST_IP is the IP address of the host where the Zabbix Agent is installed and where the PHP-FPM is running, for example 127.0.0.1
• ZABBIX_HOST_PORT is the port of the Zabbix Agent, for example 10050
• POOL_URL is the socket of the pool or IP and port combination, example: /var/lib/php7.3-fpm/web1.sock or 127.0.0.1:9000
• POOL_PATH is the status path of PHP-FPM that you set in pm.status_path, the default value is /php-fpm-status.

All commands should return valid JSON data. If any error happens then it will be displayed.

1) Discover PHP-FPM pools

Command syntax:

zabbix_get -s ZABBIX_HOST_IP -p ZABBIX_HOST_PORT -k php-fpm.discover["POOL_URL"]

Command output example:

root@server:/# zabbix_get -s 127.0.0.1 -p 10050 -k php-fpm.discover["/php-fpm-status"]
{"data":[{"{#POOLNAME}":"www","{#POOLSOCKET}":"/run/php/php7.3-fpm.sock"},{"{#POOLNAME}":"www2","{#POOLSOCKET}":"localhost:9001"}]}

Most common problems of testing the php-fpm.discover key:

• The resulting JSON data is empty, but the discovery script started manually works. Then it's a problem of insufficient privileges of Zabbix agent. Please, check again section "Root privileges" of the installation manual.
• Error ZBX_NOTSUPPORTED: Unsupported item key. It means the userparameter_php_fpm.conf file is ignored by the Zabbix agent. Please, make sure that you copied this file to correct location and you have restarted the Zabbix agent.
• Error php_fpm.cache: Permission denied means that the script has insufficient permissions. Please, check that you granted privileges to the PHP-FPM auto discovery script or run Zabbix agent as root user. Please, check again section "Root privileges" of the installation manual.
• Message Error: write permission is not granted to user USER for cache file php_fpm.cache means that the user of Zabbix agent does not have required privileges. Please, check that you granted privileges to the PHP-FPM auto discovery script or run Zabbix agent as root user. Please, check again section "Root privileges" of the installation manual. You may need to manually delete the php_fpm.cache after granting the privileges.

2) Get status of required pool

Command syntax:

zabbix_get -s ZABBIX_HOST_IP -p ZABBIX_HOST_PORT -k php-fpm.discover.status["POOL_URL","POOL_PATH"]

Command output example:

root@server:/# zabbix_get -s 127.0.0.1 -p 10050 -k php-fpm.status["localhost:9001","/php-fpm-status"]
{"pool":"www2","process manager":"static","start time":1578093850,"start since":149,"accepted conn":3,"listen queue":0,"max listen queue":0,"listen queue len":511,"idle processes":4,"active processes":1,"total processes":5,"max active processes":1,"max children reached":0,"slow requests":0}

3. Other issues

3.1. Multiple items in Zabbix "Latest data" section

If you open the "Latest data" section in Zabbix, then you may notice that items of this template are displayed twice: grouped as members of the PHP-FPM app, and grouped by discovered pools. This is not a bug: that's the way Zabbix groups and displays data by default. Filtering helps to show only the data you need (without duplicates), use the Select button:

Select the desired pools in the popup dialog: