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
setup.py for your web application, or in the
requirements.txt file used by
If you are using a
setup.py file, install New Relic by adding
newrelic to the list of third party modules passed to
from setuptools import setup setup(name='YourAppName', version='1.0', description='OpenShift App', author='Your Name', firstname.lastname@example.org', url='https://www.python.org/community/sigs/current/distutils-sig', install_requires=['Flask>=0.7.2', 'MarkupSafe', 'newrelic'], )
If you are using
pip, add the following line to
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
requirements.txt file and push your application. Use this syntax:
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.
rhc env set NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY -a YOUR_APP_NAME
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 support.newrelic.com.
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
The second relies on you providing a standalone Python web application script called
app.py. This would typically start an embedded Python WSGI server, with the WSGI application entry point being specified within the
app.py file, or imported from a separate Python code file such as the
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
import newrelic.agent newrelic.agent.initialize()
This should precede any other Python module imports appearing in the
wsgi.py 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
app.py, these lines should instead be placed at the very start of the
app.py file. These lines should be at the start of the
app.py file even if you import the WSGI application entry point from a
wsgi.py file. When using
wsgi.py, 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 @newrelic.agent.wsgi_application() 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 support.newrelic.com
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:
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:
[newrelic] 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.
Now modify the
app.pyfile 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') newrelic.agent.initialize(config_file)
Commit the configuration file to your repository and push the change up to OpenShift.
For more help
Additional documentation resources include: