[opensourcedex]

php-spx is a free, open source business intelligence & reporting project written in C and released under GPL-3.0. It has 2,636 GitHub stars, 103 forks and 70 open issues, and was last pushed 7 days ago. On this registry it ranks #43 of 77 tracked projects in Business Intelligence & Reporting, with 5 head-to-head comparisons available.

What is php-spx?

SPX (Simple Profiling eXtension) is a free, GPL-3.0 PHP profiling extension written in C that ships with its own built-in web UI, intended for PHP developers and performance engineers who profile web requests and command line scripts on their own infrastructure.

What it is

SPX is a native profiling extension for PHP, shipped as spx.so and loaded through php.ini or a dedicated spx.ini file placed in the include directory. It supports PHP 5.4 through 8.5 and runs on GNU/Linux, macOS and FreeBSD, on x86-64 or ARM64, with the zlib development package required at build time. The profiler and the analysis front end arrive together: the web UI both controls profiling and presents the collected reports, so no separate viewer has to be installed or kept in step with the extension.

The concrete problem it solves is context loss and setup friction in other PHP profilers. Xhprof and potentially its forks aggregate data per caller and callee pair, which discards the full call stack and forbids timeline or Flamegraph analysis. SPX keeps that context and is multi-metric capable, with 22 metrics currently supported across various time and memory metrics, included files, objects in use and I/O. It also removes the instrumentation step entirely: profiling a script needs only an environment variable for a command line run or a radio button for a web request, with no manual code changes, no dedicated browser extension and no command line launcher.

Key capabilities

  • Reports 22 metrics, covering various time and memory metrics together with included files, objects in use and I/O.
  • Enables profiling by setting an environment variable for a command line script or switching on a radio button in the web UI for a web request, without instrumenting application code.
  • Supports Ctrl-C interruption of a long running command line script, which still ends the profiling session in a usable state.
  • Ships a web UI that enables and configures profiling for the current browser session, lists profiled script reports, and opens a selected report for in-depth analysis.
  • Renders three interactive visualizations: a timeline that scales to millions of function calls, a flat profile and a Flamegraph.
  • Reads procfs under /proc on GNU/Linux to collect per-process or per-thread statistics behind the mor, io, ior and iow metrics.
  • Confines all profiling data to the host infrastructure, with no SaaS component involved.

Who uses it and how

  • Developers chasing slow web requests in local development, switching profiling on from the web UI for the current browser session and reading the resulting report straight away.
  • Engineers profiling long running command line jobs such as workers or batch scripts, where Ctrl-C ends the run but still leaves a finished profile behind.
  • GNU/Linux teams running PHP-FPM that want I/O and memory figures alongside timing data, by selecting the io, ior, iow and mor metrics.
  • Performance engineers analysing deep call stacks, where the timeline view scales to millions of function calls and the Flamegraph exposes the hot path.
  • Teams that cannot send application data to a third party service, since profiling stays confined to their own machines.

Getting started

Install the extension through PIE with pie install noisebynorthwest/php-spx. To build from source instead, clone the repository, check out release/latest, then run phpize, ./configure, make and sudo make install, and add extension=spx.so to php.ini or to a dedicated spx.ini file.

How it compares

Among PHP profilers, the named point of comparison is Xhprof and potentially its forks, which aggregate data per caller and callee pair and therefore lose the full call stack. SPX retains that stack, and that retention is what makes timeline and Flamegraph analysis possible in the first place. It also bundles its own web UI rather than relying on external tooling, and both the extension and that interface are free, with profiling data staying on the user's own infrastructure.

When to use it — and when not to

