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:

Get your Blackfire 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 integrate Blackfire with Magento Commerce (Cloud) and to log in to the Blackfire website. 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. You can access your Blackfire license key through project details.

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.

  1. Using your Project Owner Blackfire credentials, log in to Blackfire.
  2. Navigate to the Environments tab and select an environment.
  3. Click the Settings tab.
  4. Enter an e-mail address and click Add Member.
  5. In the Revoke drop-down list of an account, click Promote as an admin.

    Promote an admin

Enable Blackfire on local workspace

You need to install and configure Blackfire on your local workspace with your working Magento Commerce (Cloud) installation. You do not need to run these installations directly on the hosted environments; only on your local.

We recommend using the Blackfire installation guide to walk you through the process:

  1. Log in to Blackfire.
  2. Navigate to the Environments tab and select the Integration environment.
  3. Click the Settings tab.
  4. Scroll to the bottom and locate the Server ID and Server Token for the environment. You need these values for the instructions.
  5. Open the Blackfire installation guide, select the Operating System, and follow the instructions.

Integrate Blackfire

We recommend enabling Blackfire in all of your active environments, including the Integration environment. See Configure the server credentials & the integration with Magento Cloud. You can integrate with the Pro Integration environment and Starter development branches.

For Starter plans, pushing your code and .magento.app.yaml file to the Staging and Master branches updates those environments directly. You can directly add Blackfire to those environments the way you do with development.

These instructions assume you have set up your local workspace.

  1. Log in to Blackfire.
  2. Navigate to the Environments tab and select the Integration environment.
  3. Click the Builds tab.
  4. Click the info icon next to Magento Cloud.

    Click info icon

  5. In the Magento Cloud Integration page, follow the additional steps to complete the integration. The redacted content is the Project ID.

    Blackfire Magento Cloud integration

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. If you need instructions creating a branch, complete the following:

  1. Log in to your Magento Commerce (Cloud) project.

    magento-cloud login
    
  2. List projects.

    magento-cloud project:list
    
  3. List environments in the project.

    magento-cloud environment:list -p <project_ID>
    
  4. Verify current branch.

    git branch
    
  5. If necessary, check out an existing branch.

    magento-cloud environment:checkout <environment_ID>
    

    You can also create a new branch using the magento-cloud environment:branch command.

  6. Back up the environment using a snapshot.

    magento-cloud snapshot:create -e <environment_ID>
    

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

  1. Use a text editor to locate and edit <project root dir>/.magento.app.yaml in your branch.
  2. Enter - name: blackfire in the extensions block under runtime.

    # .magento.app.yaml
    runtime:
        extensions:
        - mcrypt
        - redis
        - xsl
        - json
        - blackfire
    
  3. Save your changes to .magento.app.yaml and exit the text editor.
  4. 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.

Add project variables

Add project variables for Blackfire for the server ID and token. You can add these using the Magento Cloud CLI or the Project Web Interface. The following instructions walk through adding them using CLI commands.

  1. Open a terminal and navigate to your Magento Commerce (Cloud) project.
  2. Copy the commands from step 3 on the Blackfire Magento Cloud Integration page.
  3. Paste and enter the commands in the Magento Cloud CLI. Since you are already in your project, remove the --project='<Project ID>' content from the command. The commands include the Project ID and Blackfire server ID and token, similar to the following:

    magento-cloud project:variable:set env:BLACKFIRE_SERVER_ID <Blackfire Server ID>
    
    magento-cloud project:variable:set env:BLACKFIRE_SERVER_TOKEN <Blackfire Server Token>
    

Add Blackfire integration to the project

Using the Magento Cloud CLI, enter an integration command to connect Blackfire with the project. This command requires using an account with superuser access. Make sure your Cloud Project account has the super user option in the Project through the Project Web Interface.

  1. Open a terminal and navigate to your Magento Commerce (Cloud) project.
  2. Copy and enter the integration commands from the Blackfire Magento Cloud Integration page.

    magento-cloud integration:add \
    --project='<Project ID>' \
    --type=webhook \
    --url='<Blackfire provided URL>'
    
  3. A series of requests display for the command. To accept default values, hit enter for the questions. If you receive a permission error, verify that you have superuser access for the Magento Commerce (Cloud) project. Either request your permission be upgraded or request an admin run this command.

Default route

If you need to specify a different route to use instead of the default route, change the route in the Blackfire Magento Cloud Integration page (step 5) and update the route in your project routes.yaml file.

Save changes in Blackfire

With all integrations entered on the Blackfire Magento Cloud integration page, click Save. All integration settings save to your Blackfire account with saved integrations and connections with changes entered to your Magento Commerce (Cloud) project. Continue to the next section to begin profiling your store to verify the integration.

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:

  1. 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.
  2. 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.
  3. Click the Blackfire icon.

    Start profiling

  4. 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:

  1. Install the Blackfire CLI Tool. Click on your preferred Platform tab and scroll down to Installing the Blackfire CLI tool.

  2. Depending on the type of code, profile using the blackfire curl or blackfire run command.

Automate performance testing

After completing the Blackfire Integration, you can define events for the Staging and Production environments that enable Blackfire to execute polling requests automatically. An event example is whenever a commit deploys in the Integration environment, or when activating the integration between Blackfire and New Relic.

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 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 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 allow the __blackfire cookie name to pass through the cache. For example:

.magento.app.yaml

cache:
    enabled: true
    cookies: [“/SESS.*/“, “__blackfire”]

Blackfire support

If you continue to experience problems, you can contact Blackfire support and provide output from the following:

  1. Display startup errors and save the output.

     magento-cloud ssh -- php -d display_startup_errors=on --ri blackfire
    
  2. Create a temporary log file.

    magento-cloud variable:create --name php:blackfire.log_file --value /tmp/blackfire.log
    
  3. Set the logging level.

    magento-cloud variable:create --name php:blackfire.log_level --value 4
    
  4. Start a profile/build again and collect the logs.

     magento-cloud ssh -- cat /tmp/blackfire.log > blackfire.log
    
  5. 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: