Blackfire has built-in support for projects. The integration is made simpler as Blackfire agent and probe are installed and enabled by default on all accounts.

Blackfire server credentials and the file should be configured out of the box for Obervability Suite customers. Those steps may then be ignored. Blackfire integration appears in the project settings in console.

Set the Blackfire server credentials as environment variables (run this command from the root directory of your project):


You may also use your console

The client credentials are required to trigger profiles with the CLI from your environments. In this case, set the client credentials as environment variables (run this command from the root directory of your project):


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"

The configuration of your application depends on its type.

PHP Application

Add the blackfire PHP extension to the project file:

        - blackfire

Python Application

Your application must have the Blackfire Probe installed as a pip dependency.

Update your file to use the blackfire-python binary to start your webserver:

        socket_family: unix
    # Commands are run once after deployment to start the application process.
        # Replace "my_app.wsgi" by your actual WSGI script.
        start: "blackfire-python gunicorn -w 4 -b unix:$SOCKET my_app.wsgi:application"

To enable Blackfire builds on all of your environments each time a branch is deployed (after a push, merge, or redeploy event), you need to set up a specific webhook.

To do so, follow these steps:

  1. Install the platform utility
  2. Run the following command:

The command asks several questions. Hit enter to accept the default for all of them. If you get a permission error, ask a project admin to upgrade your account or ask someone who is an admin to run this command.

Now, whenever you push to a environment, Blackfire will automatically trigger a build for this specific environment. Blackfire scenarios will be run for all your pull requests.

If you are using GitHub and if you have setup the synchronization between GitHub and, don't forget to configure the Blackfire GitHub notification channel. That way, Blackfire will post a status on your GitHub pull requests.

Here is a full video tutorial to get you started with the integration of the three services: