PHP-FPM

This guide explains how to instrument a PHP application running on PHP-FPM by selecting a Linux agent for trace ingestion.

Prerequisites

• The Motadata Agent must be installed and running on the server where the PHP-FPM application is deployed. Also, the otelcol should be running as part of the Motadata Agent.
  To check the agent status, open a Linux terminal and run:

service motadata-agent status

• PHP version must be in the supported range (8.1 or above). To verify run the below command:

php -v

• PHP-FPM must be installed and running. To verify run the below command (example commands):

php-fpm -v
# or
php8.2-fpm -v

• If you are using Apache, ensure Apache version is 2.4 or higher. To verify run the below command (example commands):

apachectl -v
# or
httpd -v

• If you are using Nginx, ensure Nginx is installed and reachable. To verify run the below command:

nginx -v

• Composer must be installed (the setup pulls dependencies). To verify run the below command:

composer -V

• Ensure the setup command is executed from the application project root directory.

• Ensure an active internet connection is available while executing the setup command.

• You must have:

  • Permission to restart PHP-FPM and the web server (Apache/Nginx), or restart the container (for Docker).
  • The correct PHP CLI binary path available. You can usually fetch it using:

which php

Configuration Steps

Step1: Register the Application Service in Motadata AIOps

Go to Menu > Settings > APM > Application Registration. Clicking the Application Registration button, you can register a new application.

From the application registration screen, select the instrumentation type Host/VM or Docker.

Host/VM

PHP Trace Configuration

For doing this first find the PHP CLI Binary path, to do this run the below command:

which php

Example output:

/usr/bin/php

or

/usr/local/bin/php**

info

If which php returns no output, it means the PHP binary is not present in the system PATH environment variable. In this case, you need to manually locate the PHP binary on the system that is used to run the application. This step is mandatory and cannot be skipped. This exact path must be provided in the Motadata UI.

Field	Description
Select Agent	Select the Host/VM where this PHP-FPM application is running. You can configure PHP application service for Linux type agent.
Select Language	Select PHP from the language icons.
APM Hosting Type	Select PHP-FPM as apm hosting type.
Web Server	Select the web server used to serve requests (Apache or Nginx).
Service Name	Provide a unique and meaningful name. The service name must not contain spaces or hyphens (-). Underscore (_) is supported.
PHP Directory Path	Provide complete path where PHP is installed on your system.
Application Config Path	Provide the directory path where the your application or web server configuration is stored. This is used to set the required environment variables for instrumentation. Examples: - Apache: /etc/apache2/ or /etc/httpd/ - Nginx: /etc/nginx/

Providing these details displays Setup Command to instrument your PHP-FPM application.

Step2: Configure PHP-FPM for Instrumentation

Log in to the Linux server where your PHP-FPM application is hosted. Navigate to the project root directory of your PHP application and paste the copied Setup Command displayed in Motadata AIOps and execute it.

info

This directory typically contains:

• composer.json
• composer.lock
• vendor/
• Application source files

For Example: cd /var/www/html/my-php-app

note

Running the script outside the application root will cause installation failures.

To run the Instrumentation command follow the below example:

Example:

at

cd /var/www/html/my-php-app sudo <paste-the-script-here>

Pasting this script enables the PHP tracing extension, installs required instrumentation dependencies and configures environment variables for PHP-FPM via the web server configuration.

note

During installation few important dependencies are manged by PHP application like below:

• Additional libraries required for tracing are added.
• In applications with strict dependency constraints, minor adjustments may be required.

Then, restart your web server based on what fronts PHP-FPM:

For Nginx

sudo systemctl restart nginx

For Apache

sudo systemctl restart apache2
# or
sudo systemctl restart httpd

Docker

PHP Trace Configuration

Field	Description
Select Agent	Select the Docker host where the PHP-FPM container is running.
Select Language	Select PHP from the language icons.
APM Hosting Type	Select PHP-FPM.
Web Server	Select the web server used inside the container (Apache or Nginx).
Service Name	Provide a unique and meaningful name. The service name must not contain spaces or hyphens (-). Underscore (_) is supported.
Docker Image Name	Provide the exact Docker image name (include tag if applicable).
Application Config Path	Provide the directory path where the web server configuration is stored inside the container (example: /etc/nginx/ or /etc/apache2/).

Providing these details displays Setup Command to instrument your PHP-FPM application.

Step2: Configure PHP-FPM for Instrumentation

Identify the container where PHP-FPM is running. Open a shell inside the container.

docker exec -it <container_name> sh
# use bash if available
docker exec -it <container_name> bash

