Check php-status

Overview

Checks PHP configuration and health, including startup errors, missing modules, and misconfigured php.ini directives. Optionally reads extended PHP information (Opcache statistics) from a monitoring helper script deployed in the web server context.

Apache httpd config example for the optional monitoring.php:

Alias /monitoring.php /dev/null
<Location /monitoring.php>
    Require local
    # if using php-fpm, two examples:
    #SetHandler "proxy:fcgi://127.0.0.1:9000/monitoring.php"
    #SetHandler "proxy:unix:/run/php-fpm/www.sock|fcgi://localhost/monitoring.php"
</Location>

On the subject of Opcache see also:

• Opcache Runtime Configuration

• A one-page opcache status page

• Fine-Tune Your Opcache Configuration to Avoid Caching Suprises.

Important Notes:

• The monitoring.php helper script is optional. Without it, the plugin still works but cannot report Opcache statistics.

• The --config parameter uses startswith matching against php --info output.

• The --module parameter uses startswith matching against php --modules output.

Data Collection:

• Executes php --version to detect startup errors

• Executes php --modules to verify expected modules are installed

• Executes php --info to verify php.ini configuration values

• Optionally fetches extended Opcache data from a monitoring.php helper script deployed in the web server document root

• Requires root or sudo to run the PHP CLI commands

Fact Sheet

Fact	Value
Check Plugin Download	https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/php-status
Nagios/Icinga Check Name	check_php_status
Check Interval Recommendation	Every minute
Can be called without parameters	Yes
Runs on	Cross-platform
Compiled for Windows	No
Requirements	PHP monitoring script monitoring.php (optional, callable via HTTP(S))

Help

usage: php-status [-h] [-V] [--always-ok] [-c CRIT] [--config CONFIG] [--dev]
                  [--module MODULES] [--insecure] [--no-proxy]
                  [--timeout TIMEOUT] [--url URL] [-w WARN]

Checks PHP configuration and health, including startup errors, missing
modules, and misconfigured php.ini directives. Optionally reads extended PHP
information from a monitoring helper script deployed in the web server
context. Alerts on startup errors, missing modules, or insecure settings.
Requires root or sudo.

options:
  -h, --help           show this help message and exit
  -V, --version        show program's version number and exit
  --always-ok          Always returns OK.
  -c, --critical CRIT  CRIT threshold for Opcache usage, in percent. Default:
                       >= None
  --config CONFIG      PHP ini "key=value" pair to check (startswith match).
                       Can be specified multiple times. Example: `--config
                       "memory_limit=128M"`
  --dev                Development mode. Tolerates `display_errors=On` and
                       `display_startup_errors=On`.
  --module MODULES     PHP module name to check (startswith match). Can be
                       specified multiple times. Example: `--module json
                       --module mbstring`
  --insecure           This option explicitly allows insecure SSL connections.
  --no-proxy           Do not use a proxy.
  --timeout TIMEOUT    Network timeout in seconds. Default: 8 (seconds)
  --url URL            URL to the optional PHP `monitoring.php` helper script.
                       Without it the plugin still works, but with reduced
                       accuracy. Default: http://localhost/monitoring.php
  -w, --warning WARN   WARN threshold for Opcache usage, in percent. Default:
                       >= 90

Usage Examples

./php-status --url http://localhost/monitoring.php --config date.timezone=Europe/Zurich --config memory_limit=256M --module mbstring --module GD

Output:

Everything is ok. PHP v8.3.26 (/etc/php.ini), Opcache Mem 59.2% used (75.8MiB/128.0MiB),
Wasted 0% (0.0B, max. 5.0%), Keys 78.4% used (6245/7963), Hit Rate 100.0% (13.5M hits, 3.3K misses),
Interned Strings 61.8% used (12.4MiB/20.0MiB, 130787 Strings), 0 OOM / 0 manual / 0 key restarts,
No startup errors were detected. No unexpected configurations detected. All expected modules were
found.

Key                             ! Value                            
--------------------------------+----------------------------------
date.timezone                   ! Europe/Zurich                    
default_socket_timeout          ! 10                               
display_errors                  ! Off                              
display_startup_errors          ! Off                              
error_reporting                 ! 22519                            
expose_php                      ! Off                              
max_execution_time              ! 3600                             
max_file_uploads                ! 100                              
max_input_time                  ! -1                               
memory_limit                    ! 1024M                            
post_max_size                   ! 16M                              
SMTP                            ! localhost                        
upload_max_filesize             ! 10000M                           
opcache.blacklist_filename      ! /etc/php-zts.d/opcache*.blacklist
opcache.enable                  ! True                             
opcache.enable_cli              ! True                             
opcache.huge_code_pages         ! False                            
opcache.interned_strings_buffer ! 20                               
opcache.max_accelerated_files   ! 7963                             
opcache.memory_consumption      ! 128.0MiB                         
opcache.revalidate_freq         ! 60                               
opcache.save_comments           ! True                             
opcache.validate_timestamps     ! True

