IMPORTANT---------Version 1.0.12 has a *SERIOUS* uninstallation bug in the file manifest that will remove all the files on your filesystem if you try and do a ``pip remove newrelic_plugin_agent``.

Version 1.0.13 and greater will attempt to fix the issue when doing a ``pip upgrade`` *BUT* you should also run the script ``fix_nrp_manifest.py`` (or the older ``fix_removal.py``) to clean up the erroneous entries in the installed-files.txt manifest file in your python site-packages directory.

If you do not see "Fixed a serious uninstallation problem in previous version" in the output, then it did not find a problem, which means more diagnosing is required. Before opening a ticket, you can run the following commands to try and find the problem:

If those do not provide output, you will need to look for your Python site-packages directory. You can manually uninstall ``newrelic_plugin_agent`` if you find the appropriate site packages directory where it was installed and remove the ``newrelic_plugin_agent`` directory and the ``newrelic_plugin_agent-1.0.12-*.egg-info`` directory.

Configuration File Note-----------------------The configuration file uses YAML as its format. Most tickets for non-working installs are due to configuration file formatting errors. Please make sure you are properly formatting your configuration file prior to submitting a ticket. YAML is a whitespace dependent markup format. More information on writing proper YAML can be found at http://yaml.org.

2. Copy the configuration file example from ``/opt/newrelic_plugin_agent/newrelic_plugin_agent.cfg`` to ``/etc/newrelic/newrelic_plugin_agent.cfg`` and edit the configuration in that file.

3. Make a ``/var/log/newrelic`` directory and make sure it is writable by the user specified in the configuration file

4. Make a ``/var/run/newrelic`` directory and make sure it is writable by the user specified in the configuration file

5. Run the app:

::

$ newrelic_plugin_agent -c PATH-TO-CONF-FILE [-f]

Where ``-f`` is to run it in the foreground instead of as a daemon.

Sample configuration and init.d scripts are installed to ``/opt/newrelic_plugin_agent`` in addition to a PHP script required for APC monitoring.

Installing Additional Requirements----------------------------------

To use the MongoDB the ``mongodb`` library is required. For the pgBouncer or PostgreSQL plugin you must install the ``psycopg2`` library. To easily dothis, make sure you have the latest version of ``pip`` installed http://www.pip-installer.org/) This should be done after installing the agent itself:

::

$ pip install newrelic_plugin_agent[mongodb]

or::

$ pip install newrelic_plugin_agent[pgbouncer]

or::

$ pip install newrelic_plugin_agent[postgresql]

If this does not work for you, make sure you are running a recent copy of ``pip`` (>= 1.3).

Plugin Configuration Stanzas----------------------------Each plugin can support gathering data from a single or multiple targets. To support multiple targets for a plugin, you create a list of target stanzas:

While you can use the multi-target format for a plugin's configuration stanza like:

::

plugin_name: - name: target_name host: localhost foo: bar

You can also use a single mapping like follows:

::

plugin_name: name: target_name host: localhost foo: bar

The fields for plugin configurations can vary due to a plugin's configuration requirements. The name value in each stanza is only required when using multiple targets in a plugin. If it is only a single target, the name will be taken from the server's hostname.

APC Installation Notes----------------------Copy the ``apc-nrp.php`` script to a directory that can be served by your web server or ``php-fpm`` application. Edit the ``newrelic_plugin_agent`` configuration to point to the appropriate URL.

Apache HTTPd Installation Notes-------------------------------Enable the HTTPd server status page in the default virtual host. The following example configuration snippet for Apache HTTPd 2.2 demonstrates how to do this:

::

<location server-status=""> SetHandler server-status Order deny,allow Deny from all Allow from all </location>

The agent requires the extended information to parse metrics. If you are not seeing any metrics on your graphs for Apache verify that you have enabled ``ExtendedStatus``, the default is off so you must enable it. In your global Apache HTTP configuration you need to enable exetended status using:

::

ExtendedStatus On

If you are monitoring Apache HTTPd via a HTTPS connection you can use the ``verify_ssl_cert`` configuration value in the httpd configuration section to disable SSL certificate verification.

Memcached Installation Notes----------------------------The memcached plugin can communicate either over UNIX domain sockets using the path configuration variable or TCP/IP using the host and port variables. Do not include both.

MongoDB Installation Notes--------------------------You need to install the pymongo driver, either by running ``pip install pymongo`` or by following the "`Installing Additional Requirements`_" above. Each database you wish to collect metrics for must be enumerated in the configuration.

There are two configuration stanza formats for MongoDB. You must use one or the other, they can not be mixed. For non-authenticated polling, you can simply enumate the databases you would like stats from as a list:

Nginx Installation Notes------------------------Enable the Nginx ``stub_status`` setting on the default site in your configuration. The following example configuration snippet for Nginx demonstates how to do this:

::

location /nginx_stub_status { stub_status on; }

If you are monitoring Nginx via a HTTPS connection you can use the ``verify_ssl_cert`` configuration value in the httpd configuration section to disable SSL certificate verification.

pgBouncer Installation Notes----------------------------The user specified must be a stats user.

PostgreSQL Installation Notes-----------------------------By default, the specified user must be superuser to get PostgreSQLdirectory listings. To skip those checks that require superuserpermissions, use the ``superuser: False`` setting in the configurationfile.

Several of the checks take O(N) time where N is the number of relationsin the database. If you need to use this on a database with a very largenumber of relations, you can skip these, using ``relation_stats: False``.

The Redis plugin can communicate either over UNIX domain sockets using the path configuration variable or TCP/IP using the host and port variables. Do not include both.

Riak Installation Notes-----------------------If you are monitoring Riak via a HTTPS connection you can use the ``verify_ssl_cert`` configuration value in the httpd configuration section to disable SSL certificate verification.

UWSGI Installation Notes------------------------The UWSGI plugin can communicate either over UNIX domain sockets using the path configuration variable or TCP/IP using the host and port variables. Do not include both.

Troubleshooting---------------- If the installation does not install the ``newrelic_plugin_agent`` application in ``/usr/bin`` then it is likely that ``setuptools`` or ``distribute`` is not up to date. The following commands can be run to install ``distribute`` and ``pip`` for installing the application:

- If the application installs but doesn't seem to be submitting status, check the logfile which at ``/tmp/newrelic_plugin_agent.log`` if the default example logging configuration is used.- If the agent starts but dies shortly after ensure that ``/var/log/newrelic`` and ``/var/run/newrelic`` are writable by the same user specified in the daemon section of the configuration file.- If the agent has died and won't restart, remove any files found in ``/var/run/newrelic/``- If using the Apache HTTP plugin and your stats are blank, ensure the ExtendedStatus directive is on.