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.

Prerequisites

  • Middleware Host Agent (MW Agent), to install the MW Agent please see our installation guide.
  • PHP version 8+, you can check your PHP version with the following command.
    Shell
    php -v
    
  • Pecl and Composer and the otel-instrumentation PHP extension (see below)

PHP Extension

Follow these steps to install the required otel-instrumentation PHP extension.

Install the extension.

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

Mention the extension as extension=opentelemetry.so in your php.ini file. The php.ini file can be found using the following commands based on your Linux distribution.

Ubuntu/Debian

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

CentOS/RHEL

Shell
sudo nano /etc/php.ini

Arch Linux

Shell
sudo nano /etc/php/php.ini

Specific to Web-Serve

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

Verify the extension is installed and enabled.

Shell
php -m | grep opentelemetry

Troubleshooting

Below we cover a few common errors and their solutions.

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

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

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
sudo apt --fix-broken install

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

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

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

Step 1: Install APM-PHP 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 one, create it using composer init. Then run the following to install Middleware’s APM-PHP package.

Shell
composer update
composer require middleware/agent-apm-php

Step 2: Import Tracker

Add these lines to the beginning of your project.

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

Step 3: 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.

Shell
MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>
docker bridge gateway address is the IP address of the gateway between the Docker host and the bridge network, which is 172.17.0.1 by default. Refer more about Docker bridge networking here
Shell
kubectl get service --all-namespaces | grep mw-service

Then add the following environment variable to your application deployment YAML file.

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

Step 4: Implement APM Collector

Start a tracing scope at the beginning of your code.

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

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

Shell
$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 after your code.

PHP
$tracker->postTrack();

Step 5: Enable Logging

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

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.");
Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.