TracesMetricsApp LogsCustom LogsProfiling
---

​
Prerequisites

  • To monitor APM data on dashboard, Middleware Host-agent needs to be installed, You can refer this demo project to refer use cases of APM.
  • PHP requires at least PHP 8+ and a PHP-Extension to run this agent.

​
Guide

​
Initial Setup:

Before installing this agent, you need to install PHP-Extension(named otel_instrumentation) to run this agent. You can follow below steps to install & enable it:
  • Run follow cmd to install the extension:
sudo pecl install channel://pecl.php.net/opentelemetry-1.0.0beta3
  • Then, Mention the extension as extension=opentelemetry.so to your php.ini file (depending on which Linux distribution you’re using):
    Ubuntu/Debian: 
    sudo nano /etc/php/{PHP_VERSION}/cli/php.ini
    CentOS/RHEL: 
    sudo nano /etc/php.ini
    Arch Linux: 
    sudo nano /etc/php/php.ini
    Specific to the Web-Serve: 
    sudo nano /etc/php/{PHP_VERSION}/apache2/php.ini
  • And verify that the extension is installed and enabled using:
php -m | grep  opentelemetry

​
Troubleshoot

While installing PHP-Extension:
  • If you are facing pecl:command not found, then you need to run follow cmd: 
    sudo apt-get update
apt-get install php-pear php8.1-dev
  • If you are facing any kind of broken dependencies issues like: libpcre2-dev : Depends: libpcre2-8-0 / libpcre2-16-0 / libpcre2-32-0, then you need to run follow cmd: 
    sudo apt --fix-broken install
  • If you are facing ERROR: 'phpize' failed, then you need to run follow cmd: 
    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

Make sure you have a PHP project set up and a composer.json file in your project’s root directory. If you don’t have one, you can create it using composer init. Run below command in your terminal to install Middleware’s APM-PHP package. 
composer update
composer require middleware/agent-apm-php

​
Step 2: Prepend APM script

Add these lines given below at the very start of your project. 
require 'vendor/autoload.php';
use Middleware\AgentApmPhp\MwTracker;

​
Step 3: Use APM Collector & Start the Tracing-scope

By using the APM Collector, you will start tracing-scope before your code, Also you need to register your hooks along with initial declaration. In each hook, you need to define your Classes & Functions name, so whenever they run, agent will track them auto. 
$tracker = new MwTracker('<PROJECT-NAME>', '<SERVICE-NAME>');
$tracker->preTrack();

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

​
Step 4 : End the Tracing-scope

After your code-flow, you need to end the tracing scope, so that agent can send the data to Middleware’s APM dashboard. 
$tracker->postTrack();

​
Step 5 : To enable Logging feature

If you want to enable Logging feature along with tracing in your project, then you can use below code snippet. 
 $tracker->warn("this is warning log.");
 $tracker->error("this is error log.");
 $tracker->info("this is info log.");
 $tracker->debug("this is debug log.");

​
Final code snippet will be

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

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

$tracker->info("this is info log.");

// ----
// Your code goes here.
// ----

$tracker->postTrack();

​
Sample Code:

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

$tracker = new MwTracker('DemoProject', 'PrintService');
$tracker->preTrack();
$tracker->registerHook('DemoClass', 'runCode', [
    'code.column' => '12',
    'net.host.name' => 'localhost',
    'db.name' => 'users',
    'custom.attr1' => 'value1',
]);
$tracker->registerHook('DoThings', 'printString');

$tracker->info("this is info log.");

class DoThings {
    public static function printString($str): void {
        // sleep(1);
        global $tracker;
        $tracker->warn("this is warning log, but from inner function.");
        
        echo $str . PHP_EOL;
    }
}

class DemoClass {
    public static function runCode(): void {
        DoThings::printString('Hello World!');
    }
}

DemoClass::runCode();

$tracker->postTrack();

​
Note for APM inside Kubernetes

If you are using APM in a Kubernetes cluster make sure to follow these 2 steps:

​
Step 1 : Find your Middleware Service namespace

For older setup, your “mw-service” can be inside mw-agent-ns-{FIRST-5-LETTERS-OF-API-KEY} namespace For newer setup, we simplified the namespace name to mw-agent-ns

​
Step 2 : Set this ENV variable in your application deployment YAML

MW_AGENT_SERVICE=mw-service.NAMESPACE.svc.cluster.local
Please replace “NAMESPACE” with the correct value that you found from Step 1.