Excimer

Excimer is a PHP 7.1+ extension that provides an interrupting timer and a sampling profiler.

Just enabling Tideways XHProf in PHP 7.2 causes a performance degradation of about 4%. We believe this is due to its installation of a zend_execute_ex hook, which intercepts all function calls. Even though this hook does nothing by default, just installing it causes PHP's VM to omit certain optimisations. The hook must be installed globally, it is not possible to enable it just for a particular request.

Excimer does not install a zend_execute_ex hook and thus cannot count function calls. It is thus suitable for production installation.

Installation
Excimer requires Linux.

Download the source code into an appropriate directory from git:

Or and unpack.

Build
here is the directory that excimer git repository was cloned to.

Then add  to the PHP configuration in an appropriate place. For example, in modern Debian-derived distributions you'd add a file to  (where   is the version of PHP for which you compiled Excimer) and use the   command to enable it.

Reference documentation
For now, please see the function stubs in the extension source.

Use a one-shot timer to limit the execution time of a function
When the timer expires, Excimer sets a flag which is then checked by the PHP VM every time a function returns, and on every loop iteration. For CPU-intensive tasks, this is usually often enough. However, it will not interrupt long-running C functions such as MySQL connection attempts.

When the exception is thrown, the backtrace will show the callback being called from the interrupted code.

Note that the $timer variable must be kept alive, for example by keeping it in scope. If the timer object is destroyed, the timer will stop and the callback will not be called.

Use a periodic timer to gather time-series memory usage statistics
The process will be interrupted once every 100ms, and the current memory usage logged to a file.

Profile a process and produce a flame graph
In this example, FlameGraph is presumed to be installed at /usr/local/bin/flamegraph.pl. An SVG file is written to /tmp/profile.svg. An example of the typical output can be seen at https://tstarling.com/stuff/excimer-flamegraph.svg.

Profile a process and produce a function table
In this example, event counts are aggregated by function name, formatted in a fixed-width table, and written to a file. An example of typical output can be seen at https://tstarling.com/stuff/excimer-aggregated.txt.