1. Documentation
  2. Integrations
  3. PaaS & Hosting Providers
  4. Heroku

Heroku

Blackfire provides an official buildpack for Heroku. This buildpack lets you configure and use the Blackfire Agent and the Blackfire CLI Tool. It is complementary to other builpacks, such as official language support buildpacks provided by Heroku.

Install

Configure the Blackfire credentials from your project root directory:

To auto-fill server credentials in the command below, or first

heroku config:set BLACKFIRE_SERVER_ID=<SERVER-ID>
heroku config:set BLACKFIRE_SERVER_TOKEN=<SERVER-TOKEN>
heroku config:set BLACKFIRE_CLIENT_ID=<CLIENT-ID>
heroku config:set BLACKFIRE_CLIENT_TOKEN=<CLIENT-TOKEN>

Note

You may use your Blackfire personal server credentials or environment server credentials.

Add the Blackfire buildpack to your project:

1
heroku buildpacks:add --index=1 https://github.com/blackfireio/integration-heroku

Note

Blackfire being part of the default PHP buildpack, if you are using PHP you don’t need to add the Blackfire buildpack. Read more details below.

Note

As documented in Heroku devcenter, when using multiple buildpacks, the buildpack for the primary language of your app should be the last one added.

PHP

Blackfire is part of the default Heroku PHP buildpack.

To enable Blackfire when using the PHP official Heroku buildpack, add it as a requirement in the project’s composer.json file:

1
composer require ext-blackfire

Python

Install the Blackfire Probe by referring blackfire as dependency in your requirements.txt file, e.g.:

1
2
3
4
blackfire
django
jinja2
gunicorn

Configuration

To set your config vars, you may use heroku config:set command. You may also define them in your app dashboard, in the Settings tab.

Warning

Each time you set or update a config var, you must redeploy your app on Heroku, using a git push heroku master.

Mandatory Config Vars

The following configuration vars must be set:

  • BLACKFIRE_SERVER_ID
  • BLACKFIRE_SERVER_TOKEN
  • BLACKFIRE_CLIENT_ID
  • BLACKFIRE_CLIENT_TOKEN

Optional Config Vars

  • BLACKFIRE_LOG_LEVEL
  • BLACKFIRE_COLLECTOR
  • BLACKFIRE_AGENT_SOCKET

Find more details in Blackfire Agent configuration documentation.

Logs

Log files are located in your app at /app/.blackfire/var/log.

Profile

Profile using the regular Blackfire CLI tools or a browser (Firefox or Chrome).

Note

If your app spans across several dynos, you might have to turn on Session Affinity using the heroku features:enable http-session-affinity command so that only one dyno is profiled when aggregation is enabled (the default).