Running SPX requires little beyond PHP itself: the zlib development package at build time, and for the mor, io, ior and iow metrics on a PHP-FPM setup, read access to /proc, which most PHP-FPM setups deny through permissions. ZTS PHP support is still beta, and it adds overhead even when SPX is not enabled, does not finish a session properly on Ctrl-C, and makes segfaults more likely, so mixing SPX with debuggers or other instrumenting extensions is inadvisable. Anyone needing Windows, a platform outside GNU/Linux, macOS and FreeBSD, or a managed profiler with no extension to build and no server access to arrange should look elsewhere.

project readme (upstream, from github) — read inline

SPX - A simple profiler for PHP

[![Build Status][:badge-ci:]][:link-ci:] ![Supported PHP versions: 5.4 .. 8.x][:badge-php-versions:] ![Supported platforms: GNU/Linux, macOS & FreeBSD][:badge-supported-platforms:] ![Supported architectures: x86-64 or ARM64][:badge-supported-arch:] [![License][:badge-license:]][:link-license:]

Buy Me A Coffee

Click here for a live demo of the analysis screen

Showcase

Showcase

SPX, which stands for Simple Profiling eXtension, is just another profiling extension for PHP. It differentiates itself from other similar extensions as being:

  • totally free and confined to your infrastructure (i.e. no data leaks to a SaaS).
  • very simple to use: just set an environment variable (command line) or switch on a radio button (web request) to profile your script. Thus, you are free of:
    • manually instrumenting your code (Ctrl-C a long running command line script is even supported).
    • using a dedicated browser extension or command line launcher.
  • multi metrics capable: 22 are currently supported (various time & memory metrics, included files, objects in use, I/O...).
  • able to collect data without losing context. For example Xhprof (and potentially its forks) aggregates data per caller / callee pairs, which implies the loss of the full call stack and forbids timeline or Flamegraph based analysis.
  • shipped with its web UI which allows to:
    • enable / configure profiling for the current browser session
    • list profiled script reports
    • select a report for in-depth analysis, featuring these interactive visualizations:
      • timeline (scale to millions of function calls)
      • flat profile
      • Flamegraph

Requirements

Platforms support is currently quite limited. Feel free to open an issue if your platform is not supported. Current requirements are:

  • x86-64 or ARM64
  • GNU/Linux, macOS or FreeBSD
  • zlib dev package (e.g. zlib1g-dev on Debian based distros)
  • PHP 5.4 to 8.5

Installation

Prerequisites

  • PHP development package (corresponding to your installed PHP version).
  • zlib development package:
    • For Debian-based distros (including Ubuntu, Kubuntu...), just run: sudo apt-get install zlib1g-dev.
    • For Fedora-based distros (including CentOS, AlmaLinux, Rocky Linux...), just run: sudo dnf install zlib-devel.

Install the extension

Install via PIE
pie install noisebynorthwest/php-spx
Install from source
git clone https://github.com/NoiseByNorthwest/php-spx.git
cd php-spx
git checkout release/latest
phpize
./configure
make
sudo make install
Activate & configure SPX

After installing SPX, add extension=spx.so to your php.ini, or in a dedicated spx.ini file created within the include directory. You may also want to override default SPX configuration to be able to profile a web request, with this one for example for a local development environment.

ZTS PHP (multi-thread)

ZTS PHP is supported, with these extra limitations:

  • a little overhead (theoretically unnoticeable in most cases) is added when SPX is loaded, even if it is not enabled.
  • Ctrl-C a CLI script will not make the possible profiling session to be properly finished.
  • segfaults are more likely than for NTS PHP. In this regard, avoid more than ever mixing SPX with other instrumenting extensions (debuggers, profilers...).

Also, consider ZTS PHP support as still being in beta.

Linux, PHP-FPM & I/O stats

On GNU/Linux, SPX uses procfs (i.e. by reading files under /proc directory) to get some stats for the current process or thread. This is what is done under the hood when you select at least one of these metrics: mor, io, ior or iow.

But, on most PHP-FPM setups, you will have a permission issue preventing SPX to open a file under /proc/self directory. This is due to the fact that PHP-FPM master process runs as root when child processes run as another unprivileged user.

