Installation

Installing Blackfire should take less than 5 minutes and this document will guide you through the steps:

  1. Check that your system meets Blackfire's requirements;
  2. Install the PHP extension and the agent;
  3. Start profiling your applications.

If you get stuck in the process, have a look at the Troubleshooting section or contact our support.

Before starting, it's important to understand the main components of Blackfire.

Pre-Requisites

Before installing Blackfire, make sure that your system meets these technical requirements:

  • The Agent, and the Client work on Linux, MacOS X, FreeBSD and Windows;
  • The Probe works on Linux, MacOS X, FreeBSD with PHP 5.3 to 7.1. On Windows , the Probe works with PHP 5.4 to 7.1
  • The Companion is currently only available for Google Chrome;
  • The Website works on all browsers but Internet Explorer.

Installation

Quick Links:

Configuring 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 -O - https://packagecloud.io/gpg.key | sudo apt-key add -
  2. Add deb http://packages.blackfire.io/debian any main to /etc/apt/sources.list.d/blackfire.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-get update

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

  1. Install the blackfire-agent package:
    sudo apt-get install blackfire-agent
  2. Configure your Blackfire credentials:
    sudo blackfire-agent -register

    This command will ask for your Blackfire server credentials, log in or sign up now:

    or

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

    After registering the agent, and whenever you modify its configuration, you have to restart its service:
    sudo /etc/init.d/blackfire-agent restart

If something goes wrong, check out the log file generated by default in /var/log/blackfire/agent.log (you can changethe log file and the log level in the agent configuration.)

Installing the Blackfire CLI tool

  1. Install the blackfire-agent package:
    sudo apt-get install blackfire-agent
  2. Run the config command to initialize the client:
    blackfire config

    This command will ask for your Blackfire client credentials, log in or sign up now:

    or

To profile from your browser, install the Google Chrome extension.

Installing the PHP Probe

  1. Install the blackfire-php package:
    sudo apt-get install blackfire-php
  2. To finish the probe installation, restart your web server or PHP-FPM and check that there are no error messages.

To debug problems, you can change the log level and the log file in the probe configuration.

Known incompatibilities

Please note that PHP compiled with debug are not supported and that the Probe may conflict with XDebug or XHProf; disable those extensions when enabling the Probe.

The Probe conflicts with some PHP extensions like Pinba.

Zend Thread Safety (ZTS)

Support for ZTS versions of PHP on MacOS X is currently in beta.

Quick Links:

Configuring the Red Hat Repository

Blackfire uses a custom Red Hat repository to distribute its packages; it is compatible with most Red Hat-based distributions like Fedora and CentOS.

  1. Install the pygpgme package used to verify GPG signatures:
    sudo yum install pygpgme
  2. Add the repository to the configuration:
    wget -O - "http://packages.blackfire.io/fedora/blackfire.repo" | sudo tee /etc/yum.repos.d/blackfire.repo
Cannot retrieve repository metadata

With old releases, you can encounter the following message Gpg Keys not imported, cannot verify repomd.xml for repo blackfire

This is often due to the lack of pygpgme on those platforms and can be fixed by editing /etc/yum.repos.d/blackfire.repo and changing the value of repo_gpgcheck to 0

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

  1. Install the blackfire-agent package:
    sudo yum install blackfire-agent
  2. Configure your Blackfire credentials:
    sudo blackfire-agent -register

    This command will ask for your Blackfire server credentials, log in or sign up now:

    or

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

    After registering the agent, and whenever you modify its configuration, you have to restart its service:
    sudo /etc/init.d/blackfire-agent restart

If something goes wrong, check out the log file generated by default in /var/log/blackfire/agent.log (you can changethe log file and the log level in the agent configuration.)

Installing the Blackfire CLI tool

  1. Install the blackfire-agent package:
    sudo yum install blackfire-agent
  2. Run the config command to initialize the client:
    blackfire config

    This command will ask for your Blackfire client credentials, log in or sign up now:

    or

To profile from your browser, install the Google Chrome extension.

Installing the PHP Probe

  1. Install the blackfire-php package:
    sudo yum install blackfire-php
  2. To finish the probe installation, restart your web server or PHP-FPM and check that there are no error messages.

To debug problems, you can change the log level and the log file in the probe configuration.

Known incompatibilities

