This is a detailed guide showing how to install New Relic's Python agent for application performance monitoring. 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 want more detailed information about the installation steps.
To use Python or any other agent, as well as the rest of our observability platform, join the New Relic family! Sign up to create your free account in only a few seconds. Then ingest up to 100GB of data for free each month. Forever.
Requirements
Before you install the Python agent:
- Read and understand the compatibility and requirements.
- Have your New Relic account's license key. (If you don't have one already, sign up for a New Relic account.)
Summary of install process
Here's a summary of how to install the Python agent:
- Download and install the Python agent package.
- Create config file.
- Integrate the agent with your app.
- 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 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
We recommend 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:
- Download the appropriate tar.gz file from our 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
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 thesudo
command or run the command as root.
2. Create config file
The config file is the primary method to customize the agent's behavior. You can also use server-side configuration or environment variables.
After you install the 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 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
-
The agent 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
. Withmod_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:
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:
- Restart your app server.
- Wait five minutes.
- View your app's data in APM's Summary page.
If data does not appear after five minutes, follow the troubleshooting procedures.
Additional steps
Here are some suggested next steps after installing the Python agent for your app:
- Explore your data in New Relic One and get comfortable with the standard user interface features.
- Learn about APM's Summary page, the Transactions page, and other performance monitoring features.
- Change your application's name, and use other configuration options.
- Set up custom instrumentation for application activity not monitored by default.
- Configure custom events and custom attributes to collect additional data from your app.