Docker

Integrating Blackfire.io with Docker Compose

Blackfire Integration with Docker is fully covered in the official documentation: https://blackfire.io/docs/integrations/docker
But here is a short summary on how you add support of Blackfire to your project Docker Compose setup.

Pre-requisites

1. You’ll need to have a Blackfire account

Blackfire stores all profiles on their servers so you need access to them.
You will be given a Server ID, Server Token, Client ID and Client Token, which you will need later for configuration. These could be found here: https://blackfire.io/my/settings/credentials.

2. You’ll (most probably) need a Blackfire Companion in your browser

It connects to your account and helps starting profiling directly from your browser. Install and configure it as described here:

Integrate Blackfire with your Docker Compose

1. Add Blackfire Agent to your network

Blackfire Agent sends your local profiling results to the Blackfire servers. The easiest way is to add it as a separate container using the official blackfire/blackfire image:

docker-compose.yaml

1
2
3
4
5
services:
  ...
  blackfire_agent:
    image: blackfire/blackfire
    restart: always

The Agent needs Server ID and Server Token to communicate with Blackfire API. You can configure it using environment variables.

docker-compose.override.yaml

1
2
3
4
5
6
7
services:
  ...
  blackfire_agent:
    environment:
      ...
      BLACKFIRE_SERVER_ID: <Your Server ID>
      BLACKFIRE_SERVER_TOKEN: <Your Server Token>

Find out more about docker-compose.override.yaml file here: Using override file.

2. Add Blackfire PHP Probe and CLI tool to your application container

Blackfire Probe collects the execution stats and sends it to the Agent.

Considering that we base on PHP-FPM image add the following lines to your php Dockerfile:

Dockerfile

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
FROM php:7.2-fpm

...

# You will need these to run commands below
RUN apt-get update && apt-get install -y \
    wget \
    gnupg2

...

# Install Blackfire CLI tool and PHP Probe
RUN wget -q -O - https://packages.blackfire.io/gpg.key | apt-key add -
RUN echo "deb http://packages.blackfire.io/debian any main" | tee /etc/apt/sources.list.d/blackfire.list
RUN apt-get update && apt-get install -y blackfire-agent blackfire-php

...

The CLI tool needs Client ID and Client Token to communicate with Blackfire API. You can configure it using environment variables.

docker-compose.override.yaml

1
2
3
4
5
6
7
services:
  ...
  your_php_app_service:
    environment:
      ...
      BLACKFIRE_CLIENT_ID: <Your Client ID>
      BLACKFIRE_CLIENT_TOKEN: <Your Client Token>

3. Point your PHP Probe to your Agent

Add the zz-blackfire.ini file to your php-related configuration files in the repo. In my case it’s: docker/local/php/conf/zz-blackfire.ini.
Put the following contents to it:

zz-blackfire.ini

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
; priority=90
; ?priority=90
[blackfire]
extension=blackfire.so
; Default port is 8707.
; You can check the actual configuration by running (see "socket" setting):
;   docker-compose exec blackfire_agent blackfire-agent -d
blackfire.agent_socket = tcp://blackfire_agent:8707
blackfire.agent_timeout = 0.25

;Sets fine-grained configuration for Probe.
;This should be left blank in most cases. For most installs,
;the server credentials should only be set in the agent.
;blackfire.server_id =

;Sets fine-grained configuration for Probe.
;This should be left blank in most cases. For most installs,
;the server credentials should only be set in the agent.
;blackfire.server_token =
;blackfire.log_level = 3
;blackfire.log_file = /tmp/blackfire.log

Here we set the agent_socket to tcp://blackfire_agent:8707, where “blackfire_agent” is the name of your Agent’s service added above and “8707” is the default port on which the Agent is listening.

Then mount this file into your application container:

docker-compose.yaml

1
2
3
4
5
6
services:
  your_php_app_service:
    ...
    volumes:
      ...
      - ./docker/local/php/conf/zz-blackfire.ini:/usr/local/etc/php/conf.d/zz-blackfire.ini

That’s it

Re-build your containers and you are good to go.

Profiling from CLI

Blackfire CLI tool can be used to profile your PHP CLI commands or simple scripts. We installed it to the application container so here is how you run it:

1
docker-compose exec your_php_app_service blackfire run bin/magento list

If you need this often I’d suggest to create a bin helper.

Profiling with PHP SDK

With Blackfire PHP SDK you can trigger profiling from PHP code and profile a specific piece of code in your app. You will also have access to profiling results programmatically, which will give you more flexibility to analyze them.

PHP SDK same as CLI tool uses Client ID and Client Token configuration from environment variables.

Add Blackfire PHP SDK as a dev dependency to your project

1
composer require blackfire/php-sdk --dev

Or add the latest package version manually to your composer.json:

composer.json

1
2
3
"require-dev": {
  "blackfire/php-sdk": "^1.18"
}

That’s it.

The simplest way to profile a piece of code is:

1
2
3
4
5
6
$blackfire = new \Blackfire\Client();
$probe = $blackfire->createProbe();

// some PHP code you want to profile

$profile = $blackfire->endProbe($probe);

After putting this just open a page in browser or run the CLI command, no need to run profiling with a Companion.