Docker

If you are using Docker, 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 on the Docker host machine:

Please log in or sign up first:

or

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

Docker Compose

Within a docker-compose context, consider using the following snippet to declare the Blackfire agent as a service:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
version: '3'
services:
  blackfire:
    image: blackfire/blackfire
    ports: ["8707"]
    environment:
        # Exposes BLACKFIRE_* environment variables from the host
        BLACKFIRE_SERVER_ID: ~
        BLACKFIRE_SERVER_TOKEN: ~
        BLACKFIRE_CLIENT_ID: ~
        BLACKFIRE_CLIENT_TOKEN: ~

CLI Client for HTTP Profiling

When profiling remote servers, you may use the Blackfire CLI tool which is embedded in Blackfire Docker image.

Assuming you configured blackfire service as explained above, you may use the following command:

1
docker-compose exec blackfire blackfire curl http://example.com

To make it less verbose, create an alias:

1
2
alias blackfire-curl='docker-compose exec blackfire blackfire curl'
blackfire-curl http://example.com/

Debugging the Agent

By default, the agent is quiet and does not produce logs. To debug problems, increase the log verbosity by setting BLACKFIRE_LOG_LEVEL to 4:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
version: '3'
services:
  blackfire:
    image: blackfire/blackfire
    environment:
        BLACKFIRE_LOG_LEVEL: 4
        BLACKFIRE_SERVER_ID: ~
        BLACKFIRE_SERVER_TOKEN: ~
        BLACKFIRE_CLIENT_ID: ~
        BLACKFIRE_CLIENT_TOKEN: ~

You may then tail the logs with docker-compose:

1
docker-compose logs -f blackfire

Raw Docker Image

The 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

CLI Client for HTTP Profiling

When profiling remote servers, you may use the Blackfire CLI tool which is embedded in Blackfire Docker image:

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

To make it less verbose, create an alias:

1
2
alias blackfire-curl='docker run -it --rm -e BLACKFIRE_CLIENT_ID -e BLACKFIRE_CLIENT_TOKEN blackfire/blackfire blackfire curl'
blackfire-curl http://example.com/

Using the Probe

To install the Blackfire Probe in your application container, read the following guides, depending on your runtime: