Overview
PHP-based services require you to specify the directory path where the codebase is located. Traces are captured through integration points in PHP scripts and processed using the agent.
Prerequisite
Before you begin, ensure the following requirements are met:
- PHP Version: 8.1 to 8.4
To verify run the below command:
php -v
You can also check php path by using the below command:
which php
- Docker Version: 20.1 or Higher
- Apache Version: 2.4 or Higher
- Nginx Version: 1.14 or Higher
- The command must be executed from the project's root directory.
- An active internet connection is required while executing the command.
Navigation
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
- Docker
PHP Trace Configuration
| Field | Description |
|---|---|
| Select Agent | Select the Host/VM where this application is running. You can configure PHP application service for Linux type agent. |
| Language | Select PHP from the language icons. |
| Business Service | The business service represents a logical grouping of related microservices under a single business application (e.g., Order Management). Adding or selecting the available service group from the drop-down will add your application service to the dedicated business service group. |
| App Hosting Type | Choose the method your application uses to execute PHP requests. You can select either PHP CLI or PHP FPM. |
| Web Server | If you select app hosting type as PHP FPM then you need to select the web server running your application as Apache or Nginx. |
| Service Name | Provide a unique and meaningful name (e.g., ERP). |
| PHP Directory Path | Please provide complete path where PHP is installed on your system. |
| Application Config Path | If you select app hosting type as PHP FPM then you need to provide complete path where your application or web server configuration is stored. |
| 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. |
| Add Custom Parameters | Allows you to define custom sampling or tagging parameters for advanced use cases. These optional parameters are passed to the agent (for example, version=4). |
Clicking the Apply Configuration button, the ingestion gets started.
Providing these details displays Setup Command to instrument your PHP application. To instrument your PHP application, run the following .sh script. Start collecting Traces by restarting your service.
You can configure Trace ingestion according to the framework used to build the application. The below mentioned are the supported frameworks.
Supported Frameworks
The following frameworks are supported for instrumentation and monitoring. Ensure your application version aligns with the supported versions listed below.
| Framework | Version(s) |
|---|---|
| CakePHP | 4 || 5 |
| CodeIgniter | 4.0+ |
| Laravel | 1.2.2+ |
| Symfony | 1.0.2+ |
| Slim Framework | 1.1.1+ |
Supported Database
| Database | Version(s) |
|---|---|
| MongoDB | ext-mongodb 1.13+ |
Supported Others
| Library | Version(s) |
|---|---|
| Guzzle | Guzzle >7.0 |
| HTTPlug async | php-http/httplug 2.0+ |
Once the Application is Running, you need to 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.
- Docker Run
- Docker Compose
- Docker Swarm
PHP Trace Configuration
| Field | Description |
|---|---|
| Select Agent | Select the Docker where this application is running. You can configure PHP application service for Linux type agent. |
| Language | Select PHP from the language icons. |
| Business Service | The business service represents a logical grouping of related microservices under a single business application (e.g., Order Management). Adding or selecting the available service group from the drop-down will add your application service to the dedicated business service group. |
| App Hosting Type | Choose the method your application uses to execute PHP requests.i.e., PHP CLI, PHP FPM. |
| Service Name | Provide a unique and meaningful name (e.g., ERP). |
| Image Name | Specify the Docker image name where your application is running. (e.g nginx:latest) |
| 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. |
| Add Custom Parameters | Allows you to define custom sampling or tagging parameters for advanced use cases. These optional parameters are passed to the agent (for example, version=4). |
Clicking the Apply Configuration button, the ingestion gets started.
Providing these details displays Setup Command to instrument your Java application. Add the following argument to your java -jar command and restart the service to collect Traces.
You can configure Trace ingestion according to the framework used to build the application. The below mentioned are the supported frameworks.
Supported Frameworks
The following frameworks are supported for instrumentation and monitoring. Ensure your application version aligns with the supported versions listed below.
| Framework | Version(s) |
|---|---|
| CakePHP | 4 || 5 |
| CodeIgniter | 4.0+ |
| Laravel | 1.2.2+ |
| Symfony | 1.0.2+ |
| Slim Framework | 1.1.1+ |
Supported Database
| Database | Version(s) |
|---|---|
| MongoDB | ext-mongodb 1.13+ |
Supported Others
| Library | Version(s) |
|---|---|
| Guzzle | Guzzle >7.0 |
| HTTPlug async | php-http/httplug 2.0+ |
Once the Application is Running, you need to 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.
Prerequisites
Ensure the following are in place before proceeding:
| Requirement | Details |
|---|---|
| Docker & Docker Compose installed | docker --version and docker-compose --version |
| Application already running via Compose | docker ps shows the app container |
| Agent files available on host | Confirm agent binary and config files exist under /motadata/motadata/ |
docker-compose.yml accessible | In the application's project directory |
Understanding the Generated Instrumentation Command
Motadata generates a docker run instrumentation command when you click Apply Configuration. Do not run this command directly if the application is managed by Docker Compose. Instead, translate the volume mount flags into docker-compose.yml as described below.
Step 1 — Verify Agent Files on the Host
Confirm the agent and config files exist on the host machine:
ls /motadata/motadata/instrumentation/
ls /motadata/motadata/config/
If either file is missing, contact the Motadata team before proceeding.
Step 2 — Open docker-compose.yml
Navigate to the application's project directory:
cd /path/to/your/project
cat docker-compose.yml
Identify the app service block — this is the service running your application.
Step 3 — Add Volume Mounts
Locate the volumes: section under the app service and append the two instrumentation mounts.
Before:
volumes:
- ./logs:/app/logs
After:
volumes:
- ./logs:/app/logs
- /motadata/motadata/instrumentation:/motadata/instrumentation
- /motadata/motadata/config:/motadata/config
If no
volumes:section exists, add it at the same indentation level asenvironment:,ports:, etc.
Step 4 — Validate the YAML
docker-compose config
This prints the resolved configuration. If there are errors, fix them before proceeding.
Step 5 — Restart the Application
docker-compose down
docker-compose up -d --build
Step 6 — Verify Containers Are Running
docker ps
Both the app and any dependent services should show status Up.
Step 7 — Confirm Agent Loaded Successfully
Check the container logs to confirm the agent initialized correctly:
docker logs <container_name>
Prerequisites
Ensure the following are in place before proceeding with instrumentation.
| Prerequisite | Requirement / Details |
|---|---|
| Docker & Docker Swarm enabled | Docker 20.10 or higher; run docker swarm init on the manager node |
| Docker image available | The service image must be accessible (local registry or Docker Hub) |
| Agent files available on host | Confirm agent binary and config files exist under /motadata/motadata/ |
docker-compose.yml accessible | In the application's project directory |
All worker nodes must be joined to the swarm before deploying instrumented services.
Understanding the Generated Instrumentation Command
Motadata generates a docker run instrumentation command when you click Apply Configuration. Do not run this command directly if the application is managed by Docker Swarm. Instead, translate the volume mount flags into docker-compose.yml as described below.
Step 1 — Verify Agent Files on the Host
Confirm the agent and config files exist on the host machine:
ls /motadata/motadata/instrumentation/
ls /motadata/motadata/config/
If either file is missing, contact the Motadata team before proceeding.
Step 2 — Open docker-compose.yml
Navigate to the application's project directory:
cd /path/to/your/project
cat docker-compose.yml
Identify the app service block — this is the service running your application.
Step 3 — Add extra_hosts
Add the host gateway mapping so the agent inside the container can reach the APM collector on the host:
Before:
ports:
- "8080:8080"
After:
ports:
- "8080:8080"
extra_hosts:
- "host.docker.internal:host-gateway"
Step 4 — Add Volume Mounts
Append the two instrumentation mounts to the volumes: section under the app service:
Before:
volumes:
- ./logs:/app/logs
After:
volumes:
- ./logs:/app/logs
- /motadata/motadata/instrumentation:/motadata/instrumentation
- /motadata/motadata/config:/motadata/config
If no
volumes:section exists, add it at the same indentation level asenvironment:,ports:, etc.
Step 5 — Validate the YAML
docker-compose config
This prints the resolved configuration. If there are errors, fix them before proceeding.
Step 6 — Deploy the Stack
docker stack deploy -c docker-compose.yml <stack_name>
To update an already-running stack:
docker stack deploy -c docker-compose.yml <stack_name> --with-registry-auth
Step 7 — Verify Services Are Running
docker service ls
The instrumented service should show the expected number of replicas in the REPLICAS column (e.g. 2/2).
Step 8 — Confirm Agent Loaded Successfully
Check the container logs to confirm the agent initialized correctly:
docker service ps <stack_name>_<service_name>
docker logs <container_id>