PHP FPM
Datadog's Research Report: The State of Serverless Report: The State of Serverless

PHP FPM

Agent Check Agent Check

Supported OS: Linux Mac OS Windows

PHP overview

Overview

The PHP-FPM check monitors the state of your FPM pool and tracks request performance.

Setup

Installation

The PHP-FPM check is included in the Datadog Agent package, so you don’t need to install anything else on your servers that use PHP-FPM.

Configuration

Follow the instructions below to configure this check for an Agent running on a host. For containerized environments, see the Containerized section.

Host

  1. Edit the php_fpm.d/conf.yaml file, in the conf.d/ folder at the root of your Agent’s configuration directory. See the sample php_fpm.d/conf.yaml for all available configuration options:

    init_config:
    
    instances:
     ## @param status_url - string - required
     ## Get metrics from your FPM pool with this URL
     ## The status URLs should follow the options from your FPM pool
     ## See http://php.net/manual/en/install.fpm.configuration.php
     ##   * pm.status_path
     ## You should configure your fastcgi passthru (nginx/apache) to catch these URLs and
     ## redirect them through the FPM pool target you want to monitor (FPM `listen`
     ## directive in the config, usually a UNIX socket or TCP socket.
     #
     - status_url: http://localhost/status
    
       ## @param ping_url - string - required
       ## Get a reliable service check of your FPM pool with `ping_url` parameter
       ## The ping URLs should follow the options from your FPM pool
       ## See http://php.net/manual/en/install.fpm.configuration.php
       ##   * ping.path
       ## You should configure your fastcgi passthru (nginx/apache) to
       ## catch these URLs and redirect them through the FPM pool target
       ## you want to monitor (FPM `listen` directive in the config, usually
       ## a UNIX socket or TCP socket.
       #
       ping_url: http://localhost/ping
    
       ## @param use_fastcgi - boolean - required - default: false
       ## Communicate directly with PHP-FPM using FastCGI
       #
       use_fastcgi: false
    
       ## @param ping_reply - string - required
       ## Set the expected reply to the ping.
       #
       ping_reply: pong
  2. Restart the Agent.

Containerized

For containerized environments, see the Autodiscovery Integration Templates for guidance on applying the parameters below.

ParameterValue
<INTEGRATION_NAME>php_fpm
<INIT_CONFIG>blank or {}
<INSTANCE_CONFIG>{"status_url":"http://%%host%%/status", "ping_url":"http://%%host%%/ping", "use_fastcgi": false, "ping_reply": "pong"}

Extras

Multiple pools

It is possible to monitor multiple PHP-FPM pools using the same proxy server, a common scenario when running on Kubernetes. To do so, modify your server’s routes to point to different PHP-FPM instances. Here is an example NGINX configuration:

server {
    ...

    location ~ ^/(status1|ping1)$ {
        access_log off;
        fastcgi_pass instance1_ip:instance1_port;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ ^/(status2|ping2)$ {
        access_log off;
        fastcgi_pass instance2_ip:instance2_port;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

If you find this approach too tedious at scale, setting use_fastcgi to true instructs the check to bypass any proxy servers and communicate directly with PHP-FPM using FastCGI. The default port is 9000 for when omitted from status_url or ping_url.

Unix sockets

If your PHP-FPM installation uses unix sockets, you have to use the below syntax for status_url, ping_url and enable use_fastcgi:

ParameterValue
status_urlunix:///<FILE_PATH>.sock/status
ping_urlunix:///<FILE_PATH>.sock/ping
ping_replypong
use_fastcgitrue

Note: With Autodiscovery, if the Agent runs in a separate container/task/pod, it doesn’t have access to the Unix sockets file of your FPM pool. It order to address this, run the Agent as a sidecar.

Validation

Run the Agent’s status subcommand and look for php_fpm under the Checks section.

Data Collected

Metrics

php_fpm.listen_queue.size
(gauge)
Size of the socket queue of pending connections
php_fpm.processes.active
(gauge)
Total number of active processes
Shown as process
php_fpm.processes.idle
(gauge)
Total number of idle processes
Shown as process
php_fpm.processes.total
(gauge)
Total number of processes
Shown as process
php_fpm.requests.accepted
(count)
Total number of accepted requests
Shown as request
php_fpm.processes.max_reached
(count)
The number of times the process limit has been reached (when pm tries to start more children)
Shown as process
php_fpm.requests.slow
(count)
Total number of slow requests
Shown as request

Events

The PHP-FPM check does not include any events.

Service Checks

php_fpm.can_ping:

Returns CRITICAL if the Agent cannot ping PHP-FPM at the configured ping_url, otherwise OK.

Troubleshooting

Need help? Contact Datadog support.