• /
  • Log in
  • Free account

Python agent: Advanced integration

After you install the Python agent package and create a config file, New Relic's Python agent must be integrated with your application. This step allows the agent to capture and report your application's important functions and web requests.

There are two integration methods:


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.

Admin script integration method

For a simple explanation of how to use the admin script via the command line, see the integration section of the advanced install instructions. Here are instructions with more details and context.

The newrelic-admin admin script 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, use custom instrumentation.)

Here are examples of running the script:

Old command form

New command form


NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program YOUR_ORIGINAL_COMMAND_OPTIONS


NEW_RELIC_CONFIG_FILE=newrelic.ini VARIABLE=value newrelic-admin run-program YOUR_ORIGINAL_COMMAND_OPTIONS

The following examples give instructions for a Bourne-style shell. You may need to adjust these instructions for a different shell.

For framework-specific documentation on using the admin script, see Web frameworks and servers.

Here are some advanced instructions for running the admin script:

For more information, see Admin script details.

Manual integration in app code

If you cannot or do not want to use the recommended admin script integration method, you must initialize the Python agent manually in your web app code. 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 agent listens for the function classes it recognizes.

For manual integration, add the following to the beginning of the application script file or module that holds your WSGI entry point.


Unlike standard Python functionality, the import order matters: the agent package must be imported first.

import newrelic.agent

In this example, /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.

Unsupported web frameworks

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 is 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:

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 can still use the decorator or wrapper explicitly if, for example, you want to configure 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.

For more information, see the documentation for the wsgi_application() and WSGIApplicationWrapper wrapper.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.