New Relic for Python monitors your Python application, helping you get insight into performance issues. This document explains how to get New Relic for Python installed and reporting data.
This document gives you helpful context and details about install steps. For very simple install instructions that will work for most WSGI web frameworks (including Django), see the Quick start guide.
Before you install New Relic for Python, you must have a New Relic account. If you don't yet have an account, go to the New Relic sign-up page to create one.
You will also need your New Relic license key number.
If you use one of these hosting services, select it for instructions:
Overview of install process
New Relic for Python supports a number of web frameworks and libraries right out of the box. If you use one of the many supported web frameworks, installation is easy. If you use an unsupported framework, the process will involve some additions to your app code and/or web server files.
Here's an overview of the major install steps:
- Download and install the New Relic package
- Create config file
- Integrate agent with your app
- Restart app and check for data
These steps are described in more detail in the following sections.
Download and install
Download and install the New Relic Python agent package using your preferred procedure. Some common install procedures are below. pip is the recommended install method.
- pip install
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.
Create configuration file
The New Relic agent's config file is the main way to customize the New Relic agent's behavior. (The other methods are via the UI or via environment variables.)
To create the agent config file:
After the New Relic Python package installation, a
newrelic-admin scriptwill be in the same directory as the Python executable. In that directory, run the following:
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 more on how to find your New Relic license key, see New Relic license key.
For in-depth details on how to use the admin script, see Python agent admin script.
Integrate New Relic with your app
Next, you must integrate the Python agent with your application so that important functions and web requests are captured by the agent and sent to New Relic.
There are two integration methods:
- Run the
newrelic-adminscript via the command line (recommended)
- Initialize the Python agent in your web app code
Running the admin script from the command line is recommended because it doesn't require changing your app code. It's possible with most Python set-ups. If you use one of the following web frameworks or servers, select it to read special requirements.
The New Relic Python agent can be used with uWSGI version 1.2.6 or higher. The recommended command line admin script method 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:
Continue reading the install instructions for more on using the command line admin script.
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, running the admin script via the command line is not possible and you must use manual integration in your app code. If you use mod_wsgi-express, you can use the admin script via the command line and you can continue reading the procedures on this page. 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 info, see New Relic Tornado 4 documentation.
Run admin script via command line
To run the
newrelic-admin script via the command line:
- Via your startup shell script or the command line, place the
newrelic-admin run-programscript command in front of your usual startup commands.
For example, if you are using Gunicorn (a popular Python web server) and your startup command is:
gunicorn -w 3 wsgi:application
Then your new New Relic-integrated command would be:
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.
For more information on this method, see Running the admin script from the command line.
Manual integration in application code
The second option for integration is to manually initialize the Python agent in your application code. (You might use this, for example, if you have an embedded Python environment). This is not the recommended method; it is recommended to use the admin script method.
To learn more about this option, see Manual integration in app code.
Restart app and check for data
When you're finished the integration procedure:
- Restart your app server.
- Wait five minutes.
- Check for data showing up in the New Relic APM 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:
- Look at your data in New Relic and learn how things work.
- Read some documentation about New Relic APM. For example, read about the Overview page, the Transactions page, and other APM features.
- Change your application's name. or other configuration options.
- Read about setting up custom instrumentation for your Python app.