--- title: Python agent and OpenShift source: https://docs.newrelic.com/docs/apm/agents/python-agent/hosting-services/python-agent-openshift --- [OpenShift](http://www.openshift.com/ "Link opens in a new window") is a Platform as a Service (PaaS) solution capable of hosting web applications using various languages, including the Python agent. ## Prepare your application [#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](https://developers.openshift.com/en/python-overview.html "Link opens in a new window") for more information. ## Install the APM Python agent [#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 `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`: ```py 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 [#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 `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 [#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. ```sh 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: ```sh rhc env set NEW_RELIC_LOG=stderr -a YOUR_APP_NAME ``` To verify that the environment variables are being set, run: ```sh 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 [#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: ```sh 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](https://support.newrelic.com "Link opens in a new window"). ## Initialize the Python agent [#initializing-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: ```py 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 [#wrapping-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. ````py 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. ````py import myapp application = myapp.WSGIHandler() application = newrelic.agent.WSGIApplicationWrapper(application) ``` ```` | ## Override the application name [#overriding-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: ```sh rhc env set NEW_RELIC_APP_NAME='Web Site (Production)' -a yourappname ``` To verify that the configuration has been updated, run: ```sh rhc env list -a yourappname ``` Then look for: ```sh [output] 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 [#debugging-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: ```sh 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: ```sh 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: ```sh 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](https://support.newrelic.com "Link opens in a new window") ## Update agent configuration file [#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](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-configuration). 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: 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: ```ini [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. 2. 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: ```py 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) ``` 3. Commit the configuration file to your repository and push the change up to OpenShift.