Docker

If you are using Docker on your server infrastructure, you might want to use the official Blackfire Docker image to run the Agent and get some inspiration from our recipes to install the Client and the Probe.

To ease the process of using Blackfire with Docker, define these environment variables:

Please log in or sign up first:

or

From now on, we assume that these environment variables are set up properly.

Running the Agent

The blackfire/blackfire image is the fastest way to get the Blackfire agent running:

1
docker run --name="blackfire" -d -e BLACKFIRE_SERVER_ID -e BLACKFIRE_SERVER_TOKEN blackfire/blackfire

The image exposes port 8707 to allow connection to the agent from a PHP image configured with Blackfire (see below).

To upgrade the Blackfire image, pull the newest image from Docker and restart the agent container:

1
docker pull blackfire/blackfire

You can check the version of a running Blackfire container with the following command:

1
docker exec blackfire blackfire-agent -v

Enabling the PHP Probe

Before being able to profile, you need to add the Probe to your Docker PHP image. Here is an example of a Dockerfile based on the official Docker PHP image:

1
2
3
4
5
6
7
FROM php:5.6-apache

RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION;") \
    && curl -A "Docker" -o /tmp/blackfire-probe.tar.gz -D - -L -s https://blackfire.io/api/v1/releases/probe/php/linux/amd64/$version \
    && tar zxpf /tmp/blackfire-probe.tar.gz -C /tmp \
    && mv /tmp/blackfire-*.so $(php -r "echo ini_get('extension_dir');")/blackfire.so \
    && printf "extension=blackfire.so\nblackfire.agent_socket=tcp://blackfire:8707\n" > $PHP_INI_DIR/conf.d/blackfire.ini

This example targets official PHP Docker images, if you are using a custom image, you'll probably want to adapt it.

A common mistake while adapting it for custom images is the lack of PHP_INI_DIR. In such case you can easily get it by using php -i | grep "additional .ini".

An alternative solution is to simply proceed with the regular Blackfire installation using the package manager available with your base image.

Caution

For Alpine variants of the PHP Docker images, please replace linux with alpine in the URL of the downloaded file.

Build your container as usual:

1
docker build -t php-blackfire .

When running the PHP container, you need it to be on the same docker network as the blackfire one so that the Probe is able to communicate with the Agent:

1
2
3
4
5
6
docker network create myphp-app
docker run -d -p 8080:80 \
    --net=myphp-app \
    -v `pwd`:/var/www/html \
    php-blackfire
docker network connect myphp-app blackfire

To upgrade the probe, rebuild your PHP container and relaunch it (you might need to use the --no-cache option to force the download of the latest Probe version).

If you are using Docker prior to version 1.10, or if you don't want to define yourself a network, you need to use docker links:

1
2
3
4
docker run -d -p 8080:80 \
    --link blackfire:blackfire \
    -v `pwd`:/var/www/html \
    php-blackfire

Within a docker-compose context, you should probably take inspiration of the following snippet to connect your PHP container and the agent together:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
version: '2'
services:
  php:
    build: .
    ports:
      - "8080:80"
  blackfire:
    image: blackfire/blackfire
    environment:
        # Exposes the host BLACKFIRE_SERVER_ID and TOKEN environment variables.
        - BLACKFIRE_SERVER_ID
        - BLACKFIRE_SERVER_TOKEN
        # You can also use global environment credentials :
        # BLACKFIRE_SERVER_ID: SERVER-ID
        # BLACKFIRE_SERVER_TOKEN: SERVER-TOKEN

Using the Client for HTTP Profiling

When profiling remote servers, you only need to use the Blackfire CLI tool. Instead of installing it via your platform preferred channel, you can use the blackfire/blackfire Docker image that already contains everything you need.

Then, use the blackfire/blackfire image to profile any URL where Blackfire is enabled:

1
2
3
4
5
docker run -it --rm \
    -e BLACKFIRE_CLIENT_ID \
    -e BLACKFIRE_CLIENT_TOKEN \
    blackfire/blackfire blackfire \
    curl http://example.com/

To make it less verbose, create an alias:

1
alias blackfire-curl='docker run -it --rm -e BLACKFIRE_CLIENT_ID -e BLACKFIRE_CLIENT_TOKEN blackfire/blackfire blackfire curl'

Use the alias like this:

1
blackfire-curl http://example.com/

Using the Client for CLI Profiling

When profiling command line scripts, the process is slightly different. You run blackfire run which in the end runs an embedded agent and wraps you PHP script with the required environment variables. Therefore, in this configuration you don't need to (and can't) use a blackfire/blackfire image. Instead, you need to fetch and use the blackfire client binary inside your PHP container.

Here is an example of a Dockerfile based on the official Docker PHP image that retrieves the client at build time:

1
2
3
4
5
6
FROM php:5.6-apache

RUN mkdir -p /tmp/blackfire \
    && curl -A "Docker" -L https://blackfire.io/api/v1/releases/client/linux_static/amd64 | tar zxp -C /tmp/blackfire \
    && mv /tmp/blackfire/blackfire /usr/bin/blackfire \
    && rm -Rf /tmp/blackfire

Build your container as usual:

1
docker build -t php-blackfire .

When running the PHP container, you need to expose a BLACKFIRE_SERVER_ID and a BLACKFIRE_SERVER_TOKEN environment variables to allow the client to communicate with the Blackfire.io API.

You can now directly execute blackfire run php myscript.php within your PHP container.

Debugging the Agent and the PHP Probe

By default, the probe is quiet and do not produce logs. To debug problems, pass -e BLACKFIRE_LOG_LEVEL=4 to the docker run command, and tail the logs via Docker:

1
docker logs -f blackfire
1
docker logs -f PHP_CONTAINER_ID