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 Version

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

Shell

Shell

php -v

Install

Step 1: Install PHP Extensions

Step 1a: Install PECL & Composer

• PECL Installation
• Composer Installation

Step 1b: Install otel-instrumentation

Shell

Shell

sudo pecl install channel://pecl.php.net/opentelemetry-1.0.0beta3

Step 1c: Add Extension to php.ini File

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

Step 1d: Verify Installation

Verify the extension is installed and enabled.

Shell

Shell

php -m | grep opentelemetry

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.

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

Shell

Shell

composer update
composer require middleware/agent-apm-php

Step 3: Import Tracker

Add following code to the beginning of your project:

index.php

php

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

Step 4: Container Variables

Docker

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

Shell

Shell

MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>

Kubernetes

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

Step 5: Implement APM Collector

Start a tracing scope at the beginning of your 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();

Step 6: Enable Logging

To ingest custom logs, utilize 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.");

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

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:

OpenTelemetry

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:

index.php

php

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:

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.