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.
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.
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'
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.
Create or edit the requirements.txt file, adding the line:newrelic
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
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).
Heroku caches packages and does not detect when a newer version of the Python agent is available. To force an upgrade:
Edit the requirements.txt file by including the specific Python agent version (
n.n.n.n) with the package name:
Push your project up to Heroku.
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=0000000000000000000000000000000000000000 NEW_RELIC_APP_NAME=Your app name
The license key is unique to your New Relic account.
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.
To initialize the Python agent:
- From the root of your project, find the Procfile.
- Modify the
webentry in your Procfile to define what to do to start up your Python web application.
- Refer to the following examples to insert
newrelic-admin run-programat the start of the command.
- Run your Python web application under the control of the the Python agent's admin script.
Example web entry
Flask with the built-in development host
Flask with gunicorn
Django with gunicorn listed in
Avoid using the built-in development hosts of any web framework prior to Python version 2.7.4 or prior to Django 1.4. Instead, use gunicorn or uWSGI.
The WSGI host using the wsgiref module was not fully WSGI compliant for development hosts prior to Python version 2.7.4. This prevented the Python agent from being able to report correct data.
The agent provides automatic wrapping of the the WSGI application point for these web frameworks:
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.
If the entry point is this...
Entry point is a function
Wrap it in a decorator:
Entry point is a function or object imported from a different module
Wrap it in
To record execution time for Celery tasks as background tasks against your web application, wrap the startup of the Celery host with the
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
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:
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
heroku config:add NEW_RELIC_LOG_LEVEL=debug
Your application automatically restarts when you change the log level.
debug log level produces large quantities of output. Be sure to remove this setting as soon as it is no longer required, by running:
heroku config:remove NEW_RELIC_LOG_LEVEL
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:
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
Commit the configuration file to your repository, and push the change up to Heroku.
heroku config:addcommand to set the NEW_RELIC_CONFIG_FILE environment variable for your deployed application: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.