Introduction
------------
This package offers instrumentation for NewRelic ( http://www.newrelic.com ). Currently the catalog-tool, transformchains and zope-events are instrumented. A transform is included to support RUM (Real-User-Monitoring): it inserts small snippets of javascript at the top and bottom of the rendered pages. RUM does not work in the ZMI (Zope Management Interface).
Installation
------------
You can add this egg 'collective.newrelic' to your eggs and it will pull in the 'newrelic' egg too. ::
[buildout]
# either pin versions as shown below...
versions=versions
[versions]
newrelic = 2.6.0.5
repoze.xmliter = 0.5
# update to 1.0.9 on next release:
collective.newrelic = 1.0.8
# ...or allow picked versions and risk breakage on product updates
#allow-picked-versions = true
parts +=
newrelic
[newrelic]
recipe = zc.recipe.egg:scripts
eggs = newrelic
[instance]
eggs +=
collective.newrelic
# make sure newrelic itself is enabled and set the path to your newrelic.ini file
environment-vars +=
NEW_RELIC_ENABLED true
NEW_RELIC_CONFIG_FILE ${buildout:directory}/newrelic.ini
NEW_RELIC_ENVIRONMENT development
# when using supervisor, setting environment variables is slightly different:
#[supervisor]
#supervisord-environment=NEW_RELIC_ENABLED=true,NEW_RELIC_CONFIG_FILE=${buildout:directory}/newrelic.ini,NEW_RELIC_ENVIRONMENT=development
A number of additional settings can optionally be configured using environment variables, see http://docs.newrelic.com/docs/python/python-agent-configuration#environment-variables for details.
Customizing your newrelic.ini file is more advised though, see below.
The NEW_RELIC_ENABLED and NEW_RELIC_CONFIG_FILE variables need to be set for the newrelic agent to work though.
Omitting NEW_RELIC_ENVIRONMENT variable will mean the [newrelic] part is loaded without additional [newrelic:YOURENVNAME] settings.
Please note: the newrelic package needs python >= 2.5. This package will not work on Plone 3.
Use
---
To enable the logging to newrelic.com, create an account at newrelic.com and get your license key. Create a 'newrelic.ini' file in the root of your project. Either by copying the template from this package or the newrelic package or run ::
$ bin/newrelic-admin generate-config YOUR-LICENSE-KEY newrelic.ini
This will create a newrelic.ini file in the current directory.
You might want to validate your generated file using ``newrelic-admin validate-config newrelic.ini``
The default profile is 'staging', this can be changed in the `__init__.py` in the patches directory. You can change the default name of 'Python Application (Staging)' in the newrelic.ini file. To get sensible database-traces change ::
transaction_tracer.record_sql = obfuscated
to ::
transaction_tracer.record_sql = raw
Example usage
=============
In utils you find a few helper functions to wrap (parts) of your products and/or plone and/or any python module.
For example you could make a simple egg called myproduct.newrelic with only an `__init__.py`.
Within that file you have a '''initialize''' function, therein you use the helper functions for further wrapping.
Full class+function wrapping of an entire module
------------------------------------------------
::
from plone.app import viewletmanager as plone_viewletmanager
from collective.newrelic.utils import wrap_module_classes_functions
class_function_modules = [plone_viewletmanager, ]
wrapped_methods = wrap_module_classes_functions(class_function_modules)
print len(wrapped_methods)
Single class wrapping
---------------------
::
from zope.tal.talinterpreter import TALInterpreter
from collective.newrelic.utils import wrap_class_found_functions
wrapped_methods = wrap_class_found_functions(TALInterpreter)
print len(wrapped_methods)
Pin point precision wrapping of single class function
-----------------------------------------------------
::
from zope.tal.talinterpreter import TALInterpreter
from collective.newrelic.utils import wrap_class_function
wrapped_methods = wrap_class_function(TALInterpreter, TALInterpreter.__call__)
print wrapped_methods
"TALInterpreter.__call__"
Troubleshooting
===============
If you see a message ``The Python Agent is not enabled.`` in the Zope instance log, first check if ``NEW_RELIC_ENABLED`` environment variable was set correctly.
If this is ok, check your ``newrelic.ini`` file and make sure the profile you are using (eg ``[newrelic:staging]``) has ``monitor_mode = true``.
It can also mean that the newrelic.ini cannot be found. Make sure the path to your newrelic.ini file is correctly set using the ``NEW_RELIC_CONFIG_FILE`` environment variable.
If you see a message ``A valid account license key cannot be found.``, check that you have a valid license key and make sure it is correctly set in the ``newrelic.ini`` file.
References
==========
http://www.newrelic.com
http://newrelic.com/docs/python/python-agent-installation
http://docs.newrelic.com/docs/python/testing-the-python-agent
Change history
==============
1.0.9 (2014-01-02)
-------------------
- Introduce and explain NEW_RELIC_ENABLED and NEW_RELIC_CONFIG_FILE enviroment variables [fiterbek]
- Fix documentation formatting [fiterbek]
- Print nicer info message [fiterbek]
- Update documentation for NEW_RELIC_ENVIRONMENT enviroment variables [puittenbroek]
1.0.8 (2013-10-02)
-------------------
- Fix: TALInterpreter patch fails when PageTemplate is made by value instead of file [puittenbroek]
- Added dependency on repoze.xmliter [fiterbek]
1.0.7 (2013-07-11)
-------------------
- Documentation typos [khink]
- Documentation checking for pypi release [puittenbroek]
- Patch cron4plone tick (if present) to make it a backgroundtask [puittenbroek]
- Improve hook logic to worker properly in ZMI [puittenbroek]
1.0.6 - unreleased
-------------------
- Changed naming of transactions, now based on view/templates being used [puittenbroek]
- Ignore transactions for resource files (js, css, kss(?)) [puittenbroek]
1.0.5 - unreleased
-------------------
- First production test version
prior 1.0.5
-------------------
- Inital code implemtation and testing