Installation Instructions
=========================

This file provides a brief set of installation instructions for the Python
agent. Also see the New Relic documentation site at:

    http://newrelic.com/docs/python/new-relic-for-python

for additional information.


If you don't read instructions
------------------------------

If you don't want to read through the complete instructions here and on the
New Relic documentation site, you should at least read the following section.

To get the New Relic Python agent working you need to perform three steps.

    1. Install the New Relic Python package.
    2. Generate and edit the Python agent configuration file.
    3. Modify the main WSGI script or module for your application.

To install the Python package into your Python installation run:

    python setup.py install

If installing into a system wide Python installation remember to use the
"sudo" command or run the command as "root".

If you are using pip you can instead do:

    pip install http://host/path/to/newrelic-A.B.C.D.tar.gz

replacing the URL with the actual location of the package from our download
server. This method can also be used in conjunction with a pip requirements
files.

You now need to generate the agent configuration file. To do this, run the
command:

    newrelic-admin generate-config LICENSE-KEY newrelic.ini

When you run this command, replace the argument "LICENSE-KEY" with your
actual license key for your New Relic account. To find your account license
key:

    1. Log into your account. 
    2. Navigate to "Help->Help Center".
    3. Look on the right side-bar under "Get Your License Key".

The final argument is the name of an output file to save the result to.
Here we have used "newrelic.ini" and it should be written to the directory
you run the command.

The "newrelic-admin" command itself should have been installed into the
"bin" directory associated with your Python installation. That is, the same
directory where the "python" executable should be located.

As necessary, move the generated "newrelic.ini" configuration file to a
directory where your Python web application is located.

If you are unable to run the "newrelic-admin" command in your environment
to generate the sample configuration you can instead also download a copy
of the sample configuration from:

    http://download.newrelic.com/python_agent/release/newrelic.ini

If downloading the sample configuration rather than generating it with the
'newrelic-admin' command, you will need to edit it and change the
'license_key' setting to be your account license key yourself.

Now modify the configuration file and first uncomment the line:

    log_file = /tmp/newrelic-python-agent.log

and then change the location of the log file to somewhere more appropriate
but where the user your web application runs as can write to.

Note that if running under Apache/mod_wsgi your application may be running
as the Apache user which usually has restricted access. You may need to set
up a special directory owned by the Apache user where the log file can be
placed. The path should always be an absolute path.

Finally, modify the name your application data will be reported as to the
New Relic UI to something more approriate. The current default is:

    app_name = Python Application

Before you continue, now validate that the package is installed properly
and that details in the configuation file are correct by doing a command
line test. This is done by running the command:

    newrelic-admin validate-config newrelic.ini

The final argument should be the path to the agent configuration file you
just created and edited. See more detailed instructions for this validation
step in a later section of this file.

Having modified the agent configuration file and optionally validated it by
running the command line test, you need to next modify the WSGI application
script file or module which holds your WSGI application entry point and add
at the beginning:

    import newrelic.agent
    newrelic.agent.initialize('/some/path/newrelic.ini')

replacing "/some/path/newrelic.ini" with the actual location of the copy
of the configuration file which you made and edited. This configuration file
must be readable by the user that your web application runs as.

If you have installed the New Relic Python package into a Python virtual
environment the above lines must be added after you have setup "sys.path"
to find your virtual environment.

Within the same WSGI application file, you then need to add a wrapper around
the actual WSGI application entry point. If the WSGI application entry point
is a function declared in the file itself, then you can use a decorator.

    @newrelic.agent.wsgi_application()
    def application(environ, start_response):
        ...

If the WSGI application entry point is a function or object imported from a
different module, then you can wrap it in pre decorator style.

    import django.core.handlers.wsgi
    application = django.core.handlers.wsgi.WSGIHandler()
    application = newrelic.agent.wsgi_application()(application)

You should then restart the specific WSGI hosting mechanism you are using to
reload the WSGI script file or module.

If your WSGI hosting mechanism doesn't use a WSGI script file or module then
see below for further instructions.


What platform can this be used on?
----------------------------------

The New Relic Python package is pure Python code and should be able to run
on any UNIX based platform. It may work on Windows but this hasn't been
tested at this point and is not supported.


What Python version can this be used with?
------------------------------------------

At the present time Python 2.6 or 2.7 is required.


How can I test that the install is okay?
----------------------------------------

You can quickly test that data can get through to the New Relic UI by
running the command:

    newrelic-admin validate-config /some/path/newrelic.ini

The path "/some/path/newrelic.ini" should be replaced with the location of
the agent configuration file you created and edited. The "newrelic-admin"
command should be that for the Python installation you installed the New
Relic Python package into.

This command will run a small test harness which will attempt to report
data to the account corresponding to the license key which you configured
into the agent configuration file.

The name of the application in the New Relic UI which the data will be
reported against is called "Python Agent Test". If the data shows up then
all is okay. After a period the UI will regard that application as inactive
and you can delete the application from the list of your applications using
the tools drop down in the UI.

If data doesn't appear to be getting through to the UI after five minutes
then you should check the log file produced. Ensure you provide this log to
New Relic support if you try to obtain assistance in debugging why the
agent isn't able to report data to the UI.

For assistance if debugging any problems send email to "support@newrelic.com"
including any log files, details of operating system, Python version etc.


I don't use a WSGI script file or module?
-----------------------------------------

Not all WSGI hosting mechanisms expose the WSGI application object so it
can be easily wrapped with the New Relic WSGI application wrapper.

For further details on how to integrate the Python agent into your web
application when using these other WSGI hosting mechanisms see the New
Relic documentation site.

    http://newrelic.com/docs/python/new-relic-for-python
