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 install guide. Read this advanced guide only if you cannot use the standard install, or if you'd like more understanding of the install steps.
Before you install New Relic for Python:
- Read and understand the compatibility and requirements.
- Have your New Relic account's license key (if you don't have an account, sign up for one here)
Overview of install process
Here's an overview of how to install the New Relic Python agent:
- Download and install the New Relic package
- Create config file
- Integrate the New Relic agent with your app
- Restart your app
These steps are described in more detail in the following sections.
If you use the hosting service Heroku, see Heroku install for more information.
If you want to instrument non-web scripts, worker processes, tasks, and functions, see Monitor scripts and functions.
1. Download and install
Download and install the New Relic Python agent package using your preferred procedure. Some common install procedures are:
- pip install (RECOMMENDED)
Install the newrelic package directly from PyPi by running:
pip install newrelic
pip install is recommended, 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
- Manual download and install
To obtain the package manually:
- Download the appropriate tar.gz file from the download site.
- Unpack the tar.gz file.
In the top directory of the unpacked package, install it by running:
python setup.py install
This should be the
pythonexecutable 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
sudocommand or run the command as root.
2. Create config file
Next, you will create a configuration file for the New Relic Python agent. The config file is the main way to customize the New Relic agent's behavior. (The other methods are using the UI or using environment variables.)
To create the agent config file:
After you've installed the New Relic Python package, the
newrelic-admin script will be in the same directory as the Python executable. In that directory, run:
newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini
generate-config command creates the config file.
newrelic.ini is the recommended name for the config file. For instructions on how to find your New Relic license key, see New Relic license key.
3. Integrate the agent
The next step is integrating the Python agent with your application so that your app's major functions and web requests are captured by the agent. This is done by running the
newrelic-admin script in front of your usual app startup command.
If you use one of the following services, select it to read some caveats before continuing to the admin script instructions.
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. The additional options you must use are:
By default uWSGI does not enable threading support within the Python interpreter core. This means it is not possible to create background threads from Python code. As the Python agent relies on being able to create background threads, this option is required. This option will be automatically applied if uWSGI is configured for multiple threads using the --threads option.
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 is done to allow multiple separate Python web applications to be run within the one process but to be sufficiently separated so as to not interfere with each other. Older versions of uWSGI can fail however when using sub interpreters with threading enabled. It is therefore safest to use this option and restrict yourself to a single web application per process. Running a single web application in each process with uWSGI is the normal use case so it would be unlikely that this restriction would be an issue.
If you use mod_wsgi, the recommended integration method (running the admin script via the command line) is not possible and you must manually integrate the Python agent in your app code.
If you use mod_wsgi-express, you can use the recommended integration method and you can continue reading the instructions in this document. For more information, see the New Relic mod_wsgi documentation.
- Tornado 4
New Relic provides introductory support for Tornado 4. Use of Tornado 4 requires activation with a feature flag. For more on this, see New Relic for Tornado 4.
Python web applications on WebFaction typically use Apache/mod_wsgi. With mod_wsgi, it is not possible to use the recommended admin script method; you must use a manual integration method.
If you're using mod_wsgi-express, you can use the admin script via the command line and you can continue reading the instructions in this document.
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
newrelic-admin run-programscript command
For example, if you use Gunicorn (a Python web server) and your startup command is:
gunicorn -w 3 wsgi:application
Then the new command would be:
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn -w 3 wsgi:application
The above instructions are for a Bourne-style shell. You may need to adjust these instructions for a different shell.
4. Restart app and check for data
When you've finished the integration procedure:
- Restart your app server.
- Wait five minutes.
- Check for data showing up in your New Relic charts.
If data is not showing up, see Troubleshooting: No data appears.
If you've gotten New Relic working for your Python app, here are some suggested next steps:
- Explore your data in New Relic and get comfortable with the user interface.
- Read documentation about New Relic APM. For example, read about the Overview page, the Transactions page, and other performance monitoring features.
- Change your application's name, and other configuration options.
- Learn about setting up custom instrumentation for application activity not monitored by default.