Blackfire.io for Magento Cloud
Blackfire.io for Magento Cloud is a PHP profiler and automated performance testing tool that can be used in the development Integration, Staging, and Production environments. It enables you to locate and investigate performance issues in your environment at the code level and creates a performance profile by tracking every PHP call, method, and SQL query performed by your code. Blackfire digs deeper to provide granular performance analytics.
In addition, it profiles your code automatically and notifies you whenever your code does not comply with best practices for Magento 2 code performance management. For a high level overview and demo of Blackfire, review the videos in the Introduction to Blackfire.io for Magento Cloud.
For full details on integrations, also review Configuring Blackfire on Magento Cloud.
Blackfire includes the following environments through their site:
Magento Cloud (<your-instance-reference>)—Integration and Development
Magento Cloud (<your-instance-reference>)—Staging
Magento Cloud (<your-instance-reference>)—Production
- You must bypass the Fastly service in your Production environment when profiling with Blackfire. See Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDN).
For Pro projects created before October 23, 2017, the architecture is slightly different. You must enter a Support ticket with your Blackfire credentials to configure your Staging and Production environments with Blackfire. See Pro architecture (legacy).
Get your Blackfire login credentials
The Project Owner is the account owner, and their e-mail address is part of the credentials required for accessing Blackfire for your project. You can only use the Project Owner credentials to log in to the Blackfire website initially. An invitation email is sent to the Project Owner’s e-mail address to complete activation.
For information on setting up an account on Blackfire, see Accessing your Blackfire account as a Magento Cloud user.
Add collaborator accounts
After you access your Blackfire account, you can add additional collaborator accounts.
We recommend adding at least one account through Blackfire to manage all access, integrations, and usage of the tool. We also recommend promoting one of the added members to Admin, to manage all Blackfire access and integrations.
- Using your Project Owner Blackfire credentials, log in to Blackfire.
- Navigate to the Environments tab and select an environment.
- Click the Settings tab.
- Enter an e-mail address and click Add Member.
In the Revoke drop-down list of an account, click Promote as an admin.
We recommend enabling Blackfire in all of your active environments, including the Integration environment. See Configure Blackfire to run in all Magento Cloud environments.
- You must be an account owner or have super user access.
- Set up your local workspace. (
magento-cloudCLI v1.23 or later)
MAGENTO_CLOUD_APPLICATIONenvironment variable in Staging or Production environment.
Use the following to verify the settings:
magento-cloud ssh 'PRO="$(env | grep -v SSH_ORIGINAL_COMMAND | grep MAGENTO_CLOUD_APPLICATION)"; [[ -n "$PRO" ]] && echo "MAGENTO_CLOUD_APPLICATION exists" || echo "MAGENTO_CLOUD_APPLICATION does not exist; contact Magento Commerce Cloud support"'
If you do not meet all requirements, contact your Magento Commerce Cloud account manager.
From the terminal, log in to your Magento Commerce Cloud project.
Configure Blackfire using the
blackfire:setupcommand automatically configures Blackfire on all environments and activates automated profiling each time you apply and commit changes to an environment. If prompted, provide the Magento Commerce Cloud project ID and your Blackfire client credentials.
Enable Blackfire on local workstation
You can install and use Blackfire on your local workstation with your Magento Commerce Cloud installation. You do not need to run these installations directly on the hosted environments.
We recommend using the Blackfire installation guide to walk you through the process:
Log in to Blackfire.
On the Environments tab, select the Integration environment.
Click the Settings tab.
Scroll to the bottom and locate the Server ID and Server Token for the environment. You need these values for the instructions.
Open the Blackfire installation guide, select the Operating System, and follow the instructions.
Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDN)
If you use a reverse proxy, cache, or CDN, you must grant Blackfire access to your servers. See Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDN) for an in-depth explanation.
HTTP Cache configuration
If you use the HTTP cache with
cookies, update your
.magento.app.yaml file to enable the
__blackfire cookie name to pass through the cache. For example:
cache: enabled: true cookies: [“/SESS.*/“, “__blackfire”]
Add Blackfire to .magento.app.yaml
By default, the
.magento.app.yaml file includes the Blackfire module. If the module is not present, use the following instructions to update your
.magento.app.yaml file, push the updated file to your remote branch, merge, and deploy across all environments.
- For Starter, merging your Git branch across all environments adds the module.
- For Pro (legacy), you need to enter a Support ticket to have
.magento.app.yamlupdated to Staging and Production.
We recommend working in a branch and creating a snapshot prior to installing. If you have a branch already created, you can skip down to the steps for modifying the
To create a snapshot in a new branch:
Log in to your Magento Commerce Cloud project.
List environments in the project.
magento-cloud environment:list -p <project-ID>
Verify current branch.
If necessary, check out an existing branch.
magento-cloud environment:checkout <environment-ID>
Also, you can create a new branch using the
Back up the environment using a snapshot.
magento-cloud snapshot:create -e <environment-ID>
Next, modify the
Use a text editor to locate and edit the
<project root dir>/.magento.app.yamlfile in your branch.
- name: blackfirein the
# .magento.app.yaml runtime: extensions: - mcrypt - redis - xsl - json - blackfire
Save your changes to the
.magento.app.yamlfile and exit the text editor.
Add, commit, and push your changes to the environment.
git add -A && git commit -m "<message>" && git push origin
If errors display during deployment, open the
.magento.app.yamlfile and check the syntax, such as indentation and spelling, and try again.
Changing from the default route
Instead of using the default route, you can change the route in the Blackfire Magento Cloud Integration page (expand Advanced Settings to reveal the route selection setting) to the desired route from your
Profile your store
You can verify that Blackfire works using a browser extension or the CLI. For extensive CLI profiling options and better understanding the profiles, see Blackfire resources.
You can only use the CLI in your local development environment.
To profile using the browser:
- Install the Blackfire browser extension in Chrome or Firefox. A Blackfire icon displays in your browser next to the address location. If you do not see it, you may need to display the bar.
- Visit the store or site URL for your specific environment, such as the URL for your Integration environment. If you need this URL, you can find it through the Project Web Interface. Select the environment branch and copy the link from the Access section.
Click the Blackfire icon.
Click Profile to start.
Note: The browser extension also enables you to profile all requests while you browse. For more information about this, see Blackfire resources.
To profile using the CLI:
Install the Blackfire CLI Tool. Click on your preferred Platform tab and scroll down to Installing the Blackfire CLI tool.
Depending on the type of code, profile using the
Automate performance testing
After completing the Blackfire Integration, Blackfire runs performance tests automatically each time you push code to an active branch, merge a branch, or deploy to Staging or Production environments. This adds no overhead and has no impact on the deployment process. Also, you can activate Blackfire’s automated performance testing using the Blackfire/New Relic integration, and other options.
By simply defining a set of key requests for Blackfire to profile—
/checkout/payment—Blackfire can notify you if your code complies with established code performance recommendations. The following is a sample build report with recommendations:
Writing your first automated tests and scenarios
You can easily write tests and scenarios for Blackfire to execute. Create a
.blackfire.yml file and store it at your project root directory.
Try adding the following scenarios in the file:
scenarios: Home: - /index.php Product list: - /index.php/women/tops-women/jackets-women.html Checkout: - /index.php/checkout Payment: - /index.php/checkout/payment
Running your tests automatically
Once you create and deploy your
.blackfire.yml file, you can enable Blackfire to run your tests automatically in various ways:
- Automated builds on Integration—Whenever you push code on an Integration, Staging, or Production branch, Blackfire automatically runs your tests. You can receive a notification of the results in various ways, such as a commit status level when using GitHub or Bitbucket. See Blackfire notifications.
- Automated builds using a webhook—Blackfire offers a very flexible way to start builds using a webhook, which can target any endpoint. See Start building a webhook.
- Automated builds with the Blackfire/New Relic integration—Blackfire and New Relic are very complementary. New Relic monitors the overall traffic performance, and Blackfire profiles much deeper into the PHP code. See What is the difference between Blackfire and New Relic. You can configure New Relic to fire Blackfire builds whenever relevant. See New Relic.
When you configure at least one way of triggering builds with Blackfire, you can be notified whenever a build report is available. Blackfire supports an integration with Slack, GitHub, BitBucket, email, and more. See Scenario notification channels.
To prepare log output for Blackfire support:
If you continue to experience problems, prepare your log files and contact Blackfire support.
Display startup errors and save the output.
magento-cloud ssh "php -d display_startup_errors=on --ri blackfire"
Create a temporary log file.
magento-cloud variable:create --name php:blackfire.log_file --value /tmp/blackfire.log
Set the logging level.
magento-cloud variable:create --name php:blackfire.log_level --value 4
Start a profile/build again and collect the logs.
magento-cloud ssh "cat /tmp/blackfire.log" > blackfire.log
Send output and logs to email@example.com.
To disable the Blackfire logs:
You can disable logging by cleaning the temporary log file and removing the log level:
magento-cloud variable:delete php:blackfire.log_file
magento-cloud variable:delete php:blackfire.log_level
Blackfire provides great information to better profile and investigate the results on their documentation site: