Clarifying how things work

Blackfire works on the back-end. “Profiles” are measurements of PHP processes (HTTP, CLI, daemons), which are automatically instrumented by the use of a special Blackfire HTTP header, or by the use of our SDK.

Profiles can be done manually, via the browser extension or the CLI. And they can be done automatically, via our integration with Magento Cloud and other tools.

The Blackfire stack on Magento Cloud

Blackfire's stack includes two components which need to be installed on the client servers: the Probe (a PHP extension), and the Agent (daemon).

In Magento Cloud, only the Probe requires some configuration. The Probe is installed by default in all containers. The Agent is maintained solely by Magento.


In order to have Blackfire fully up-and-running, there are a couple of mandatory steps:

  • To have configured the “server credentials” on Magento Cloud machines (integration, staging and production)
  • To have configured the integration web-hooks, so that profiling starts automatically each time an environment is redeployed (integration, staging and production)
  • To have configured any system on the way between the Blackfire servers and the Magento Cloud machines so that Blackfire request hit the server: firewall, proxies, CDNs,…

Default configuration

The magento-cloud blackfire:setup command does the first two steps with a default behavior:

  • It creates Blackfire environment variables on production, staging and integration (with inheritance on this one) branches, and set automatically the related server credentials as values for those variables. That enables manual profiling and allows automated profiling as well.
  • It creates integration web-hooks on each branch, so that a Blackfire build is fired every time a branch is redeployed (hereby enabling to integrate back in git UIs to have Blackfire builds give a commit status)

Also, the default procedure when a project is created on Magento Cloud is to setup Fastly correctly so that Blackfire requests are not cached.


  • For unknown reasons, we have customers in the past that didn’t get Blackfire pre-installed. The magento-cloud blackfire:setup command therefore was useless. Only Magento can fix this (please reach out to their support);
  • For unknown reasons, we have customers in the past that didn’t get Fastly configured properly. Only Magento/ can fix this (please reach out to their support);
  • On some customers, it happened that other systems than Fastly were used (CloudFlare,…). Each system on the way between Blackfire and the machines must let Blackfire through;
  • Some customers don’t have a standard naming of branches, which may cause the magento-cloud blackfire:setup  command to malfunction. We have submitted an update of that command to Magento, but do not have control over that code base and the releasing workflow. It still is possible to manually add the environment variables, as well as the integration hooks;
  • A common last mile issue is to get builds with the following error: “SSL certificate problem: self signed certificate Download failed on /”. Here is a guide to quickly fix it;
  • You might see a warning on some profiles saying "This profile was generated with and outdate Blackfire probe". You can safely discard it. It only means that we released a new version of the probe, and we recommend that people update it.


If this guide doesn't help, don't hesitate to reach out to us via the chat window on this site or via

Please make sure to mention the Magento Project ID for the project where you are facing the issue.

Did this answer your question?