For most supported WSGI servers and web frameworks, you can follow the instructions listed in New Relic's Python agent quick start guide. If using Heroku, also see New Relic's Python agent and Heroku.
If the quick start guides do not cover your specific web stack, or if you have special requirements around how the package needs to be installed, then the instructions below may be more appropriate.
There are two standard methods to install the newrelic Python package:
- Download the package manually from our download site and install it using the provided setup.py script.
- Install from the Python Package Index (PyPi) using tools such as pip, easy_install or buildout.
To get the New Relic Python agent working, you need to perform four steps:
- Install the newrelic package into your Python installation.
- Create and edit the sample Python agent configuration file.
- Test the installation.
- Modify your application to pull in and initialize the agent.
If you are running your application within a virtual environment, ensure you install the
newrelic package within the virtual environment.
Downloading the package
To obtain the package manually:
- Download the appropriate tar.gz file from the download site.
- Unpack the tar.gz file.
Within the top directory of the unpacked package, install it by running:
python setup.py install
Note: 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.
Python package index
The New Relic Python agent package is listed on PyPi at http://pypi.python.org/pypi/newrelic.
|Python package||Installation instructions|
Install the newrelic package directly from PyPi by running:
You can use this method in conjunction with pip requirements files by listing the name of the package (with or without a version qualifier), or the URL to the file on New Relic's download site, and then running:
Recommendation: Use pip instead of easy_install, as pip will correctly remove old versions of the agent software when upgrading.
|buildout||Install the package by creating an appropriate section for the newrelic package using the zc.recipe.egg recipe.|
Creating the configuration file
When the newrelic Python package is installed, it will include a newrelic-admin script in the same directory as the Python executable. To create the agent configuration file:
Run the admin script with the command
generate-config, and supply your license key. Include a target name for the file to write the configuration file out to.
newrelic-admin generate-config LICENSE-KEY newrelic.ini
Edit the generated agent configuration file to uncomment the line and set the log file's location where your web application can write to it.
log_file = /tmp/newrelic-python-agent.log
Change the default application name ("Python Application") to a meaningful name for reporting your application data in the New Relic UI.
Log file options
Depending on your setup, there may be different requirements for your log file. For example:
- If hosting your web application on a hosting service, verify an absolute path for the log file with the hosting provider.
- If you are using Apache/mod_wsgi, your application may be running as the Apache user and may have restricted access. You may need to set up a special directory owned by the Apache user where the log file can be placed. Alternatively, you can use
log_file = stderr, which should result in the agent log output ending up in your web server error log.
For additional options, see Python agent logging.
Testing the agent configuration
Before you continue, test that the package is installed properly and that details in the configuation file are correct.
From the command line, use the admin script to run:
newrelic-admin validate-config newrelic.ini
If this does not appear to run successfully, see testing the Python agent for potential solutions.
Integrating with your application
After installing and configuring, integrate the Python agent into your app or hosting mechanism:
- Refer to the documentation for hosting mechanisms and hosting services.
- Follow standard procedures to integrate the Python agent with your application.
For more help
Additional documentation resources include:
- New Relic for Python (an overview and system requirements for the Python agent)
- Python agent quick start (a quick Python installation usable for most configurations)
- Python agent integration (integrating the Python agent into your application)
- Python hosting mechanisms (a list of additional documentation by hosting mechanism)
- Python hosting services (a list of additional documentation by hosting service)
- Python agent logging (details on configuring Python agent logging)