Please note that PHP compiled with debug are not supported and that the Probe may conflict with XDebug or XHProf; disable those extensions when enabling the Probe.

The Probe conflicts with some PHP extensions like Pinba.

Zend Thread Safety (ZTS)

Support for ZTS versions of PHP on MacOS X is currently in beta.

Quick Links:

Configuring Homebrew

Blackfire provides a homebrew tap to distribute its packages. Make sure that you have brew installed in your system or download and install it.

  1. Add the Blackfire repository:
    brew tap blackfireio/homebrew-blackfire

If you are not using Homebrew and don't want to install Homebrew, use the manual install procedures.

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

  1. Install the blackfire-agent package:
    brew install blackfire-agent
  2. Configure your Blackfire credentials:
    sudo blackfire-agent -register

    This command will ask for your Blackfire server credentials, log in or sign up now:

    or

  3. Register the blackfire-agent service:
    ln -sfv /usr/local/opt/blackfire-agent/*.plist ~/Library/LaunchAgents
  4. Then load it for the first time:
    launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.blackfire-agent.plist
  5. In order to restart the service, and whenever you modify its configuration, unload it:
    launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.blackfire-agent.plist
    Then load it again:
    launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.blackfire-agent.plist

If something goes wrong, check out the log file generated by default in /usr/local/var/log/blackfire/agent.log (you can changethe log file and the log level in the agent configuration.)

Installing the Blackfire CLI tool

  1. Install the blackfire-agent package:
    brew install blackfire-agent
  2. Run the config command to initialize the client:
    blackfire config

    This command will ask for your Blackfire client credentials, log in or sign up now:

    or

To profile from your browser, install the Google Chrome extension.

Installing the PHP Probe

    Homebrew-PHP users

    If you use Homebrew-PHP, execute the command below replacing 56 by the installed PHP version: 

    brew install blackfire-php56

    Non Homebrew-PHP users (MacOS X native PHP, MAMP, MAMP Pro, etc)

    When using a PHP different than the one shipped with MacOS X, please ensure the php binary from your PATH is the one you want to use Blackfire on. For example if you are using MAMP, when you run which php, the path returned should mention MAMP.

    Please also note you may have to edit two php.ini files, one for the web and one for the command line.

    For MAMP Pro users, please note that you should not directly edit the php.ini file used in web mode. Instead you need to edit the template from the MAMP Pro interface.

    Execute the command below replacing 56 by the installed PHP version and follow the instructions in the command output: 

    brew install blackfire-php56 --without-homebrew-php

    Users of PHP with ZTS enabled

    Append -zts on package name: 

    brew install blackfire-php56-zts
  1. To finish the probe installation, restart your web server or PHP-FPM and check that there are no error messages.

To debug problems, you can change the log level and the log file in the probe configuration.

Known incompatibilities

Please note that PHP compiled with debug are not supported and that the Probe may conflict with XDebug or XHProf; disable those extensions when enabling the Probe.

The Probe conflicts with some PHP extensions like Pinba.

Zend Thread Safety (ZTS)

Support for ZTS versions of PHP on MacOS X is currently in beta.

Quick Links:

In order to be able to use the blackfire curl command, you need to have curl.exe installed on your system and available in your PATH environment variable.
You can download it on the official cURL website.

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

  1. Download the best agent binary for your platform:
  2. Move both the downloaded blackfire-agent.exe and blackfire.exe files to a directory (e.g. C:\Programs\Blackfire) and add it to your PATH environment variable.
  3. Create the agent configuration file.
  4. Configure your Blackfire credentials:
    blackfire-agent -register

    This command will ask for your Blackfire server credentials, log in or sign up now:

    or

  5. Run the agent using the blackfire-agent.exe command.

Installing the Blackfire CLI tool

  1. Download the best agent binary for your platform:
  2. Move both the downloaded blackfire-agent.exe and blackfire.exe files to a directory (e.g. C:\Programs\Blackfire) and add it to your PATH environment variable.
  3. Create the agent configuration file.
  4. Run the config command to initialize the client:
    blackfire config

    This command will ask for your Blackfire client credentials, log in or sign up now:

    or

To profile from your browser, install the Google Chrome extension.

Installing the PHP Probe

  1. Download the "best" probe library for your platform:
    Alternatively, copy/paste the following script in a PHP file and run it to get the URL of your DLL file: 
    <?php echo 'packages.blackfire.io/binaries/blackfire-php/1.14.1/blackfire-php-windows_x'.(PHP_INT_SIZE-4?64:86).'-php-'.(10*PHP_VERSION).(PHP_ZTS?'':'_nts').'.dll';
  2. Determine your PHP extensions directory by using in the CLI: 
    php -i | grep 'extension_dir'

    When using a PHP different than the one of your server, please ensure the php binary from your PATH is the one you want to use Blackfire on.

  3. Move the downloaded blackfire[...].dll corresponding to your PHP version and architecture to this directory.
  4. Create the probe configuration file.
  5. To finish the probe installation, restart your web server or PHP-FPM and check that there are no error messages.

To debug problems, you can change the log level and the log file in the probe configuration.

Known incompatibilities

Please note that PHP compiled with debug are not supported and that the Probe may conflict with XDebug or XHProf; disable those extensions when enabling the Probe.

The Probe conflicts with some PHP extensions like Pinba.

Zend Thread Safety (ZTS)

Support for ZTS versions of PHP on MacOS X is currently in beta.

Quick Links:

In order to be able to use the blackfire curl command, you need to have curl installed on your system and available in your PATH.

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

Please use the manual installation procedure.

Installing the Blackfire CLI tool

  1. Please use the manual installation procedure.
  2. Run the config command to initialize the client:
    blackfire config

    This command will ask for your Blackfire client credentials, log in or sign up now:

    or

To profile from your browser, install the Google Chrome extension.

Installing the Probe

Please use the manual installation procedure.

Blackfire is natively available on many platforms; Configuration is easier for them:

Besides supporting traditional way of installing Blackfire, you might be interested in the integrations with the following tools:

If you need to install the stack manually because every other installation methods failed, please contact us and mention your platform and PHP version.

In the meantime, continue the following steps and you will be guided through manual installation.

You are strongly advised to use the other installation methods available if possible as they give you seamless upgrade methods.

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

  1. Download the "best" agent binary for your platform:
  2. Move the downloaded blackfire-agent file to a directory in your path (e.g. /usr/local/bin) and make the file executable.
  3. Create the agent configuration file.
  4. Configure your Blackfire credentials:
    sudo blackfire-agent -register

    This command will ask for your Blackfire server credentials, log in or sign up now:

    or

    5. You can manually launch the agent each time you want to profile a page or a script by using blackfire-agent, but it is better to register a service in order to have it launched automatically and avoid any troubles.

    Please refer to your OS documentation to determine how to register a service (eg. using upstart, init.d, systemd or launchtl.)

If something goes wrong, check out the log file generated by default in /var/log/blackfire/agent.log (you can changethe log file and the log level in the agent configuration.)

Installing the Blackfire CLI tool

  1. Download the "best" client binary for your platform:
  2. Run the config command to initialize the client:
    blackfire config

    This command will ask for your Blackfire client credentials, log in or sign up now:

    or

To profile from your browser, install the Google Chrome extension.

Installing the PHP Probe

  1. Download the "best" probe library for your platform:
  2. Determine your PHP extensions directory: 
    php -i | grep 'extension_dir'

    When using a PHP different than the one shipped with MacOS X, please ensure the php binary from your PATH is the one you want to use Blackfire on. For example if you are using MAMP on MacOS X, when you run which php, the path returned should mention MAMP.

    Please also note you may have to edit two php.ini files, one for the web and one for the command line.

    For MAMP Pro users, please note that you should not directly edit the php.ini file used in web mode. Instead you need to edit the template from the MAMP Pro interface.

  3. Move the downloaded blackfire.so file to this directory.
  4. Create the probe configuration file.

    5. On Linux systems, check that the /var/run/blackfire/ directory exists and is accessible by both the Agent and the Probe.
    For MacOS users, check that the /usr/local/var/run/ directory exists and is accessible by both the Agent and the Probe.

  5. To finish the probe installation, restart your web server or PHP-FPM and check that there are no error messages.

To debug problems, you can change the log level and the log file in the probe configuration.

Known incompatibilities

Please note that PHP compiled with debug are not supported and that the Probe may conflict with XDebug or XHProf; disable those extensions when enabling the Probe.

The Probe conflicts with some PHP extensions like Pinba.

Zend Thread Safety (ZTS)

Support for ZTS versions of PHP on MacOS X is currently in beta.