TracesMetricsApp LogsCustom LogsProfiling

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.

The Laravel and CakePHP web frameworks are not currently supported by the PHP APM.


1 Infra Agent

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

2 PHP Version

PHP version 8.2 or above. Check your PHP version with the following command:


Step 1: Install PHP Extensions

Step 1a: Install PECL & Composer

Step 1b: Install otel-instrumentation

Step 1c: Add Extension to php.ini File

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

Arch Linux

Step 1d: Verify Installation

Verify the extension is installed and enabled.

Step 2: Install PHP APM Package

Ensure you have a PHP project set up and a composer.json file in your project’s root directory.

If you do not have a composer.json file already created, create one using using the composer init command.

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

Step 3: Import Tracker

Add following code to the beginning of your project:

Step 4: Container Variables


Applications running in a container require an additional environment variable. If your application is not running in a container, move to Step 5.

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

The DOCKER_BRIDGE_GATEWAY_ADDRESS is the IP address of the gateway between the Docker host and bridge network. This is by default. Learn more about Docker bridge networking here


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

Step 5: Implement APM Collector

Start a tracing scope at the beginning of your code:

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

End the tracing scope:

Step 6: Enable Logging

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


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:

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:

ERROR: ‘phpize’ failed error

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

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:

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:

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:

The below build pipeline includes installation steps for Opentelemetry and the middleware/agent-apm-php

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:

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 Cloudflare 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.

Need assistance or want to learn more about Middleware? Contact our support team in Slack.