Profile PHP Applications with Reli: Sampling Tracing and Flamegraph Guide

Reli is a PHP‑written sampling profiler and VM state inspector that can read information about running PHP scripts from outside the process, so the target program needs no modification.

What It Can Do

Detect and visualize bottlenecks at function, line, or opcode level.

Provide low‑overhead sampling even when many fast functions are called.

Investigate bugs or performance failures, even when the script is unresponsive.

Find memory bottlenecks or leaks.

How It Works

Parses the PHP interpreter’s ELF binary.

Reads memory maps from /proc/<pid>/maps.

Uses FFI together with ptrace(2) and process_vm_readv(2) to read the target process’s memory.

Analyzes internal Zend Engine data structures.

Requirements

PHP 8.1+ (NTS or ZTS) on 64‑bit Linux x86_64.

FFI extension enabled (compiled with --with-ffi).

PCNTL extension enabled.

Installation

git clone [email protected]:reliforp/reli-prof.git
cd reli-prof
/usr/local/php-8.2.14/bin/php /home/www/build/composer.phar install
/usr/local/php-8.2.14/bin/php ./reli

Basic Usage

1. Get trace configuration

/usr/local/php-8.2.14/bin/php ./reli inspector:trace --help

The command prints options such as -p/--pid, -d/--depth, -s/--sleep-ns, and template choices like phpspy, phpspy_with_opcode, or json_lines.

2. Daemon mode

/usr/local/php-8.2.14/bin/php ./reli inspector:daemon --help

Daemon mode continuously collects traces from processes whose command line matches a given regex.

Example: Tracing a WebMan Process

First, view the status of a WebMan server (output omitted for brevity). Then trace a simple script:

/usr/local/php-8.2.14/bin/php ./reli i:trace -- php -r "fgets(STDIN);"

Attach to a running process by PID:

sudo /usr/local/php-8.2.14/bin/php ./reli i:trace -p 2184553

Get a memory address of the target process:

sudo /usr/local/php-8.2.14/bin/php ./reli i:eg -p 2184553

Trace opcodes (useful for CPU‑bound workloads):

sudo /usr/local/php-8.2.14/bin/php ./reli i:trace --template=phpspy_with_opcode -p 2184553

The output shows stack frames with the opcode name, e.g., ZEND_DO_FCALL, which can be visualized with a flamegraph.

Flamegraph Generation

sudo /usr/local/php-8.2.14/bin/php ./reli c:flamegraph < traces > flame.svg

Open flame.svg in a browser to view the flamegraph of the traced PHP process.

Additional Tips

Install Google Chrome (optional) to view SVG files.

If the FFI extension fails to compile with No package 'libffi' found, install the library: sudo apt install libffi-dev.

Give execution permission to the reli‑prof directory: sudo chmod 0775 -R /home/www/build/reli-prof.