Python agent and OpenShift

OpenShift is a Platform as a Service (PaaS) solution capable of hosting web applications using various languages including Python.

The New Relic Python agent can be used in conjunction with OpenShift by following the steps outlined below.

Preparing your application

Before installing the Python agent, make sure your Python web application is installed and running under OpenShift using one of the available Python cartridges. See the OpenShift developer guides for more information.

Installing the Python agent

OpenShift support two different ways of installing third party Python packages. You can either list the package as a dependency in the for your web application, or in the requirements.txt file used by pip.

If you are using a file, install New Relic by adding newrelic to the list of third party modules passed to install_requires:

from setuptools import setup

      description='OpenShift App',
      author='Your Name',
      install_requires=['Flask>=0.7.2', 'MarkupSafe', 'newrelic'],

If you are using pip, add the following line to requirements.txt:


When you push your project up to OpenShift, this will install the New Relic Python agent package. It will use the latest version of the Python agent from the OpenShift mirror of the Python Package Index (PyPi). Updates to the OpenShift mirror of PyPi can be delayed, so you may have to wait up to a day before a new release on PyPi is available on OpenShift.

Updating the Python agent

OpenShift will cache packages and will not detect when a newer version of the Python agent is available. To force an upgrade to a newer version, explicitly list the version against the package name in the or requirements.txt file and push your application. Use this syntax:


Replace A.B.C.D with the version of the New Relic Python agent you wish to install.

Agent environment variables

In order for the Python agent to report data to the correct account, you need to tell it the license key for your New Relic account.

For OpenShift, the most secure way to provide the license key is using an environment variable configured in your application configuration using the rhc env set command. This avoids storing sensitive information in your GIT repository and also works if you are using a scaled web application which is hosted on multiple physical servers.


While specifying your license key, also tell the Python agent where to record log messages:

rhc env set NEW_RELIC_LOG=stderr -a YOUR_APP_NAME

To verify that the environment variables are being set, run:

rhc env list -a YOUR_APP_NAME

Although set, these will only take effect the next time the web application gears are restarted.

Testing the agent installation

To test that the Python agent package has been installed correctly and that the agent environment variables are being set correctly, you can ssh into the main gear of your application and run:

newrelic-admin validate-config - stdout

This admin script will create a connection back to New Relic and report test transaction data under the application Python Agent Test in your New Relic account.

Data can take up to five minutes to appear in the UI. If it doesn't appear after some time, capture the output from running the test and use the data to troubleshoot the issue. If you need further assistance, get support at

Initializing the Python agent

The OpenShift Python cartridges provide two ways of running a WSGI application.

The first uses a preconfigured Apache/mod_wsgi installation. In this case your WSGI application entry point must be defined in the file.

The second relies on you providing a standalone Python web application script called This would typically start an embedded Python WSGI server, with the WSGI application entry point being specified within the file, or imported from a separate Python code file such as the file.

For either method, because OpenShift controls the startup of the WSGI server, you must manual integrate the Python agent into your WSGI application. It is not possible to use our newrelic-admin wrapper script around the startup of the WSGI server.

If you are using the Apache/mod_wsgi approach, add the following code at the very start of the file:

import newrelic.agent

This should precede any other Python module imports appearing in the file. There is no need to provide any arguments to the initialize() call because the license key information and destination for logging are read from the environment variables.

If you are using an embedded Python WSGI server from, these lines should instead be placed at the very start of the file. These lines should be at the start of the file even if you import the WSGI application entry point from a file. When using with, do not add these lines to

Note: It is not recommended that you use the built-in development servers of any web framework. This is because these development servers are often based on the WSGI server from the wsgiref module from the Python standard library. The WSGI server from the wsgiref module had a bug which meant it was not fully WSGI-compliant, which would cause the Python agent to report incorrect data. This issue with the wsgiref module is only fixed in Python 2.7.4. The builtin WSGI server in older versions of Django prior to Django 1.4 had a similar problem. It is therefore recommended you do not use the OpenShift Python 2.6 cartridge or older Django versions.

Wrapping the WSGI application

If you are using a Python web framework for which we provide automatic wrapping of the WSGI application entry point, this is all that needs to be done. Python web frameworks with automatic wrapping include Django, Flask and Bottle.

For others, you will need to modify the Python code file with your WSGI application entry point to wrap the WSGI application object with a New Relic WSGI application wrapper. This will initiate the timing for the web requests received by your application.

Entry point Example code

Enty point is a function

Wrap it in a decorator.

import newrelic.agent

def application(environ, start_response):

Enty point is a function or object imported from a different module.

Wrap it in pre decorator style.

import myapp
application = myapp.WSGIHandler()
application = newrelic.agent.WSGIApplicationWrapper(application)

Overriding the application name

By default, your data is recorded under the app name Python Application. The display name for this can be changed in the New Relic APM user interface. However, from the agent side, New Relic highly recommends keeping this as a unique, unchanging value, independent of changes to the display name in the UI.

This is required if you intend to run multiple distinct sites under the one New Relic account and want to have the data reported separately.

To override the application name, use the rhc env set command:

rhc env set NEW_RELIC_APP_NAME='Web Site (Production)' -a yourappname

To verify that the configuration has been updated, run:

rhc env list -a yourappname

Then look for:

NEW_RELIC_APP_NAME=Web Site (Production)

Changes to environment variables only take effect the next time you restart your web application gears.

Debugging the Python agent

To begin debugging you need to collect the log output from the Python agent. So long as the NEW_RELIC_LOG environment variable was set to stderr, then log messages from the Python agent will be captured within the standard Python web application logs.

To tail the web application logs under OpenShift, run:

rhc tail -a YOUR_APP_NAME

To grab the complete log, you will need to copy back from each of your web applications the log file:


By default the Python agent will log at info level. If we require an alternate level of logging, you will need to manually add an additional environment variable. For example, to set logging output to debug, run:

rhc env set NEW_RELIC_LOG_LEVEL=debug -a YOUR_APP_NAME

As environment variables do not take effect immediately, you will need to restart your web application gears.

Running with debug logging should only be done when requested and only for the time required as it can produce a lot of output and will bloat your log files. You should remove this setting as soon as it is no longer required by running:

rhc env unset NEW_RELIC_LOG_LEVEL -a yourappname

and restart your web application gears.

Use the logfile to troubleshoot the issue. If you need further assistance, get support at

Agent configuration file

With OpenShift, the preferred way of specifying your account license key and defining where logging should go is to use environment variables. This means it is not necessary to use an agent configuration file to get the agent working. However, without the agent configuration file, it is not possible to customize other agent settings.

If you enable server-side configuration for your application, you do not need an agent configuration file. This is done from the Application settings in the New Relic APM user interface application. Using server-side configuration you can override core settings for the agent. When a change is made to a setting via the UI, the agent running within each of your web application processes will be notified, and it will pick up the changed settings.

However, some agent features are incompatible with server-side configuration. In these cases, use an agent configuration file pushed up with your web application to OpenShift.

To add and enable an agent configuration file with OpenShift:

  1. Add the agent configuration file newrelic.ini to the root directory of your project repository that you are pushing up to OpenShift. This should contain a [newrelic] section along with just the specific configuration setting you need to set. For example:

    transaction_tracer.function_trace = mydbm:connect

    Do not use the agent configuration file for core settings such as the license key or app name, as doing so will override the environment variable settings. You also likely do not want the license key as part of your GIT repository, especially if the project source code is publicly available.

    Also note that if server-side configuration is enabled at the same time, any setting that can be set via server-side configuration will always override the local setting. Therefore only use this for settings that cannot be set using server-side configuration if server-side configuration is enabled.

  2. Now modify the or file where you added the code to initialize the Python agent. Change the code you had already added to:

    import os
    import newrelic.agent
    repo_dir = os.environ['OPENSHIFT_REPO_DIR']
    config_file = os.path.join(repo_dir, 'newrelic.ini')
  3. Commit the configuration file to your repository and push the change up to OpenShift.

For more help

Additional documentation resources include:

Join the discussion about Python in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at