PHP CLI

This guide explains how to instrument a PHP application running as PHP CLI for trace ingestion using a Linux agent. You can instrument the application on Host/VM or Docker.

Prerequisites

• The Motadata Agent must be installed and running on the server where the PHP CLI application is running. 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 should be in the supported range (8.1 to 8.4). To check the version, run:

php -v

• Composer must be installed (required for auto-instrumentation dependencies). To verify, run:

composer --version

• The setup command must be executed from the project’s root directory.
• Ensure an active internet connection is available while executing the setup command.
• Required permissions to restart your CLI workload (for example, supervisor/systemd/cron job) or restart the container if deployed on Docker.

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

Field	Description
Select Agent	Select the Host/VM where this PHP CLI application is running.
Select Language	Select PHP from the language icons.
App Hosting Type	Select PHP CLI.
Service Name	Provide a unique and meaningful name (for example, php_cli_worker).
PHP Directory Path	Provide the full path to the PHP binary used to run the CLI scripts (for example, /usr/local/php83/bin/php).

Providing these details displays the Setup Command to instrument your PHP CLI application.

Step2: Configure PHP CLI for Instrumentation (Host/VM)

1. Log in to the Linux server where your PHP CLI application is hosted.
2. Navigate to your application project root directory.
3. Copy the Setup Command displayed in Motadata AIOps and execute it in the same terminal session.

4) Start your PHP CLI workload using the same command you use in production (for example, a worker/consumer/cron command). Example:

php index.php

or

php /path/to/your-script.php

Docker

PHP Trace Configuration

Field	Description
Select Agent	Select the Docker host where this PHP CLI container is running.
Select Language	Select PHP from the language icons.
Deployment Type	Select Docker Image.
Service Name	Provide a unique and meaningful name (for example, php_cli_docker_worker).
Docker Image Name	Provide the exact Docker image name used to run the PHP CLI workload (for example, my-php-cli-app:latest).

Providing these details displays the Docker Run Command required to instrument your PHP CLI container.

Step2: Configure PHP CLI for Instrumentation (Docker)

1. After you select Apply Configuration, copy the Docker command shown in the UI.
2. In the copied command, replace <your-php-app-start-command> with the exact PHP CLI command you normally run inside the container. Examples:

php index.php

php worker.php

php /app/bin/consumer.php

3. Run the updated Docker command on the Docker host.
4. Trigger your CLI workload (or let it run as per its normal schedule). Traces will start flowing automatically.

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 configuration (for example, version=4).

Select Apply Configuration to finalize the configuration and start ingestion.

Verification

Once the application is running, verify the below points:

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