Then, navigate to the application project root directory inside the container and paste the copied Setup Command displayed in Motadata AIOps.

Then, restart the container using your standard deployment method. For Example:

docker restart <container_name>

info

You can verify the instrumentation for PHP-FPM using browser-based phpinfo page. For doing this initially you need to create a phpinfo page in the container using the below command:

<?php phpinfo(); ?>

You can access it in the browser using:

http://<host>/phpinfo.php

Now check Server API in the pageinfo using:

Server API => FPM/FastCGI

Then Loaded Configuration File using:

Loaded Configuration File => /path/to/php.ini

And last Loaded Extensions and Environments by searching:

OTEL_

Step3: Configure Attributes and Parameters

After configuring the application, you can provide the below details:

Field	Description
Service Attributes(Tags)	Add key–value tags to your application for better filtering and organizing data in Explorer. Attribute keys must be in lowercase (for example, apm.env = prod). To add multiple Key-Value pairs you can click the add icon.
Custom Parameters	Add optional key–value parameters for advanced use cases. These parameters are passed to the agent (for example, version=4).

Select Apply Configuration to start trace ingestion.

Verification

Once the application is running, verify the following:

• Confirm that the service has been registered successfully.
• On the service registration screen, the Service Trace Collection Status should display Running/Active.
• Traces should start appearing in the APM Explorer screen for the registered service.

You can troubleshoot the PHP-FPM instrumentation for both Host/VM and Docker.

Troubleshooting Steps

Host/Vm

Use the below trouble shooting steps, if traces are not visible or setup fails.

1. Verify PHP-FPM is running bu using the below command:

systemctl status php-fpm

or version-specific:

systemctl status php8.2-fpm

2. Check PHP Info Page in Browser (Recommended for PHP-FPM)

Create a file in your web root:

/var/www/html/phpinfo.php

Content should be like:

<?php phpinfo(); ?>

Then open in browser using:

http://<host>/phpinfo.php

Then check the phpinfo page for Server API using:

Server API => FPM/FastCGI

You can check Loaded Configuration File using:

Loaded Configuration File => /etc/php/8.2/fpm/php.ini

This confirms PHP-FPM is using the expected php.ini or not.

You can also search for Loaded Extensions and Environmental variables by searching:

OTEL_

If missing, there may be the below reasons:

• Web server was not restarted.
• Application config path may be incorrect.

3. phpinfo Page Works but No Traces found

Then the Common reasons can be:

• Web server was not restarted after instrumentation.
• May be the provided application config path was Incorrect.
• Wrong PHP binary configured.
• Traffic is not reaching PHP-FPM (this can be because it contains static files only).
• Internet was unavailable during installation.

4. Extension Not Loaded in PHP-FPM but Works in CLI

Possible Reason:CLI and FPM use different php.ini files

To Check you can run below command in the directory:

php -i | grep "Loaded Configuration File"

Compare the output with phpinfo page path and ensure Extension is enabled in FPM configuration.

5. Check PHP-FPM Logs

Common locations:

/var/log/php-fpm.log /var/log/php8.2-fpm.log

Web server logs:

/var/log/apache2/error.log /var/log/nginx/error.log

6. No Service Visible in Motadata

You need to verify the below details:

• Agent is running.
• Correct agent is selected.
• Service name matches in the setup command.
• Application has received traffic.
• Web server was restarted after instrumentation.
• Script was executed from application root
• Make sure that root permissions were used during instrumentation.

Docker

1. If Container Exits Immediately

Check logs using:

docker logs <container_id>

Common reasons:

• PHP-FPM binary may be missing.
• Invalid image
• Permission issues

You can fix these issues manually or connect support team for major issues.

2. PHP-FPM Starts but No Traces found.

For this you need to check for:

• Agent is running on the host
• Correct agent was selected
• Container can reach the host
• Traffic is actually hitting PHP (not only static files)

3. phpinfo Page Shows No OTEL Extension

This may happen due to:

• PHP version can be unsupported.
• The PHP binary inside the image can be incorrect.
• PHP-FPM may have used a different php.ini

You can check inside container using below command:

php -i | grep "Loaded Configuration File"

You can fix the listed issues manually or connect support team for major issues.

4. Composer-Related Errors During Startup

In some images you may find:

• Dependency constraints may require adjustments
• Composer may already be locked to specific versions

These situations are common in containerized PHP environments and can usually be resolved by reviewing the logs.

5. Multiple Containers Using Same Image

This may be because each container instance generates traces independently, so you need to use different service names if logical separation is required.