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 - perhaps 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:

user@server:~$ sudo -u zabbix sudo /etc/zabbix/zabbix_php_fpm_discovery.sh POOL_PATH

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

Note: we use sudo two times here. First sudo is used to run the command as zabbix user, second sudo is used to run the script with root privileges. This approach provides maximum simulation how zabbix agent runs it. You may also test the script directly without running it as zabbix user:

user@server:~$ sudo bash /etc/zabbix/zabbix_php_fpm_discovery.sh POOL_PATH

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:

user@server:~$ sudo -u zabbix sudo /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: seeing a warning message when debug mode is enabled does not necessarily mean you have an 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 they do really exist and are running, for example, using command:

user@server:~$ sudo ps aux | grep "php-fpm"
root     17953  0.0  0.5 260052 41428 ?        Ss   09:23   0:00 php-fpm: master process (/etc/php/7.3/fpm/php-fpm.conf)
web1     17954  0.0  0.1 259900 10672 ?        S    09:23   0:00 php-fpm: pool web1
web1     17955  0.0  0.1 259900 10672 ?        S    09:23   0:00 php-fpm: pool web1
web11    17956  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web11
web11    17957  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web11
web14    17958  0.0  0.1 259900 10672 ?        S    09:23   0:00 php-fpm: pool web14
web14    17959  0.0  0.1 259900 10672 ?        S    09:23   0:00 php-fpm: pool web14
web16    17960  0.2  0.5 267520 46436 ?        S    09:23   0:02 php-fpm: pool web16
web16    17961  0.1  0.5 267516 45896 ?        S    09:23   0:01 php-fpm: pool web16
web17    17962  0.5  0.5 265136 40984 ?        S    09:23   0:05 php-fpm: pool web17
web17    17963  0.5  0.5 265216 40832 ?        S    09:23   0:04 php-fpm: pool web17
web18    17964  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web18
web18    17965  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web18
web2     17966  0.0  0.1 259900 10672 ?        S    09:23   0:00 php-fpm: pool web2
web2     17967  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web2
web21    17968  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web21
web21    17969  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web21
web22    17970  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web22
web22    17971  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web22
web3     17972  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web3
web3     17973  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web3
web4     17974  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web4
web4     17975  0.0  0.1 259900 12400 ?        S    09:23   0:00 php-fpm: pool web4
web5     17976  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web5
web5     17977  0.0  0.1 259900 12396 ?        S    09:23   0:00 php-fpm: pool web5
web6     17978  1.7  0.8 350240 68892 ?        S    09:23   0:17 php-fpm: pool web6
web6     17979  1.4  0.7 345780 64620 ?        S    09:23   0:13 php-fpm: pool web6
www-data 17980  0.0  0.1 259896 10676 ?        S    09:23   0:00 php-fpm: pool www
www-data 17981  0.0  0.1 259896 10676 ?        S    09:23   0:00 php-fpm: pool www
web6     18036  1.3  0.6 273096 54488 ?        S    09:23   0:12 php-fpm: pool web6

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 receive 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:

For apt-get based environments (Debian, Ubuntu, etc.):

user@server:~$ sudo apt-get install zabbix-get

For yum based environments (CentOS):

user@server:~$ sudo yum 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:

user@server:~$ zabbix_get -s ZABBIX_HOST_IP -p ZABBIX_HOST_PORT -k php-fpm.discover["POOL_URL"]

Command output example:

user@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 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 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 cannot create temp file for here-document: Permission denied means that the script has insufficient permissions. Please, check 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 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.
• Message /usr/bin/sudo: Permission denied. Make sure you correctly configured the root privileges for Zabbix using the visudo. Please, check again section "Root privileges" of the installation manual. Another reason can be that you have SELinux enabled that does not allow to execute the sudo command. You can disable SELinux with command setenforce 0.

2) Get status of required pool

Command syntax:

user@server:~$ zabbix_get -s ZABBIX_HOST_IP -p ZABBIX_HOST_PORT -k php-fpm.status["POOL_URL","POOL_PATH"]

Command output example:

user@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}

2.3. Check file encoding

This problem may happen when you download the files in Windows, edit them and then upload them to your Linux server. In this case the scripts may have line endings in Windows style, but Linux style are required. You may use dos2unix utility to change the line endings on the Linux server, for example:

user@server:~$ sudo apt-get install dos2unix -y
user@server:~$ sudo dos2unix /etc/zabbix/zabbix_php_fpm_discovery.sh
dos2unix: converting file /etc/zabbix/zabbix_php_fpm_discovery.sh to Unix format...
user@server:~$ sudo dos2unix /etc/zabbix/zabbix_php_fpm_status.sh
dos2unix: converting file /etc/zabbix/zabbix_php_fpm_status.sh to Unix format...

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: