Blackfire recommends for monitoring and profiling web sites and applications. From development to test, staging and production Blackfire offers a unique blend of monitoring, often called APM, and profiling features. Blackfire supports PHP and Python.

Across all of your sites and testing pipelines and get actionable reports and insights that help you fix issues.

Blackfire grants detailed information on the resources your application consumes across Wall-Time, CPU, I/O, Memory, Network Calls, HTTP requests ,and SQL queries.

In addition, it can profile your code automatically and notify you whenever your application doesn’t comply with best practices for PHP, Python, and most Open-Source frameworks.

Blackfire’s features are powerful especially when running on Watch the full video tutorial.

Getting started 

On a Grid plan or Dedicated Gen 3 infrastructure 

If you have the Observability Suite, the Blackfire automated integration is enabled on Grid environments by default.

Otherwise, to enable Blackfire on your PHP or Python applications, follow the step-by-step instructions.

On Dedicated Gen 2 infrastructure 

Open a support ticket with the Blackfire Server ID and Server Token. The support team installs it for you.

To find your server credentials, navigate to your organizations list > Select an Organization > Select an Environment > Go to the Settings/Environment Credentials menu.

Note: Make sure that your CDN is configured to let Blackfire profile the code running on your servers.

Automated integration 

Observability Suite

This feature is available as part of the Observability Suite. To add the Observability Suite to your project and take advantage of this feature, contact our sales team.

The Blackfire automated integration is available for Grid environments only.

When you create a new environment, it automatically triggers the creation of a Blackfire environment with the same settings. On this Blackfire environment, you have access to all the features provided by Blackfire. This includes monitoring, profiling, alerting, and build-related features.

When a Blackfire environment is created based on a Grid environment, user access settings are replicated from the Console to Blackfire. This includes all access levels.

To access the Blackfire environment, each project user needs a Blackfire account. When a project user doesn’t already have a Blackfire account, a new one is automatically created using the user’s credentials.

You might have Blackfire variables already set on your project. In this case, the existing variables override the settings of the automated integration.

Note that to trigger the synchronization of changes to users and their access levels, you need to redeploy the environment.

Setting-up Blackfire Monitoring 

Once Blackfire is configured on your cluster, navigate to your Organizations List > Select an Organization > Go to the Organization Monitoring Usage menu, and activate Monitoring for the required environment.

A screenshot of where to find Organization Monitoring Usage

A screenshot of what is seen in Monitoring Activation

Read more in the Blackfire documentation about:

  • Configuring alerts
  • Events API
  • Monitoring third-party calls
  • Monitoring consumers
  • Advanced settings

Testing the performance of each new deployment 

Blackfire’s native integration with enables you to verify the performance of your application each time you deploy a branch, in production, staging, or development.

  1. Set up the Blackfire Builds integration.
  2. Optionally, set up an integration with your Git provider and get commit status updates from build reports.
  3. Write scenarios to test business-critical use cases.


Blackfire lets you profile your application anywhere it is deployed, including on your local development machines. Using a browser extension or CLI command, profile HTTP requests, CLI scripts, Consumers, and Daemons.

Read more in the Blackfire documentation.

Disabling Blackfire Monitoring 

Blackfire Monitoring is enabled by default for Monitoring customers.

To disable Blackfire Monitoring, create an environment variable.

In the Console, view the environment where you would like to disable Blackfire Monitoring and add the variable env:BLACKFIRE_APM_ENABLED with the value 0. Otherwise, you can use the CLI command platform variable:create --level environment --prefix env: --name BLACKFIRE_APM_ENABLED --value 0


Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDNs) 

If you are using one of these tools, you need them to let Blackfire access your servers. Read more on how to configure a bypass.

HTTP Cache configuration 

If you are using the HTTP cache with cookies, update in your .platform/routes.yaml the cookies that are allowed to go through the cache. You need to allow the __blackfire cookie name.

Something like:

    enabled: true
    cookies: ["/SESS.*/", "__blackfire"]

Reaching out to the Blackfire support 

If the above didn’t help, collect the following and send it to the Blackfire support:

  • The output of platform ssh -- php -d display_startup_errors=on --ri blackfire command
  • The Blackfire logs

Getting the Blackfire logs 

Please execute the following in the environment where you’re facing the issue:

  • platform variable:create php:blackfire.log_file --value /tmp/blackfire.log
  • platform variable:create php:blackfire.log_level --value 4
  • start a profile/build again

You can get the logs with platform ssh -- cat /tmp/blackfire.log > blackfire.log.

Disabling the Blackfire logs 

Once you are done, disable logging by running:

  • platform variable:delete php:blackfire.log_file
  • platform variable:delete php:blackfire.log_level