Python agent and OpenShift

OpenShift is a Platform as a Service (PaaS) solution capable of hosting web applications using various languages, including the 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 pip.

If you are using a setup.py file, install the agent by adding newrelic to the list of third party modules passed to install_requires:

from setuptools import setup

setup(
    name="YourAppName",
    version="1.0",
    description="OpenShift App",
    author="Your Name",
    author_email="example@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 requirements.txt:

newrelic

When you push your project up to OpenShift, this will install the 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 setup.py or requirements.txt file and push your application. Use this syntax:

newrelic==A.B.C.D

Replace A.B.C.D with the version of the the 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 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.

bash

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

bash

$rhc env set NEW_RELIC_LOG=stderr -a YOUR_APP_NAME

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

bash

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

bash

$newrelic-admin validate-config - stdout

This admin script will create a connection and report test transaction data under the application Python Agent Test in your 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 wsgi.py file.
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.py file, or be imported from a separate Python code file, such as the wsgi.py file.

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 the 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 wsgi.py file:

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 app.py with wsgi.py, do not add these lines to wsgi.py.

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 the agent 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 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)`

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 APM user interface. However, from the agent side, we 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:

bash

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

To verify that the configuration has been updated, run:

bash

$rhc env list -a yourappname

Then look for:

bash

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:

bash

$rhc tail -a YOUR_APP_NAME

To get the complete log, copy back from each of your web applications the log file:

$OPENSHIFT_PYTHON_LOG_DIR/python.log

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

bash

$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.

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

bash

$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 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 wsgi.py or app.py 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')

newrelic.agent.initialize(config_file)

Commit the configuration file to your repository and push the change up to OpenShift.

Prepare your application .css-21sua1{background:none;border:none;width:0;padding:0;}

Install the APM Python agent

Update the Python agent

Use Python agent environment variables

Test the agent installation

Initialize the Python agent

Wrap the WSGI application

Override the application name

Debug the Python agent

Update agent configuration file

Prepare your application