Advanced install of New Relic Python agent

This document is a detailed guide showing how to install New Relic for Python. For simpler install instructions that will work for the majority of Python frameworks (including Django), see the standard installation guide. Read this advanced guide if you cannot use the standard install, or if you'd like more understanding of the installation steps.

Requirements

Before you install New Relic for Python:

Overview of install process

Here's an overview of how to install the New Relic Python agent:

  1. Download and install the New Relic package.
  2. Create config file.
  3. Integrate the New Relic agent with your app.
  4. Restart your app.

You can also install the Python agent in a Google App Engine flexible environment or use other hosting services, such as Heroku.

1. Download and install

Download and install the New Relic Python agent package using your preferred procedure. For example:

pip install (RECOMMENDED)

Install the newrelic package directly from PyPi by running:

pip install newrelic
easy_install

Run:

easy_install newrelic

New Relic recommends using pip install, because pip will correctly remove old versions of the agent when upgrading.

Buildout install

Install the package by creating an appropriate section for the newrelic package using the zc.recipe.egg recipe.

Manual download and install

To obtain the package manually:

  1. Download the appropriate tar.gz file from New Relic's download site.
  2. Unpack the tar.gz file.

  3. In the top directory of the unpacked package, install it by running:

    python setup.py install

This should be the python executable for the Python installation or virtual environment where you want to install the Python agent software. If installing into a system-wide Python installation, use the sudo command or run the command as root.

2. Create config file

The config file is the primary method to customize the New Relic Python agent's behavior. You can also use server-side configuration or environment variables.

After you install the New Relic Python package, the newrelic-admin script will be in the same directory as the Python executable. To create the agent config file, run this command in the Python executable's directory and include your license key:

newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini

The generate-config command creates the newrelic.ini config file.

3. Integrate the agent

You need to integrate the Python agent with your application so that your app's major functions and web requests are received by the agent. To integrate the Python agent with your app, run the newrelic-admin script in front of your usual app startup command.

If you use any of the following services, follow these guidelines before continuing to the admin script procedure.

uWSGI

The New Relic Python agent can be used with uWSGI version 1.2.6 or higher. The recommended integration method (using the admin script via the command line) can be used for uWSGI, but you will need to supply certain specific command line options to the uwsgi executable. These include:

Option Purpose
--enable-threads By default uWSGI does not enable threading support within the Python interpreter core, so you cannot create background threads from Python code. However, the Python agent relies on being able to create background threads, so this option is required. To automatically configure uWSGI for multiple threads, use the --threads option.
--single-interpreter

By default uWSGI will execute Python code within a sub-interpreter of the process rather than the main Python interpreter created when Python is first initialized. This allows multiple separate Python web applications to run within one process, but keep them separated so they do not interfere with each other.

Older versions of uWSGI can fail when using sub-interpreters with threading enabled. Recommendation: Use the --single-interpreter option, and restrict it to a single web application per process.
mod_wsgi

If you use mod_wsgi, you cannot use the recommended integration method of running the admin script via the command line. Instead, you must manually integrate the Python agent in your app code.

If you use mod_wsgi-express, you can run the admin script via the command line. For more information, see the New Relic mod_wsgi documentation.

Tornado 6

New Relic currently provides support for Tornado 6 only. For more information, see the Tornado 6 web framework documentation.

WebFaction

Python web applications on WebFaction typically use Apache/mod_wsgi. With mod_wsgi, you cannot use the recommended integration method of running the admin script via the command line. Instead, you must manually integrate the Python agent in your app code.

To run the newrelic-admin script via the command line, place the following in front of your standard app startup command:

  1. The path to the New Relic config file
  2. The newrelic-admin run-program script command

For example, here are instructions for a Bourne-style shell. You may need to adjust these instructions for a different shell. If you use a Python gunicorn web server and your startup command is:

gunicorn -w 3 wsgi:application

Then use this command:

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn -w 3 wsgi:application

For more details about using the admin script, see Running the admin script from command line. If you cannot use the admin script method or don't want to, see the manual integration method.

4. Restart app and check for data

When you finish the integration procedure:

  1. Restart your app server.
  2. Wait five minutes.
  3. View your app's data in New Relic APM's Overview page.

If data does not appear after five minutes, follow the troubleshooting procedures.

Additional steps

Here are some suggested next steps after installing the New Relic Python agent for your app:

For more help

Recommendations for learning more: