PHP

This guide walks you through setting up Application Performance Monitoring (APM) on a PHP application. These instructions can also be found on the Installation page in your Middleware Account. View example code here.

Prerequisites

1. Infra Agent: Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide.

2. PHP: PHP version 8.0 or above. Verify with php -v.

3. Composer: Ensure you have the Composer dependency manager installed to install our APM.

4. PECL: PECL is required to install the appropriate extension.

Vanilla PHP

Setup

Before installing any Middleware APM package for PHP, the auto-instrumentation extension must be setup beforehand.

Install the Auto-Instrumentation Extension

Shell

Shell

sudo pecl install channel://pecl.php.net/opentelemetry-1.0.3

Add Extension to php.ini

index.php

php

[opentelemetry]
extension=opentelemetry.so

The php.ini file can be found using the following commands based on your Linux distribution:

Ubuntu/Debian

CentOS/RHEL

Arch Linux

Web-Serve

Shell

Shell

sudo nano /etc/php/<php_version>/cli/php.ini

Shell

Shell

sudo nano /etc/php.ini

Shell

Shell

sudo nano /etc/php/php.ini

Shell

Shell

sudo nano /etc/php/<php_version>/apache2/php.ini

Verify Installation

Verify the extension is installed and enabled.

Shell

Shell

php -m | grep opentelemetry

Install the APM Package

To install the Middleware APM package, run the following commands:

Shell

Shell

composer update
composer require middleware/agent-apm-php

Import the Tracker

Add following code to the entry point of your application, and as the first import:

index.php

php

require 'vendor/autoload.php';
use Middleware\AgentApmPhp\MwTracker;

[Optional] Container Variables

Docker

For use with Docker, add the following environment variable to your application.

Shell

Shell

MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>

Kubernetes

For use with Kubernetes, first ensure the Middleware agent is installed in your cluster by using the following command:

Shell

Shell

kubectl get service --all-namespaces | grep mw-service

Add the following environment variable to your application deployment YAML file:

Shell

Shell

MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

Implement APM Collector

Start a tracing scope right before your main application code:

index.php

php

$tracker = new MwTracker('<PROJECT-NAME>', '<SERVICE-NAME>');
$tracker->preTrack();

Define hooks with class and function names beneath the tracing scope:

index.php

php

$tracker->registerHook('<CLASS-NAME-1>', '<FUNCTION-NAME-1>', [
    'custom.attr1' => 'value1',
    'custom.attr2' => 'value2',
]);
$tracker->registerHook('<CLASS-NAME-2>', '<FUNCTION-NAME-2>');

End the tracing scope:

index.php

php

$tracker->postTrack();

Enable Logging

To ingest custom logs, use the following functions based on desired log severity levels.

index.php

php

$tracker->warn("this is warning log.");
  $tracker->error("this is error log.");
  $tracker->info("this is info log.");
  $tracker->debug("this is debug log.");

Wordpress

Get the script

Change your directory to your wordpress installation directory (i.e. /var/www/localhost/htdocs) and run following command:

curl -O https://install.middleware.io/apm/php/wp-instrument.php

You can also download the script by clicking here.

Installation

Run the script with administrator or root privileges:

sudo -E MW_SERVICE_NAME=<your-service-name> php wp-instrument.php

Here, MW_SERVICE_NAME is optional, default service name will be service-<process id>.

Docker

For use with Docker, add the following environment variable to installation script.

Shell

Shell

sudo -E MW_TARGET=<DOCKER_BRIDGE_GATEWAY_ADDRESS> php wp-instrument.php

Laravel

Installation

Change your directory to laravel project's root directory, and run following commands to install the apm:

Shell

shell

curl -O https://install.middleware.io/apm/php/laravel-instrument.php && sudo php laravel-instrument.php install

This script installs necessary components and configures APM easily.

Usage

This script has a install command which Verifies prerequisites, Installs and configures required extensions and packages for instrumentation.

You can also download the script by clicking here.

Tracing

Traces are automatically enabled.

Metrics

To enable trace-related metrics Add the LaravelApmServiceProvider to the providers array in config/app.php:

app.php

php

'providers' => [
    // ...
    Middleware\LaravelApm\LaravelApmServiceProvider::class,
],

and add the MetricsMiddleware class to the $middleware array in app/Http/Kernel.php. If you have enabled tracing, be sure to add this after the tracing class:

Kernel.php

php

protected $middleware = [
    // ...
    \Middleware\LaravelApm\Middleware\MetricsMiddleware::class,
];

Logging

The package automatically integrates with Laravel's logging system to send logs to Middleware. Ensure the correct log driver and settings are configured in your Laravel app, and the package will automatically handle log capture and export.

Run your app

Set following variables in your environment and restart your app to instrument your app:

env

env

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=your-service-name
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320

To correlate frontend traces with backend traces, add following environment variable:

env

env

OTEL_PROPAGATORS=baggage,tracecontext,b3multi

Docker

For use with Docker, add the following environment variable to installation script.

Shell

Shell

sudo -E MW_TARGET=<DOCKER_BRIDGE_GATEWAY_ADDRESS> php laravel-instrument.php run php artisan

Azure Pipelines

The Azure Pipelines continuous integration and continuous delivery (CI/CD) infrastructure helps you build, deploy, and test your PHP projects. For information on setting up your PHP project with Azure Pipelines and Azure DevOps Services, learn more here.

Step 1: Configure OpenTelemetry Extension

Add the following code to your .ini file located in the /home/html/ini directory of your Azure account:

extension.ini

plaintext

extension=opentelemetry.so

Step 2: Add Configuration to Azure

Navigate to Application Settings in your Azure PHP project account and select New application setting. Add the following Name and Value to the New application setting:

Azure

plaintext

Name: PHP_INI_SCAN_DIR
Value: /home/html/ini

Your configuration should look like the following:

Step 3: Create Your Build Pipelines

Update your build pipeline by adding the following code to the azure-pipelines.yml file:

.yaml

YAML

trigger:
- master

variables:
  # Azure Resource Manager connection created during pipeline creation
  azureSubscription: 'XXXXXXXXXXXXXXXXXXXX'

  # Web app name
  webAppName: 'php-apm-test'

View more

Step 4: Check Your Pipeline

The PHP Agent is now set up to execute a CI/CD approach, following the build pipeline configuration, whenever new code is pushed to the production environment.

Your output should look like the following:

Troubleshooting

Below we cover a few common errors and their solutions.

pecl: command not found error

If you receive a pecl: command not found error, run the following command:

Shell

Shell

sudo apt-get update
apt-get install php-pear php8.1-dev

Broken Dependency Issue

If you receive any broken dependency issues, including errors like libpcre2-dev : Depends: libpcre2-8-0 / libpcre2-16-0 / libpcre2-32-0, run the following command:

Shell

Shell

sudo apt --fix-broken install

ERROR: ‘phpize’ failed error

If you receive an ERROR: ‘phpize’ failed error, run the following commands:

Shell

Shell

sudo apt-get update 
sudo apt-get install php8.1-dev

sudo apt-get update
sudo pecl channel-update pecl.php.net

Continuous Profiling

Continuous profiling captures real-time performance insights from your application to enable rapid identification of resource allocation, bottlenecks, and more.

Continuous Profiling for the PHP APM is not yet available; reach out to our support team if you'd like more information. Navigate to the Continuous Profiling section to learn more about using Continuous Profiling with our other APMs.