PHPackages                             wikimedia/arc-lamp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Debugging & Profiling](/categories/debugging)
4. /
5. wikimedia/arc-lamp

ActiveLibrary[Debugging & Profiling](/categories/debugging)

wikimedia/arc-lamp
==================

Flame graphs and log processing for PHP stack traces.

2.0.0(5y ago)434.4k↑30.4%5Apache-2.0ShellPHP >=7.2.0

Since Jul 23Pushed 2mo ago14 watchersCompare

[ Source](https://github.com/wikimedia/performance-arc-lamp)[ Packagist](https://packagist.org/packages/wikimedia/arc-lamp)[ RSS](/packages/wikimedia-arc-lamp/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (3)Used By (0)

[![Packagist](https://camo.githubusercontent.com/1f2b60224e942710dc28083cc3c2fbf5167f87d2c65123af97600ed44a8be02b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77696b696d656469612f6172632d6c616d702e7376673f7374796c653d666c6174)](https://packagist.org/packages/wikimedia/arc-lamp)

Arc Lamp
========

[](#arc-lamp)

Arc Lamp helps gather stack traces from a running PHP 7 application and publish them in the form of flame graphs and trace logs.

See [performance.wikimedia.org](https://performance.wikimedia.org/php-profiling/) for a live example.

Prerequisites
-------------

[](#prerequisites)

Client:

- Your PHP application, with [php-excimer](https://www.mediawiki.org/wiki/Excimer), and php-redis.

Processor:

- A Redis server.
- Python, with `python-redis` and `python-yaml`.
- The `ifne` command from `moreutils` ([Debian](https://packages.debian.org/stable/moreutils), [Homebrew](https://formulae.brew.sh/formula/moreutils), [source](https://joeyh.name/code/moreutils/)).

Quick start
-----------

[](#quick-start)

```
require_once 'ArcLamp.php';

Wikimedia\ArcLamp::collect( [ 'redis-host' => '127.0.0.1' ] );
```

To automatically enable this for all web requests and entry points, you can use the PHP [`auto_prepend_file`](https://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file)option. See [Wikimedia's own configuration](https://github.com/wikimedia/operations-mediawiki-config/blob/5959dc3e7610aa06d9307b42baed17a5bf1be719/wmf-config/PhpAutoPrepend.php#L5) for example.

How it works
------------

[](#how-it-works)

*See also: [Profiling PHP in production](https://techblog.wikimedia.org/2021/03/03/profiling-php-in-production-at-scale/) on Wikimedia Techblog.*

[![](./docs/ArcLamp_2019_diagram.png)](./docs/ArcLamp_2019_diagram.png)

The Arc Lamp pipeline comprises of three stages:

1. Capture stack traces.
2. Create trace logs.
3. Generate flame graphs.

### Capture stack traces

[](#capture-stack-traces)

The [php-excimer](https://www.mediawiki.org/wiki/Excimer) extension is used to periodically collect a backtrace. It has no run-time overhead by default. When enabled from a web request, it periodically schedules a graceful interrupt at which point it captures a backtrace.

These traces can be collected from a PHP callback and dispatched to a socket or file as-needed.

The default in `ArcLamp.php` is to send the trace to a Redis pubsub channel.

> *Arc Lamp was originally created in 2014 for [Xenon](https://github.com/facebook/hhvm/wiki/Profiling#xenon), a sampling profiler native to the HHVM engine for PHP. To use Arc Lamp with HHVM Xenon, see [arc-lamp v1.0](https://gerrit.wikimedia.org/g/performance/arc-lamp/+/1.0.0/) instead.*

### Create trace logs

[](#create-trace-logs)

In Wikimedia's production cluster, Arc Lamp's Redis server resides in the high availability "Tier 1" zone, and thus kept separate from offline performance, research, and statistics services ("Tier 2").

Each of the production web servers uses the `ArcLamp::collect` client in PHP to send traces to Redis.

The `arclamp-log` service subscribes to the Redis pubsub channel, normalizes the stack traces and write them to the relevant trace log files. The [example configuration](./arclamp-log.yaml) creates a trace log file for each hour and each day.

Within those two time periods, it segregates the trace logs by entry point of the PHP application.

For example, the MediaWiki application has `index.php`, and `rest.php` (web) and `RunJobs.php` (CLI) entry points. This results in the following trace logs:

- `daily/2019-12-21.all.log`
- `daily/2019-12-21.index.log`
- `daily/2019-12-21.rest.log`
- `daily/2019-12-21.RunJobs.log`
- …
- `hourly/2019-12-21_20.all.log`
- `hourly/2019-12-21_20.index.log`
- `hourly/2019-12-21_20.rest.log`
- `hourly/2019-12-21_20.RunJobs.log`
- …

The `arclamp-log` service is also responsible for pruning trace logs older than the configured retention period.

### Generate flame graphs

[](#generate-flame-graphs)

The `arclamp-generate-svgs` script runs at a regular interval and creates or updates the flame graph associated with each trace log file. It also maintains a *reverse* version of each flame graph.

For example:

- `daily/2019-12-21.all.svgz`
- `daily/2019-12-21.all.reversed.svgz`
- `daily/2019-12-21.index.svgz`
- `daily/2019-12-21.index.reversed.svgz`
- …
- `hourly/2019-12-21_20.all.svgz`
- `hourly/2019-12-21_20.all.reversed.svgz`
- `hourly/2019-12-21_20.index.svgz`
- `hourly/2019-12-21_20.index.reversed.svgz`
- …

The `arclamp-generate-svgs` script also removes graphs for which a trace log no longer exists.

Flamegraphs are generated using Brendan Gregg's [flamegraph.pl](https://github.com/brendangregg/FlameGraph).

Demo
----

[](#demo)

See [performance.wikimedia.org](https://performance.wikimedia.org/php-profiling/) for a live example.

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance56

Moderate activity, may be stable

Popularity33

Limited adoption so far

Community24

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~848 days

Total

2

Last Release

2000d ago

Major Versions

1.0.0 → 2.0.02020-11-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/716c86d71cbf921e7912a505f89d799de398fc0a3af0bd4c8862834b2d642bd7?d=identicon)[wikimedia](/maintainers/wikimedia)

![](https://www.gravatar.com/avatar/a91173408bf645b6ff78a309a9e55bde405d29c72e2b1ae8ec9f9df1225f76c3?d=identicon)[Krinkle](/maintainers/Krinkle)

![](https://www.gravatar.com/avatar/e020f827a3c7c6bf415cfa0f0e001ecfb9e2fdf32517016ba6e10a2261375330?d=identicon)[atdt](/maintainers/atdt)

---

Top Contributors

[![atdt](https://avatars.githubusercontent.com/u/376462?v=4)](https://github.com/atdt "atdt (15 commits)")[![Krinkle](https://avatars.githubusercontent.com/u/156867?v=4)](https://github.com/Krinkle "Krinkle (9 commits)")[![AaronSchulz](https://avatars.githubusercontent.com/u/1020708?v=4)](https://github.com/AaronSchulz "AaronSchulz (3 commits)")[![filippog](https://avatars.githubusercontent.com/u/93906?v=4)](https://github.com/filippog "filippog (2 commits)")[![bd808](https://avatars.githubusercontent.com/u/6469?v=4)](https://github.com/bd808 "bd808 (1 commits)")[![Ladsgroup](https://avatars.githubusercontent.com/u/5351225?v=4)](https://github.com/Ladsgroup "Ladsgroup (1 commits)")[![mszabo-wikia](https://avatars.githubusercontent.com/u/2721291?v=4)](https://github.com/mszabo-wikia "mszabo-wikia (1 commits)")[![paravoid](https://avatars.githubusercontent.com/u/1330796?v=4)](https://github.com/paravoid "paravoid (1 commits)")[![tstarling](https://avatars.githubusercontent.com/u/389141?v=4)](https://github.com/tstarling "tstarling (1 commits)")[![edgarsi](https://avatars.githubusercontent.com/u/6893249?v=4)](https://github.com/edgarsi "edgarsi (1 commits)")[![umherirrender](https://avatars.githubusercontent.com/u/1174884?v=4)](https://github.com/umherirrender "umherirrender (1 commits)")

---

Tags

performanceprofilingsamplingflamegraphexcimer

### Embed Badge

![Health badge](/badges/wikimedia-arc-lamp/health.svg)

```
[![Health](https://phpackages.com/badges/wikimedia-arc-lamp/health.svg)](https://phpackages.com/packages/wikimedia-arc-lamp)
```

###  Alternatives

[composer/xdebug-handler

Restarts a process without Xdebug.

2.6k397.5M90](/packages/composer-xdebug-handler)[rarst/laps

Light WordPress profiler.

567262.1k2](/packages/rarst-laps)[laracraft-tech/laravel-xhprof

Easy XHProf setup to profile your laravel application!

235321.4k](/packages/laracraft-tech-laravel-xhprof)[upscale/swoole-blackfire

Blackfire profiler integration for Swoole web-server

22114.0k8](/packages/upscale-swoole-blackfire)[koriym/xdebug-mcp

Universal PHP Xdebug MCP Server with AI-optimized debugging support

4011.6k1](/packages/koriym-xdebug-mcp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)