Installing and configuring Blackfire.io means setting up three components: the agent, the client and the PHP Probe. In the context of this book, we will be installing Blackfire.io inside our Linux for PHP container. To get more information on installing Blackfire.io on another operating system, please see the following instructions: https://blackfire.io/docs/up-and-running/installation.

We will start by installing the Blackfire agent. On the container's command-line interface, enter the following commands:

# rm /srv/www
# ln -s /srv/fasterweb/chapter_2 /srv/www
# cd /srv/www
# wget -O blackfire-agent https://packages.blackfire.io/binaries/blackfire-agent/1.17.0/blackfire-agent-linux_static_amd64

Once the download is completed, you should see the following result:

If so, please continue by typing these commands:

# mv blackfire-agent /usr/local/bin/ 
# chmod +x /usr/local/bin/blackfire-agent 

Now, we will copy a basic agent configuration file to our etc directory:

# mkdir -p /etc/blackfire 
# cp agent /etc/blackfire/ 

Here is the content of the file we just copied. It is a basic configuration file, as suggested by the Blackfire team:

[blackfire] 
; 
; setting: ca-cert 
; desc   : Sets the PEM encoded certificates 
; default: 
ca-cert= 
 
; 
; setting: collector 
; desc   : Sets the URL of Blackfire's data collector 
; default: https://blackfire.io 
collector=https://blackfire.io/ 
 
; 
; setting: log-file 
; desc   : Sets the path of the log file. Use stderr to log to stderr 
; default: stderr 
log-file=stderr 
 
; 
; setting: log-level 
; desc   : log verbosity level (4: debug, 3: info, 2: warning, 1: error) 
; default: 1 
log-level=1 
 
; 
; setting: server-id 
; desc   : Sets the server id used to authenticate with Blackfire API 
; default: 
server-id= 
 
; 
; setting: server-token 
; desc   : Sets the server token used to authenticate with Blackfire 
API. It is unsafe to set this from the command line 
; default: 
server-token= 
 
; 
; setting: socket 
; desc   : Sets the socket the agent should read traces from. Possible 
value can be a unix socket or a TCP address 
; default: unix:///var/run/blackfire/agent.sock on Linux, 
unix:///usr/local/var/run/blackfire-agent.sock on MacOSX, and 
tcp://127.0.0.1:8307 on Windows. 
socket=unix:///var/run/blackfire/agent.sock 
 
; 
; setting: spec 
; desc   : Sets the path to the json specifications file 
; default: 
spec= 

Then, create an empty file that will be used as the agent's socket:

# mkdir -p /var/run/blackfire 
# touch /var/run/blackfire/agent.sock 

Finally, we will register our agent with the Blackfire service:

# blackfire-agent -register 

Once you will have entered the last command, you will have to supply your Blackfire server credentials. These can be found in your Blackfire account at: https://blackfire.io/account#server. Once you have entered your credentials, you can start the agent by entering the following command:

# blackfire-agent start & 

After starting the agent, you should see the agent's PID number. This tells you that the agent is listening on the default UNIX socket that we created previously. In this example, the agent has a PID number of eight (8):

Once the agent is installed and configured, you can install the Blackfire client. We will install and configure the client by issuing the following commands. Let's start by downloading the binary:

# wget -O blackfire https://packages.blackfire.io/binaries/blackfire-agent/1.17.0/blackfire-cli-linux_static_amd64 

After the download is done, you should see the following message:

You can now proceed to configure the client. Enter the following commands:

# mv blackfire /usr/local/bin/ 
# chmod +x /usr/local/bin/blackfire 
# blackfire config 

After entering the final command, you will have to supply your Blackfire client credentials. These can also be found in your Blackfire account at the following URL: https://blackfire.io/account#client.

The final step in order to run Blackfire.io on our server is to install the Blackfire Probe as a PHP extension. In order to do this, please start by downloading the library:

# wget -O blackfire.so https://packages.blackfire.io/binaries/blackfire-php/1.20.0/blackfire-php-linux_amd64-php-71.so

Once the download is completed, you should get this confirmation message:

You can then copy the shared library file into your PHP extensions directory. If you are not sure of this directory's location, you can issue the following command before moving the library file into it:

# php -i | grep 'extension_dir' 
# mv blackfire.so $( php -i | grep extensions | awk '{print $3}' )

In this example, the extension's directory is /usr/lib/php/extensions/no-debug-non-zts-20160303.

You can now configure the extension in the PHP.INI file. When activating the Blackfire Probe, it is recommended that you deactivate other debugging and profiling extensions such as xdebug. Please run the following commands (alternatively, you can copy and paste the PHP.INI file that is included in our repository and already contains these modifications):

# sed -i 's/zend_extension=/usr/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so/;zend_extension=/usr/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so/' /etc/php.ini
# sed -i 's/^xdebug/;xdebug/' /etc/php.ini
# cat >>/etc/php.ini << 'EOF'

[blackfire]
extension=blackfire.so
; On Windows use the following configuration:
; extension=php_blackfire.dll

; Sets the socket where the agent is listening.
; Possible value can be a unix socket or a TCP address.
; Defaults to unix:///var/run/blackfire/agent.sock on Linux,
; unix:///usr/local/var/run/blackfire-agent.sock on MacOSX,
; and to tcp://127.0.0.1:8307 on Windows.
;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock

blackfire.agent_timeout = 0.25

; Log verbosity level (4: debug, 3: info, 2: warning, 1: error)
;blackfire.log_level = 1

; Log file (STDERR by default)
;blackfire.log_file = /tmp/blackfire.log

;blackfire.server_id =

;blackfire.server_token =
EOF 

Please complete the extension's installation and configuration by restarting PHP-FPM:

# /etc/init.d/php-fpm restart 

Let's profile our first script from the command line. You can now run the client by entering the following command on the container's CLI:

# blackfire curl http://localhost/index.php 

Once the profile is completed, you will obtain a URL and some profile statistics. If you browse to the URL, you will see the profile's call graph and get more detailed information on the profiled script:

You also have the option of installing the client as a browser plugin. In this example, we will be using the Blackfire Companion, a Google Chrome extension. To install the extension, visit the following URL with Chrome and click on the install button: https://blackfire.io/docs/integrations/chrome. Once done, it will be possible to profile the resources on the server by browsing to the page and clicking on the Blackfire Companion's icon in the toolbar and then, on the Profile button: