This document gives more detail about the integration step of installing the New Relic Python agent.
After installing the New Relic package and creating a config file, the Python agent must be integrated with your application so that the agent can capture important functions and web requests and send them to your New Relic account.
The recommended integration method is to run the admin script via the command line. This is the best method because it doesn't require you to make changes to your application code.
If, for whatever reason, you cannot use the admin script method, you can use the manual integration method.
Admin script integration method
For a simple overview of using the admin script via the command line, see the integration section of the general install instructions. Below are instructions with more detail and context.
The admin script, newrelic-admin, prefixes the command you use to start your WSGI server or web app. This script works by wrapping your startup command and listening for certain function classes used by common frameworks. (To instrument functions and methods that are not instrumented by default, you would use custom instrumentation.)
Run the script with the run-program option:
|Old command form||New command form|
For example, if you're 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:
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.
For framework-specific notes on using the admin script, see Web frameworks and servers.
Here are more examples of using the admin script:
|uWSGI run directly on a WSGI application||
|paster serve on a WSGI application specified in a paster ini configuration file.||
Here are more tips for using the admin script command:
- Splitting admin script command across multiple lines
You can separately set and export the NEW_RELIC_CONFIG_FILE environment variable before running the script. Ensure you substitute your existing command options for
NEW_RELIC_CONFIG_FILE=newrelic.ini export NEW_RELIC_CONFIG_FILE newrelic-admin run-program YOUR_COMMAND_OPTIONS
If your startup command uses
exec, separate the setting of the environment variable from the execution of the admin script. Ensure you substitute your existing command options for
NEW_RELIC_CONFIG_FILE=newrelic.ini export NEW_RELIC_CONFIG_FILE exec newrelic-admin run-program YOUR_COMMAND_OPTIONS
If you use a process management system such as supervisord where the environment variables must be set in a separate configuration setting, you cannot set them on the same line as the command.
For example, under supervisord you might use this (ensure you substitute your existing command options for
[program:warpdrive] command = newrelic-admin run-program YOUR_COMMAND_OPTIONS environment = NEW_RELIC_CONFIG_FILE=newrelic.ini
- Running admin script with Python executable
If the command being run is the
pythonexecutable and it is being run directly on a Python code file as
python main.py, use either of the following:
newrelic-admin run-program python main.py newrelic-admin run-python main.py
run-pythonwill always use the same
pythonexecutable as is installed in the Python installation or virtual environment that newrelic-admin is installed.
- Notes about the location of newrelic-admin
The newrelic-admin program you run must be coming from the same Python installation or virtual environment as your application is using. You cannot mix programs/components from different Python installations. If this is done, the agent will not run correctly.
For further information on these options to newrelic-admin and the different configuration options based on user environment variables see the more detailed documentation for the
For more details on using the admin script, see Admin script details.
Manual integration in app code
If you are unable to use the recommended admin script integration method, you must initialize the Python agent in your web app code. (For example, if you use mod_wsgi, the admin script method is not possible.)
This process involves importing a Python agent package into your app and making a call to initialize the agent. This call modifies your app's import mechanism so that when libraries are imported, the New Relic agent listens for the function classes it recognizes.
Unlike usual Python functionality, the order of import matters; the New Relic package should be imported first.
For manual integration, add the following to the beginning of the application script file or module that holds your WSGI entry point:
import newrelic.agent newrelic.agent.initialize('/some/path/newrelic.ini')
Put the Python package first in your import list. If you don't, the agent will not optimally monitor your application.
In the example above, /some/path/newrelic.ini represents the location of the copy of the config file created during Python agent installation. The config file must be readable by your web application.
Deployment environment overrides
To specify an override in the agent config file corresponding to a specific deployment environment, the name of that environment should be supplied as the second argument to the
import newrelic.agent newrelic.agent.initialize('/some/path/newrelic.ini', 'staging')
If you have installed the New Relic Python package into a Python virtual environment, the above lines must be added after you activated or otherwise have setup sys.path to find your virtual environment.
The above should, whenever possible, precede any imports for modules which are going to be instrumented. For some web frameworks, including Flask, this is mandatory. The instrumentation will not work correctly if not placed before all imports which cause code from that framework to be imported.
If you do not use the admin script, but still wish to use the environment variables
NEW_RELIC_ENVIRONMENT to configure the agent, you can call the
initialize() function with no arguments and they will be automatically consulted.
import newrelic.agent newrelic.agent.initialize()
Alternatively, you can set the
NEW_RELIC_APP_NAME environment variables if the defaults for all other configuration settings are suitable.
Do note however that when using an embedded environment, such as Apache/mod_wsgi, you generally cannot rely on being able to derive configuration from environment variables. This is because in embedded systems, more often than not, you don't have a way of being able to set process environment variables which are in turn available to the WSGI script file.
For additional details see the documentation for the initialize() function.
Unsupported web frameworks: Wrap the WSGI application
If you are using an unsupported web framework or are constructing a WSGI application using a WSGI component library such as Werkzeug or Paste, you may also need to manually wrap the WSGI application entry point. This would be in addition to doing one of the main integration methods: using the admin script, or manually initializing the Python agent.
If the WSGI application entry point is a function declared in the file itself, use a decorator:
@newrelic.agent.wsgi_application() def application(environ, start_response): ...
If the WSGI application entry point is a function or object imported from a different module, wrap it with a wrapper object:
import myapp application = myapp.WSGIHandler() application = newrelic.agent.WSGIApplicationWrapper(application)
If a supported web framework is being used, you might still use the decorator or wrapper explicitly if, for example, you were adding additional WSGI middleware around the supported web framework. This will ensure that execution of all WSGI middleware is also covered by the monitoring done by the agent.