Installing Blackfire

Installing Blackfire

Installing and updating Blackfire should be a quick process. This document will guide you through the steps.

For a better experience, you should or .

Tell us what you want to do:

I want to Blackfire
on
which uses
for the language.

To start using Blackfire, we are going to install the following:

  • A language extension;
  • An agent to communicate with Blackfire's servers;
  • A profiling client (a browser extension or a CLI tool).

Configure the Debian Repository

Blackfire uses a custom Debian repository to distribute its packages; it is compatible with most Debian-based distributions like Ubuntu and Linux-Mint.

  1. Register the packagecloud key:
    wget -q -O - https://packages.blackfire.io/gpg.key | sudo apt-key add -
  2. Add the repository to Debian source list:
    echo "deb http://packages.blackfire.io/debian any main" | sudo tee /etc/apt/sources.list.d/blackfire.list
  3. Update the repositories:
    sudo apt update

Install the Packages

  1. Install the blackfire-agent package:
    sudo apt install blackfire-agent

Configure the Agent
An agent has been detected An upgrade is available No agents have been detected

  1. This command asks for some Blackfire server credentials, log in or sign up now to get them:

    or

  2. Restart the agent service:
    sudo /etc/init.d/blackfire-agent restart

    During the agent installation, a new /etc/init.d/blackfire-agent service was created to start, stop, and restart it. Whenever you modify the agent configuration, restart it.

  3. If something goes wrong, check out the log file generated by default in /var/log/blackfire/agent.log. Change the log file or the log level in the agent configuration file.)

Install the PHP Probe

  1. Install the blackfire-php package:
    sudo apt install blackfire-php
  2. Restart your web server or PHP-FPM.
  3. Check that there are no errors in the logs. To debug problems, change the log level and the log file in the probe configuration.

Known incompatibilities

PHP will likely crash when Blackfire is used when one of the following extensions is also enabled: XHProf, Pinba, and Suhosin.

If XDebug is installed, the PHP engine may not behave as expected; consider disabling it when profiling.

Install a Profiling Client

To profile applications, you need to install a profiling client:

  • Profile from a browser via our browser extensions (Web applications only).

  • Profile from the command line via the blackfire tool (Web applications, APIs, command line tools, daemons, and more).

    Configure it with your personal credentials:

    blackfire config --client-id=CLIENT_ID --client-token=CLIENT_TOKEN

Start Profiling