Python agent and Heroku

Heroku is a Platform as a Service (PaaS) solution for hosting web applications in various agent languages, including Python. With the agent, you can extend Heroku with metrics from New Relic.

This document describes special considerations for using Heroku as a hosting service with Python agent.

Install the New Relic add-on

After deploying your Python app on Heroku, install the Python agent:

Installing the add-on automatically creates a private New Relic account and configures access for Heroku hosts. The agent will begin monitoring application performance, end user experience, and host performance collected after the add-on is installed. Within a few minutes, data should start appearing in your APM Summary page.

Upgrade from an existing agent installation

If an agent is already installed, reinstall the add-on using the Heroku toolbelt command.

$
heroku config:set NEW_RELIC_APP_NAME='Your Application Name'

Install the Python agent

To install a third party Python package such as our Python agent on Heroku, use pip. Heroku automatically looks for a requirements.txt file in the root directory of your project. It installs anything listed in that file when you push your project to Heroku.

1. Create or edit the requirements.txt file, adding the line:

   newrelic

   Copy

2. Django users: Modify the web entry of your Procfile, prefixing the value with newrelic-admin run-program. For example:

   web: newrelic-admin run-program gunicorn mysite.wsgi

   Copy

3. Push your project up to Heroku.

This will install the the Python agent package with the latest version listed on the Python Package Index (PyPi).

Update the Python agent

Heroku caches packages and does not detect when a newer version of the Python agent is available. To force an upgrade:

1. Edit the requirements.txt file by including the specific Python agent version (n.n.n.n) with the package name:

   newrelic==n.n.n.n

   Copy

2. Push your project up to Heroku.

Verify the New Relic add-on

To verify that the New Relic add-on has been enabled, run:

$
heroku run env | grep NEW_RELIC

This generates a list of New Relic-specific environment variables in Heroku. The Python agent uses these to determine which New Relic account and application data to use for reporting data.

At a minimum, you should see:

NEW_RELIC_LOG=stdout
NEW_RELIC_LICENSE_KEY=****************************************
NEW_RELIC_APP_NAME=Your app name

The license key is unique to your New Relic account.

Troubleshoot your installation

Within a few minutes of installing and configuring the agent, data should start appearing in your app's APM Summary page. If no data appears, test that environment variables are being detected properly by running:

$
heroku run newrelic-admin validate-config - stdout

This will create a connection and report test transaction data under the application Python Agent Test. Capture the output from running the test, and use the data to troubleshoot the issue. If you need further assistance, follow the Python agent troubleshooting procedures.

Initialize the Python agent

To initialize the Python agent:

1. From the root of your project, find the Procfile
2. Modify the web entry in your Procfile to define what to do to start up your Python web application.
3. Refer to the following examples to insert newrelic-admin run-program at the start of the command.
4. Run your Python web application under the control of the the Python agent's admin script.

web: newrelic-admin run-program python hello.py

web: newrelic-admin run-program gunicorn -b "0.0.0.0:$PORT" -w 3 hello:app

web: newrelic-admin run-program python hellodjango/manage.py run_gunicorn -b "0.0.0.0:$PORT" -w 3

WSGI application wrapping

The agent provides automatic wrapping of the the WSGI application point for these web frameworks:

• Bottle
• Django
• Flask

If you are using any of these Python web frameworks, no additional steps are required.

For others, you must modify the Python code file with your WSGI application entry point to wrap the WSGI application object with a WSGI application wrapper. This will initiate the timing for the web requests received by your application.

import newrelic.agent

@newrelic.agent.wsgi_application()
def application(environ, start_response):
    ...

import myapp

application = myapp.WSGIHandler()
application = newrelic.agent.WSGIApplicationWrapper(application)

Track Celery tasks

To record execution time for Celery tasks as background tasks against your web application, wrap the startup of the Celery host with the newrelic-admin command.

Prefix the existing startup command defined by the worker entry in your Procfile:

worker: newrelic-admin run-program python hellodjango/manage.py celeryd -E -B --loglevel=INFO

Debug the Python agent

To begin debugging, collect the log output from the Python agent. Heroku sends Python agent output to standard output and captures it in the web server log.

To get access to the web server log for Heroku, run:

$
heroku logs

By default the Python agent will log at info level. If New Relic Support requests an alternate level of logging, you must manually add a config variable. For example, to set logging output to debug, run:

$
heroku config:add NEW_RELIC_LOG_LEVEL=debug

Your application automatically restarts when you change the log level.

$
heroku config:remove NEW_RELIC_LOG_LEVEL

Edit the agent configuration file

When using Heroku's add-on with New Relic, this automatically sets key environment variables for the Python agent. You can also customize additional settings with the agent configuration file, or use server-side configuration.

Do not add core settings such as the license key, application name, etc. to the configuration file. Heroku automatically adds these settings.

To customize other settings, use the Python agent configuration file with Heroku:

1. Add the newrelic.ini agent configuration file to the root directory of your project repository that you are pushing up to Heroku: In the [newrelic] section, include the specific configuration setting; for example:

   [newrelic]
   transaction_tracer.function_trace = mydbm:connect

   Copy

2. Commit the configuration file to your repository, and push the change up to Heroku.

3. Use the heroku config:add command to set the NEW_RELIC_CONFIG_FILE environment variable for your deployed application:

   bash

   Copy

   $
   heroku config:add NEW_RELIC_CONFIG_FILE=newrelic.ini

If you are using the newrelic-admin wrapper program to launch your WSGI host, the settings for your license key, application name, etc., will be picked up from the environment variables set by Heroku. Any additional settings you set in the agent configuration file will also be applied. Then, when the agent registers with New Relic, any server-side configuration will also be merged to create the final configuration the agent will use.