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

For Pro:

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).

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.

Integrate Blackfire

We recommend enabling Blackfire in all of your active environments, including the Integration environment. See Configure Blackfire to run in all Magento Cloud environments.

Prerequisites

You must be an account owner or have super user access.
Set up your local workspace. (magento-cloud CLI v1.23 or later)

Set the MAGENTO_CLOUD_APPLICATION environment 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.

Setup Blackfire

From the terminal, log in to your Magento Commerce Cloud project.
Configure Blackfire using the magento-cloud CLI.
```
1
magento-cloud blackfire:setup
```
The blackfire:setup command 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.

Blackfire troubleshooting

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:

.magento.app.yaml

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.yaml updated 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 .magento.app.yaml file.

To create a snapshot in a new branch:

magento-cloud login

List projects.

magento-cloud project:list

List environments in the project.

magento-cloud environment:list -p <project-ID>

Verify current branch.
```
1
git branch
```

If necessary, check out an existing branch.

magento-cloud environment:checkout <environment-ID>

Also, you can create a new branch using the magento-cloud environment:branch command.

Back up the environment using a snapshot.

magento-cloud snapshot:create -e <environment-ID>

Next, modify the `.magento.app.yaml` file:

Use a text editor to locate and edit the <project root dir>/.magento.app.yaml file in your branch.

Enter - name: blackfire in the extensions block under runtime.

# .magento.app.yaml
runtime:
    extensions:
        - mcrypt
        - redis
        - xsl
        - json
        - blackfire

Save your changes to the .magento.app.yaml file 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.yaml file 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 routes.yaml file.

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 blackfire curl or blackfire run command.
- Profiling HTTP Requests
- Profiling CLI Commands

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— /home, /checkout, /checkout/payment—Blackfire can notify you if your code complies with established code performance recommendations. The following is a sample build report with recommendations:

Blackfire build report

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:

.blackfire.yml

scenarios:
  Home:
    - /index.php
  Product list:
    - /index.php/women/tops-women/jackets-women.html
  Checkout:
    - /index.php/checkout
  Payment:
    - /index.php/checkout/payment

See the Blackfire documentation on Writing tests and Writing scenarios.

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.

Blackfire notifications

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.

Blackfire support

Blackfire provides Enterprise support for Pro and Premium support for Starter.

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 support@blackfire.io.

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 resources

Blackfire provides great information to better profile and investigate the results on their documentation site:

Jan 30th, 2019