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.
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,…
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:setupcommand 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/Platform.sh 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:setupcommand 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 firstname.lastname@example.org
Please make sure to mention the Magento Project ID for the project where you are facing the issue.