> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Heroku add-on

> Set up AppSignal for your Heroku apps with the add-on, share it across multiple apps, and manage provisioning.

The [AppSignal add-on for Heroku](https://elements.heroku.com/addons/appsignal) 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.

<Note>
  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](/heroku/setup) as well.
</Note>

## 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 Bash theme={null}
heroku addons:create appsignal:<PLAN> --app <YOUR_APP_NAME>
```

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.

<Note>
  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.
</Note>

As your app handles requests, it reports data such as throughput, response times, and errors, which you can view in [dashboards](/metrics/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.

<Note>
  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.
</Note>

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 Bash theme={null}
heroku addons:attach <APPSIGNAL_ADDON_NAME> --app <TARGET_APP_NAME>
```

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.

<Note>
  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.
</Note>

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](/ruby/configuration/load-order).

## Remove the add-on

<Warning>
  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.
</Warning>

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 Bash theme={null}
heroku addons:detach <ATTACHMENT_NAME> --app <APP_NAME>
heroku addons:destroy <APPSIGNAL_ADDON_NAME> --app <APP_NAME>
```

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.