When this is the case, the process.dumpable = yes line must be added to the FPM pool configuration so that child processes will be able to read any file under /proc/self.

Development status

This is still experimental. API might change, features might be added or dropped, or development could be frozen.

You can still safely use it in a non-production environment.

Contributions are welcome but be aware of the experimental status of this project and please follow the contribution rules described here: CONTRIBUTING.md

Basic usage

web request

Assuming a development environment with the configuration described here and your application is accessible via http://localhost.

Just open with your browser the following URL: http://localhost/?SPX_KEY=dev&SPX_UI_URI=/ to access to the web UI control panel.

N.B.: http://localhost/ must be served by a PHP script through standard web server feature like directory index or URL rewriting. The PHP script will however not be executed, SPX will intercept and disable its execution to serve its content in place.

If you see only a blank page then make sure to set zlib.output_compression = 0 in your PHP configuration file

You will then see the following form:

Showcase

Then switch on "Enabled". At this point profiling is enabled for the current domain and your current browser session through a set of dedicated cookies.

Profiling can also be triggered with Curl as shown in this example:

curl --cookie "SPX_ENABLED=1; SPX_KEY=dev" http://localhost/

N.B.: You can also enable the profiling at INI configuration level via the spx.http_profiling_enabled setting, and therefore for all HTTP requests. However, keep in mind that using this setting on a high-traffic environment could quickly exhaust the storage device's capacity of the SPX's data directory.

Then refresh the web request you want to profile and refresh the control panel to see the generated report in the list below the control panel form.

Showcase

Then click on the report in the list and enjoy the analysis screen.

Command line script

Instant flat profile

Just prepend your command line with SPX_ENABLED=1 to trigger profiling. You will get the flat profile printed on STDERR at the end of the execution, even if you abort it by hitting Ctrl-C, as in the following example:

$ SPX_ENABLED=1 composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
^C
*** SPX Report ***

Global stats:

  Called functions    :    27.5K
  Distinct functions  :      714

  Wall time           :    7.39s
  ZE memory           :   62.6MB

Flat profile:

 Wall time           | ZE memory           |
 Inc.     | *Exc.    | Inc.     | Exc.     | Called   | Function
----------+----------+----------+----------+----------+----------
  101.6ms |  101.6ms |   41.8MB |   41.8MB |       12 | Composer\Json\JsonFile::parseJson
   53.6ms |   53.6ms |     544B |     544B |        4 | Composer\Cache::sha256
    6.91s |   41.5ms |   41.5MB |   -7.5MB |        4 | Composer\Repository\ComposerRepository::fetchFile
    6.85s |   32.3ms |   47.5MB |    5.4MB |        5 | 1@Composer\Repository\ComposerRepository::loadProviderListings
    7.8ms |    7.8ms |       0B |       0B |        4 | Composer\Cache::write
    1.1ms |    1.1ms |     -72B |     -72B |        1 | Composer\Console\Application::Composer\Console\{closure}
  828.5us |  828.5us |     976B |     976B |       12 | Composer\Util\RemoteFilesystem::findHeaderValue
  497.6us |  491.0us |  710.2KB |  710.2KB |        1 | Composer\Cache::read
    2.4ms |  332.6us |   20.9KB | -378.8KB |       34 | 3@Symfony\Component\Finder\Iterator\FilterIterator::rewind
  298.9us |  298.9us |    2.2KB |    2.2KB |       47 | Symfony\Component\Finder\Iterator\FileTypeFilterIterator::accept

readme truncated — read the full docs on github

Frequently asked questions

Is php-spx free to use?

php-spx is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does php-spx do?

A simple & straight-to-the-point PHP profiling extension with its built-in web UI

What is php-spx written in?

php-spx is primarily written in C. Its source is publicly available at https://github.com/NoiseByNorthwest/php-spx, and it has 2,636 GitHub stars.