Excimer

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

Linux package manager
See packages.debian.org and packages.ubuntu.com. For alternate PHP versions, Excimer is also packaged at https://deb.sury.org/.

For Fedora and other RPM-based distributions (e.g. using ), Excimer is packaged at https://rpms.remirepo.net (example).

PECL
See our PECL entry.

Source
Download the source code into an appropriate directory from git:

Or and unpack.

Build
Excimer requires Linux.

Below   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.

Background
We found that just enabling Tideways XHProf on a server with PHP 7.2 caused a performance degradation of about 4%. We believe this is due to it installing a  hook, which intercepts all function calls in PHP. Even though this hook does nothing by default, just having it causes PHP's VM to omit certain optimisations. The hook can only be installed globally, and it is not possible to enable it just for a particular request.

Excimer does not install any  hook. This means it cannot count function calls, but makes it suitable for production-wide installation.

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

One-shot timer to limit the execution time of a function
The "interval" timer fires only once. The way this works internally is that, when the timer thread expires, Excimer sets a flag in memory that the PHP VM checks every time a function returns, and on every loop iteration. This check exists in PHP VM and happens regardless of whether Excimer is installed or used. For CPU-intensive tasks, this is usually often enough. However, note that Excimer will not interrupt long-running native 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  variable must be kept alive, for example by keeping it in scope. If the timer object is destroyed, the timer is automatically cleaned up and the callback never called.

Periodic timer to gather time-series memory usage statistics
A long-running process (e.g. command-line job) can be interrupted periodically, and the current memory usage appended to a file.

Per-process flame graph (Speedscope)
In this example, a web request is traced at a high resolution (1ms samples), with a Speedscope-compatible data file written afterward.

You can drag-n-drop the JSON file directly into www.speedscope.app.

At Wikimedia Foundation, we abstract and automate the below through excimer-ui-client and excimer-ui-server (T291015).

Per-process flame graph (SVG)
In this example, a web request is traced at a high resolution (1ms samples), with an interactive flame graph SVG generated afterward. FlameGraph is presumed to be installed at. An SVG file is written to. A demo of the typical output can be seen at https://tstarling.com/stuff/excimer-flamegraph.svg.

Per-process 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.

Site-wide sample profiling
You can generate flame graphs that represent production requests with very low overhead. Starting the Excimer profiler with a very high period (e.g. 60 seconds), means most requests will never be observed, and a fraction of your requests will have 1 sample taken that we then flush to a tracelog buffer. This could be Redis, rsyslog, ZeroMQ, Multicast UDP-to-file, Kafka, etc. The below example will write it to a local file for testing purposes. This file could then be turned into a flame graph by running. Or load the trace log directly into Speedscope. Eximer ensures that samples are representative by automatically staggering the first (and likely, only) interval by a random fraction of the sampling period.

As of December 2022, Wikipedia's web-facing Apache servers receive about 1.6 billion requests per day (~20,000 req/s) from 300 physical servers across its 2 main data centers. The median latency is ~100ms, with p95 of ~600ms. With the sampling period of 60 seconds, we end up collecting 3 million stack traces per day. This translates to roughly 1 sample from 0.2% of requests, and 0 samples from the other 99.8%. Refer to Arc Lamp for how we do this in production. More details on Profiling PHP in production at scale at our Techblog. Our hourly and daily flame graph can be browsed at https://performance.wikimedia.org/php-profiling/.

Maintainer notes
For information about how to update the PECL release, see how to PECL.