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.

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.

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:

The path to the New Relic config file

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: