blackfire-php-profiler.md

Blackfire

Blackfire is a PHP profiler that helps you find bottlenecks in your code. It's a paid service, but you can get a free trial at blackfire.io.

How does Blackfire work?

Blackfire works by profiling your code as it runs.

A PHP extension must be installed into your PHP container. While the code is running, the PHP extension sends the profiling data to the (local) Blackfire agent container. The agent container processes the data and uploads it to the Blackfire.io website (where you can view the results).

How do I use Blackfire?

By default, Blackfire is commented out (not everyone uses it). To enable:

Enable Blackfire

1. Edit your .env file
   • Fill in all Blackfire environment variables
   • Enable the agent container by adding opt/blackfire.yml to the COMPOSE_FILE list
2. Enable the Blackfire extension for PHP by uncommenting the Install Blackfire lines in php/xx/Dockerfile (where "xx" is the version of PHP you're enabling Blackfire for)
3. Rebuild and restart your containers:

docker compose build --pull --no-cache
docker compose up -d

Run a profile

1. Sign into blackfire.io
2. Install the Blackfire extension in your browser. Here's one for Google Chrome
3. Navigate to the site/page you'd like to profile
4. Click the 'Profile' button in the Blackfire browser extension

Troubleshooting common Blackfire issues

1. Check the Blackfire extension is installed in your PHP container. Use phpinfo() to confirm.
2. Check the Blackfire agent (container) is running. Use docker compose ps to confirm.
3. Check your Blackfire environment variables are correct in .env.

How do I interpret the results?

The Blackfire documentation should have the answers you are looking for.