Day 6 - Installation

Up until now, we have used the Blackfire Google Chrome extension to profile a project hosted on Blackfire servers. This was the easiest way to get us started, but now it's time for you to use Blackfire on your own projects.

Infrastructure

Blackfire is a SaaS product. The blackfire.io website allows you to manage your Blackfire project configurations, profiles, and builds. Still, you need to install some software:

  • The Blackfire PHP C extension, the probe, instruments PHP code and gathers data about runtime behavior. The probe knowns how and when to instrument the code, and how to extract data out of the PHP runtime.
  • The Blackfire agent handles most of the intensive operations (like cleaning, anonymizing, and compressing the data) before sending each profile to Blackfire's servers. It uses a socket to communicate with the probe and HTTPS to send data to Blackfire.

When you are manually triggering Blackfire profiles, you will do so using one of the following tools:

  • The Blackfire companion is a Google Chrome extension that makes it easy to generate profiles from the browser.
  • The Blackfire client, which comes bundled with the agent, lets you generate profiles from the command line. It gives more flexibility and has more features than the companion and will be the covered in a future chapter.

Blackfire servers store some data about your code execution. You can learn about data privacy in our FAQ and in this blog post.

Installation on your Local Computers

Blackfire is supported on many platforms. Install it by following the instructions for your operating system:

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 or IonCube.

Zend Thread Safety (ZTS)

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

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 or IonCube.

Zend Thread Safety (ZTS)

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

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 or IonCube.

Zend Thread Safety (ZTS)

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

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.16.0/blackfire-php-windows_x'.(PHP_INT_SIZE-4?64:86).'-php-'.(10*PHP_VERSION).(PHP_ZTS?'':'_nts').'.dll';

    If you are using Ubuntu on Windows 10, due to timing syscalls issues, please follow the manual instructions using the Windows Subsystem for Linux OS.

    WAMP may provide two different PHP configurations for CLI and Apache. Apache may use a ZTS version of PHP whereas the CLI uses a NTS version, be careful. To make Blackrire work correctly, you need to download both ZTS and NTS versions of the extension and configure the php.ini files accordingly.

  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. Rename the downloaded blackfire[...].dll to php_blackfire.dll
  4. Move the php_blackfire.dll to your PHP extensions directory.
  5. Create the probe configuration file.
  6. 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 or IonCube.

Zend Thread Safety (ZTS)

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

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.

  6. 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 or IonCube.

Zend Thread Safety (ZTS)

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

Installation on Staging, Testing, and Production

When deploying code to testing, staging, or production environments, you can use the same installation procedure as in the previous section, or use Blackfire's integrations with Chef, Puppet, Ansible, or Docker.

Next Steps

You are now ready to profile your very own projects!

First, validate your installation by generating a profile with the companion. If you have any problems, read our troubleshooting guide or contact our support.

Once you're able to generate a profile, use the profiling methodology we described in the previous chapters to run Blackfire on your applications. I'm very confident that for any non-trivial codebase, you will find some optimizations.

Found an optimization? Share it with us on Twitter and use the #blackfireio hashtag.