To be able to use Blackfire, add the probe to your Docker PHP image. Here is an
example of a Dockerfile based on the official Docker PHP image:
Choose the snippet corresponding to the base system you are using
(Linux or Alpine).
Base image
This example targets official PHP Docker images. If you are using a custom image, you probably need to adapt it.
A common mistake while adapting it for custom images is the lack of
PHP_INI_DIR. In such case you can get it by using php -i | grep
"additional .ini".
An alternative solution is to proceed with the regular Blackfire installation using the package manager available with your base image OS.
If you are using a zts (`Zend Thread Safety`) version of PHP, please add
-zts to the version name.
Build your container as usual:
1
Upgrading
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 use docker compose, you can connect your PHP container and the
agent using the following snippet:
When profiling command line scripts, the process is slightly different
than for HTTP requests.
You execute blackfire run which in the end runs an embedded agent and
wraps your PHP script with the required environment variables. Therefore, in
this configuration, you do not need to (and cannot) use the
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 7
Build your container as usual:
1
With exposed BLACKFIRE_CLIENT_ID and BLACKFIRE_CLIENT_TOKEN environment
variables, you can now directly execute blackfire run php myscript.php
within your PHP container.
Recommended: To explicitly define which
environment the profile must be sent
to, use the --env=<ENV_UUID> parameter.
v2.14.0+ of the unified Agent and Client:
when no target environment is specified, the Agent uses the
BLACKFIRE_SERVER_ID environment variable to determine where to send the
profile.
When no target environment is specified or implicitly discovered, the profile
is sent to the personal sandbox environment of the user whose
personal credentials (BLACKFIRE_CLIENT_ID
and BLACKFIRE_CLIENT_TOKEN) were used. Only that user can then access
the profile from /my/profiles.
To explicitly specify your personal sandbox environment, use
--env="My Environment"
By default, the Probe is quiet and does not produce logs. To debug issues,
pass -e BLACKFIRE_LOG_LEVEL=4 to the docker run command, and tail the
logs via Docker:
1
To install the Blackfire Agent using Docker, please refer to the dedicated documentation page.