OpenShift is a Platform as a Service (PaaS) solution capable of hosting web applications using various languages, including New Relic APM's Python agent.
Prepare 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.
Install the APM 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', email@example.com', 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.
Update 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.
Use Python 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 hosts.
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.
Test 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.
Initialize the Python agent
The OpenShift Python cartridges provide two ways of running a WSGI application.
- The first method uses a preconfigured Apache/mod_wsgi installation. In this case your WSGI application entry point must be defined in the
- The second method relies on you to provide a standalone Python web application script called
app.py. This will typically start an embedded Python WSGI server, with the WSGI application entry point being specified within the
app.pyfile, or be imported from a separate Python code file, such as the
For either method, OpenShift controls the startup of the WSGI server. You must manually integrate the Python agent into your WSGI application. You cannot use New Relic's
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()
Make sure this precedes any other Python module imports appearing in the
wsgi.py file. You do not 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, place these lines at the very top 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
Avoid using the built-in development servers of any web framework. Also, do not use the OpenShift Python 2.6 cartridge or older Django versions. 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, and this would cause the Python agent to report incorrect data. This issue with the wsgiref module is only fixed in Python 2.7.4. The built-in WSGI server in older versions of Django prior to Django 1.4 had a similar problem.
Wrap the WSGI application
If you are using a Python web framework for which New Relic provides 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 must 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)
Override the application name
By default, your data is recorded under the app name Python Application. To change the display name, use 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.
Debug the Python agent
To begin debugging, collect the log output from the Python agent. When the
NEW_RELIC_LOG environment variable is set to
stderr, the 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 get the complete log, copy back from each of your web applications the log file:
By default the Python agent will log at
info level. If New Relic requires an alternate level of logging, you will need to manually add an additional environment variable. For example, to set logging output to
rhc env set NEW_RELIC_LOG_LEVEL=debug -a YOUR_APP_NAME
Environment variables do not take effect immediately, so be sure to restart your web application gears.
debug logging only when requested and only for the time required. Debug logging can produce a lot of output and will bloat your log files. Remove this setting as soon as it is no longer required by running the following command, and then restart your web application gears:
rhc env unset NEW_RELIC_LOG_LEVEL -a YOUR_APP_NAME
Use the logfile to troubleshoot the issue. If you need further assistance, get support at support.newrelic.com
Update 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: