---
title: PHP agent and Heroku
source: https://docs.newrelic.com/docs/apm/agents/php-agent/advanced-installation/php-agent-heroku
---

[Heroku](https://www.heroku.com/) is a Platform as a Service (PaaS) solution for hosting web applications in various languages, including PHP. With New Relic, you can extend Heroku with metrics from [APM](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/welcome-new-relic-apm) and [browser monitoring](https://docs.newrelic.com/docs/browser/new-relic-browser/getting-started/new-relic-browser).

## Prepare your application [#Preparing]

Before installing the PHP agent, make sure your PHP web application is installed and running under Heroku. For more information, see [Getting Started with PHP on Heroku](https://devcenter.heroku.com/articles/getting-started-with-php).

## Install the PHP agent [#installing]

After deploying your PHP app on Heroku, install our PHP agent:

**Via the Heroku website**

To install the New Relic add-on through the Heroku website:

1.  From the [New Relic Add-on Page](https://elements.heroku.com/addons/newrelic#pricing), select a subscription plan.
2.  From the **Select an app** dropdown, select your app.
3.  Give your application a [descriptive name](#naming) with this Heroku toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_APP_NAME='YOUR_APP_NAME'
    ```
4.  Push a change to Heroku (for example, `git commit --allow-empty`) to enable the PHP extension during build.
5.  Generate some traffic to your app.

**Via Heroku toolbelt**

To install the New Relic add-on with Heroku toolbelt:

1.  Via Heroku toolbelt, run the following command and substitute the [appropriate subscription plan](https://elements.heroku.com/addons/newrelic#pricing):

    ```bash
    heroku addons:create newrelic:YOUR_PLAN_LEVEL
    ```
2.  Give your application a [descriptive name](#naming) with this Heroku toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_APP_NAME='YOUR_APP_NAME'
    ```
3.  Push a change to Heroku (for example, `git commit --allow-empty`) to enable the PHP extension during build.
4.  Generate some traffic to your app.

Within a few minutes, data should start appearing in your [APM **Summary** page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page). If no data appears, see the [verification](#verifying) and [troubleshooting](#troubleshooting) procedures in this document.

## Configure the agent on Heroku [#config]

Heroku automatically configures default environment variables for your app. To customize your settings, create and upload a **newrelic.ini** file to Heroku:

1.  Download a "clean" copy of [`newrelic.ini_.heroku`](./files/newrelic.ini_.heroku) [INI | 16KB].
2.  Rename the file from `newrelic.ini_.heroku` to `newrelic.ini`.
3.  Copy `newrelic.ini` to the root directory of your project repository.
4.  Customize your settings as described in [PHP agent configuration](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration).

    > #### ⚠️ CAUTION
    >
    > Do not change `newrelic.license`, `newrelic.loglevel`, or `newrelic.appname`. These settings are configured by Heroku toolbelt.
5.  Commit your config file changes to your repository, and push your changes to Heroku.
6.  Instruct Heroku to use your customized config file via this Heroku toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_CONFIG_FILE=newrelic.ini
    ```

## Name your application [#naming]

To ensure that metrics from each app are reported separately, [give each app a descriptive name](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/naming-your-application#app-name). Your application name defaults to **PHP Application on Heroku**.

New Relic uses the app name to aggregate data. If you do not change this name, New Relic will aggregate the data from each additional PHP app you install under this same name.

1.  To name your application, run this Heroku toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_APP_NAME='YOUR_APP_NAME'
    ```
2.  To verify your app's name change, run:

    ```bash
    heroku run env | grep NEW_RELIC_APP_NAME
    ```

Verify that the confirmation prompt returns the new app name:

```ini
NEW_RELIC_APP_NAME=YOUR_APP_NAME
```

## Verify your installation [#verifying]

To verify that Heroku has installed the New Relic add-on, run this Heroku toolbelt command:

```bash
heroku run env | grep NEW_RELIC
```

This will generate a list of New Relic environment variables in Heroku. The agent uses these environment variables to determine which account to report data to. You should see at least the following variables:

```ini
NEW_RELIC_LICENSE_KEY="YOUR_LICENSE_KEY"
NEW_RELIC_LOG_LEVEL="warning"
NEW_RELIC_APP_NAME="YOUR_APP_NAME"
```

You can also use [**phpinfo** to verify that your app is being instrumented](https://docs.newrelic.com/docs/agents/php-agent/troubleshooting/using-phpinfo-verify-php).

## Troubleshooting the agent on Heroku [#troubleshooting]

To troubleshoot the PHP agent on Heroku, examine your log file, which is stored in the Heroku web server log.

1.  To view the web server log, run this Heroku toolbelt command:

    ```bash
    heroku logs -t | tee newrelic.log
    ```
2.  Use the log file to troubleshoot the issue.
3.  If you need further assistance, [get support at support.newrelic.com](https://support.newrelic.com).

The PHP agent defaults to the `warning` [log level](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration#inivar-loglevel). New Relic Support may also request logs at the `verbosedebug` log level. To change the log level to `verbosedebug`, run this Heroku toolbelt command:

```bash
heroku config:set NEW_RELIC_LOG_LEVEL=verbosedebug
```

> #### ⚠️ CAUTION
>
> The `verbosedebug` log level quickly generates a large volume of data. Use this setting only if New Relic Support requests it, and remove this setting as soon as you collect the output by running this Heroku toolbelt command:
>
> ```bash
> heroku config:unset NEW_RELIC_LOG_LEVEL
> ```