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.
Manual integration: If you cannot use the admin script method, you can manually initialize the Python agent in your app code.
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 some advanced instructions for running the admin script:
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 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 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 the following. Be sure to substitute your existing command options for YOUR_COMMAND_OPTIONS.
If the command being run is the python executable 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
Using run-python will always use the same python executable as is installed in the Python installation or virtual environment that newrelic-admin is installed.
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.
If you use a process management system such as supervisord in a virtual environment, you could use this configuration:
Note the PATH environment variable that points to the same path that would be used by the virtual environment.
For more information on these options to newrelic-admin and the different configuration options based on user environment variables, see the more detailed documentation for the run-program and run-python options.
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.
Important
Unlike standard Python functionality, the import order matters: the agent package must be imported first.
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.
To specify an override in the agent config file that corresponds to a specific deployment environment, supply the environment's name as the second argument to the initialize() function. If you have installed the Python package into a Python virtual environment, you must add these lines after you have activated or set up sys.path to find your virtual environment.
Whenever possible, precede any imports for modules that 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 that cause code from that framework to be imported.
If you do not use the admin script but still want to use the environment variables NEW_RELIC_CONFIG_FILE and NEW_RELIC_ENVIRONMENT to configure the agent, you can call the initialize() function with no arguments, and they will be read automatically.
import newrelic.agent
newrelic.agent.initialize()
Alternatively, you can set the NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME environment variables if the defaults for all other configuration settings are suitable.
With embedded environments such as Apache/mod_wsgi, in general you cannot rely on being able to derive configuration from environment variables. This is because typically in embedded systems, you cannot set process environment variables which are in turn available to the WSGI script file. For more information, see the documentation for the initialize() function.
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:
@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:
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.