Skip to main content
The AppSignal add-on for Heroku sets up AppSignal for your Heroku app without manual configuration. When you add it to an app, AppSignal creates an account, generates a Push API key, and sets that key as the app’s APPSIGNAL_PUSH_API_KEY config var. Your AppSignal integration reads the key automatically and starts reporting. You can attach one add-on to several Heroku apps so they report to the same AppSignal account. This helps when a project spans multiple apps, such as a web app and a background worker.
The add-on reports your application’s own data (errors and performance) through your language integration. To also collect Heroku platform data, such as platform errors, host metrics, and automated dashboards, set up a log drain or telemetry drain as well.

​
Install the add-on

You can provision the add-on from the Heroku dashboard or the Heroku CLI. The add-on is listed on the Heroku Elements Marketplace as AppSignal APM. To provision it from the Heroku dashboard:
  1. Open your app in Heroku and select Configure Add-ons under Installed Add-ons on the Overview tab. This opens the app’s Resources tab.
  2. In the Add-on Services field, search for AppSignal APM and select it from the results.
  3. Select a plan from Plan name, then select Submit Order Form.
Heroku provisions the add-on, and AppSignal APM appears in the add-on services list on the Resources tab. To provision it from the Heroku CLI, run:
Bash
Replace <PLAN> with the plan you want and <YOUR_APP_NAME> with your Heroku app’s name. To list the available plans, run heroku addons:plans appsignal. Provisioning takes a few seconds. When it finishes, AppSignal:
  • Creates an AppSignal account for the app.
  • Generates a Push API key and sets it as the app’s APPSIGNAL_PUSH_API_KEY config var. You can see it under Config Vars on the app’s Settings tab.
You don’t need to set the app name or Push API key in your application’s code. The add-on provides the key through Heroku’s configured variables, and your app appears in AppSignal under its Heroku app name. After provisioning, your application can take a few minutes to appear in AppSignal. It appears once AppSignal receives the first data from your app.

​
Open AppSignal from Heroku

Provisioning the add-on creates an AppSignal account for your app. To open it, select the AppSignal APM link under Installed Add-ons on your Heroku app’s Overview tab. Heroku signs you in to AppSignal through single sign-on, where you can see the apps that report to this account, along with their errors, performance, and metrics.
Your app can take a few minutes to report its first data after you open AppSignal. You don’t need to create the app again in AppSignal. Wait for it to appear. Once AppSignal receives data, the installation wizard shows a success message confirming the app is ready to use.
As your app handles requests, it reports data such as throughput, response times, and errors, which you can view in dashboards. To reuse the same dashboard across several apps, import it from a JSON definition: select Add dashboard, paste the dashboard JSON, and select Create dashboard.

​
Monitor multiple apps with one add-on

Attach the add-on to another Heroku app to have both apps report to the same AppSignal account with the same Push API key.
Attaching an existing add-on shares one AppSignalPush API key across apps. Adding a separate AppSignal add-on to each app instead would create a separate account and Push API key per app, and the apps would not be linked.
To attach it from the Heroku dashboard:
  1. Open the app that has the add-on and select Configure Add-ons on its Overview tab. This opens the Resources tab.
  2. In the Add-on Services table, find the AppSignal APM row. In its Attachments column, open the Attached as APPSIGNAL menu and select Manage attachments.
  3. In the Add-on Attachments panel, select Attach to another app, then enter the app’s name and select it from the results.
To attach it from the Heroku CLI, run:
Bash
Replace <APPSIGNAL_ADDON_NAME> with the name of the existing AppSignal add-on and <TARGET_APP_NAME> with the app you want to attach it to. Both apps now share the same APPSIGNAL_PUSH_API_KEY config var and report to the same AppSignal account. The apps stay independent in Heroku. For example, both can be production apps. As with the initial install, the second app can take a few minutes to appear in AppSignal.

​
How the account is named

The account takes its name from the first app the add-on was provisioned on. Accounts created by the add-on work differently from regular AppSignal accounts, so this name can’t be changed afterward. Provision the add-on on the app whose name you want the account to use.

​
If the add-on doesn’t seem to work

The add-on sets your Push API key as a Heroku config var, which your integration reads as an environment variable. If your application also sets a Push API key in its own code, that value can override the one from the add-on, so your app reports to a different account.
If your app doesn’t appear under the add-on’s account, check whether your application sets a AppSignal Push API key in code. In Ruby, for example, that could be in an appsignal.rb file or an Appsignal.configure block. Remove it so your app uses the key from the Heroku config var.
The exact precedence depends on your language’s configuration load order. For details, see the load order documentation for your language, such as the Ruby load order.

​
Remove the add-on

Removing the add-on removes your access to its AppSignal account and data. If you provision the add-on again, AppSignal generates a new Push API key and a new account, and your previous data is not carried over. Export any data you want to keep first.
You can’t delete the add-on while more than one app is attached to it. If you try, Heroku shows the error “Resource must be detached from all other apps before deprovisioning.” Detach the other apps first, then delete the add-on from the app that owns it. The owning app is shown as Billed to in the Plan column. Detaching an app doesn’t delete the add-on or its data. It only stops that app from reporting through the shared add-on. To remove it from the Heroku dashboard:
  1. Open an attached app and select Configure Add-ons on its Overview tab. This opens the Resources tab.
  2. In the Add-on Services table, open the AppSignal APM attachments menu in the Attachments column and select Manage attachments.
  3. In the Add-on Attachments panel, select the remove icon next to each app except the owning app, and confirm each with Remove Attachment.
  4. On the owning app’s Resources tab, open the AppSignal APM row’s Actions menu and select Delete Add-on.
  5. Enter the app’s name to confirm, then select Remove add-on.
To remove it from the Heroku CLI, detach each attachment, then destroy the add-on:
Bash
Replace <ATTACHMENT_NAME> with the attachment to remove, <APP_NAME> with the app it belongs to, and <APPSIGNAL_ADDON_NAME> with the AppSignal add-on’s name.