States

• OK if no startup errors, all expected modules are found, configuration matches, and Opcache usage is below the thresholds.

• WARN on PHP startup errors.

• WARN if php.ini configuration does not match the given --config values.

• WARN if a required --module is missing.

• WARN if display_errors, display_startup_errors, or expose_php are enabled.

• WARN if Opcache is not installed or not enabled.

• WARN if Opcache restarts due to Out of Memory (OOM).

• WARN or CRIT if Opcache memory usage is above the given percentage thresholds (default: 90/None).

• WARN or CRIT if Opcache key usage is above the given percentage thresholds (default: 90/None).

• WARN or CRIT if Opcache interned string usage is above the given percentage thresholds (default: 90/None).

• --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name	Type	Description
php-config-errors	Number	0 = STATE_OK, 1 = STATE_WARN, 2 = STATE_CRIT
php-module-errors	Number	0 = STATE_OK, 1 = STATE_WARN, 2 = STATE_CRIT
php-opcache-interned_strings_usage-free_memory	Bytes	Free interned strings buffer memory.
php-opcache-interned_strings_usage-number_of_strings	Number	Number of interned strings.
php-opcache-interned_strings_usage-percentage	Percentage	Interned strings buffer usage, in percent.
php-opcache-interned_strings_usage-used_memory	Bytes	Used interned strings buffer memory.
php-opcache-memory_usage-current_wasted_percentage	Percentage	Current wasted memory, in percent.
php-opcache-memory_usage-free_memory	Bytes	Free Opcache memory.
php-opcache-memory_usage-percentage	Percentage	Opcache memory usage, in percent.
php-opcache-memory_usage-used_memory	Bytes	Used Opcache memory.
php-opcache-memory_usage-wasted_memory	Bytes	Wasted Opcache memory.
php-opcache-opcache_statistics-blacklist_miss_ratio	Percentage	Blacklist miss ratio.
php-opcache-opcache_statistics-blacklist_misses	Number	Blacklist misses.
php-opcache-opcache_statistics-hash_restarts	Number	Number of restarts because of hash overflow.
php-opcache-opcache_statistics-hits	Continuous Counter	Opcache hits.
php-opcache-opcache_statistics-manual_restarts	Number	Number of restarts scheduled by opcache_reset().
php-opcache-opcache_statistics-misses	Continuous Counter	Opcache misses.
php-opcache-opcache_statistics-num_cached_keys	Number	Number of cached keys.
php-opcache-opcache_statistics-num_cached_keys-percentage	Percentage	Cached keys usage, in percent.
php-opcache-opcache_statistics-num_cached_scripts	Number	Number of cached scripts.
php-opcache-opcache_statistics-num_free_keys	Number	Number of free keys.
php-opcache-opcache_statistics-oom_restarts	Number	Number of restarts because of out of memory.
php-opcache-opcache_statistics-opcache_hit_rate	Percentage	Opcache hit rate.
php-startup-errors	Number	0 = STATE_OK, 1 = STATE_WARN, 2 = STATE_CRIT

Troubleshooting

OpCache Mem used warning Increase opcache.memory_consumption, in megabytes. The minimum permissible value is 8, which is enforced if a smaller value is set.

Keys used warning Increase opcache.max_accelerated_files. The actual value used will be the first number in the set of prime numbers {223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793} that is greater than or equal to opcache.max_accelerated_files. The minimum value is 223. The maximum value is 1048793.

Hit Rate low Cache has to warm up, so wait and see.

Interned Strings used warning The OPcache interned strings buffer assures that repeating strings can be effectively cached. Increase opcache.interned_strings_buffer, in megabytes. The actual value is always lower than what is configured in opcache.interned_strings_buffer.

OOM restarts warning Increase any of the above values and restart Apache or PHP-FPM.

display_startup_errors - N/A Could happen while a PHP or Icinga update is running on your machine.

No entry for terminal type "unknown"; using dump terminal settings. Maybe you are using a too old PHP version.

PHP Warning: PHP Startup: Unable to load dynamic library ... Update this plugin.

Credits, License

• Authors: Linuxfabrik GmbH, Zurich

• License: The Unlicense, see LICENSE file.