Lastest Build Status

Master Branch https://github.com/collective/collective.logbook

Introduction

For anonymous users Plone generates an Error Page, which contains an error number. But what to do with this error number?

You have to log into your plone site, go to the ZMI, check the error_log object and probably construct the url by hand to get the proper error with this error number, e.g.:

http://localhost:8080/Plone/error_log/showEntry?id=1237283091.10.529903983894

If you are lucky, you will find the error by this number for further investigation. If not, then maybe number of occured errors have exceeded the number of exceptions to keep, or you are on the wrong Zope instance if you run a cluster setup with a ZEO server, or maybe the Zope instance was restarted in between, which caused a reset of all logged errors.

Not really smooth this behaviour.

Would it not be better to have a nice frontend where you can paste the error number to a field and search for it? Keep all logged error messages persistent, also when Zope restarts? Keep only unique errors and not a thousand times the same Error? Get an email notification when a new, unique error occured, so that you know already what’s going on before your client mails this error number to you?

If you think that this would be cool, collective.logbook is what you want.

Quickstart

After installation, you can configure your logbook settings in the controlpanel:

http://localhost:8080/Plone/@@logbook-controlpanel

All occured errors get listed in the logbook view:

http://localhost:8080/Plone/@@logbook

As the logbook view diplays real errors that occured in your Plone site, it will probably be empty at the first time.

To raise an error by intent, collective.logbook ships with two URL routes, that do this job for you for testing purpose:

http://localhost:8080/Plone/@@error-test

This will raise an expected RuntimeError, which should be logged in the logbook view. Calling this URL multiple times, should reference the error, because of the same error signature.

This means, if you have configured Email notification, you will just be notified once. The same is true for the webhooks, which will be described later.

To simulate different errors, you can browse this URL:

http://localhost:8080/Plone/@@random-error-test

This raises different errors, and multiple calls to this URL fills up the logbook view with the occured errors, sorted by the most often happened errors or to be more precisely, the errors that are referenced most often appear first.

Web hooks

collective.logbook provides ability to HTTP POST error message to any web service when an error happens in Plone. This behavior is called a web hook.

Use cases

• Showing Plone errors real-time in Skype chat

• Routing errors to different websites and services via Zapier

In Site Setup > Logbook you can enter URLs where HTTP POST will be asynchronously performed on a traceback. HTTP POST payload is an message from Logbook, containing a link for further information.

Installation

These instructions assume that you already have a Plone buildout that’s built and ready to run.

Edit your buildout.cfg file and look for the eggs key in the instance section. Add collective.logbook to that list. Your list will look something like this:

eggs =
    ...
    collective.logbook

Run buildout.

Activate the add-on via Site Setup > Add ons.

Compatibility

This extension works with Plone 4 and Plone 5.

Browser Testing

With collective.logbook enabled, it is simple to see all errors occured in your Plone site:

>>> portal = self.getPortal()
>>> browser = self.getBrowser()
>>> browser.addHeader('Authorization', 'Basic admin:secret')

>>> def simulate_error(msg='Test error'):
...     try:
...         raise RuntimeError(msg)
...     except RuntimeError:
...         # Acquire the error_log object the same way Zope does. See module: Zope2.App.startup
...         import sys
...         from Acquisition import aq_acquire
...         error_log = aq_acquire(self.portal, '__error_log__', containment=1)
...         error_log.raising(sys.exc_info())

Remember some URLs:

>>> portal_url = portal.absolute_url()
>>> logbook_controlpanel_url = portal_url + "/@@logbook-controlpanel"
>>> logbook_test_error_url = portal_url + "/@@error-test"
>>> logbook_url = portal_url + "/@@logbook"

Browse to the @@logbook view:

>>> browser.open(logbook_url)
>>> 'Congratulations, there are 0 Errors in your Plone Site!' in browser.contents
True

Now lets create an error with the @@error-test view, which raises an expected RuntimeError:

>>> simulate_error()
>>> browser.open(logbook_url)
>>> "There are 1 saved (unique) Tracebacks and 0 referenced Tracebacks" in browser.contents
True

The same error will be referenced and not logged again:

>>> simulate_error()
>>> browser.open(logbook_url)
>>> "There are 1 saved (unique) Tracebacks and 1 referenced Tracebacks" in browser.contents
True

There is also a @@random-error-test view, which randomly selects different tracebacks for testing.

Logbook logging can be deactivated on purpose in the @@logbook-controlpanel view:

>>> browser.open(logbook_controlpanel_url)
>>> browser.getControl(name="form.widgets.logbook_enabled:list").value = []
>>> browser.getControl(name="form.buttons.save").click()

Errors should not be logged anymore:

>>> simulate_error()
>>> browser.open(logbook_url)
>>> "There are 1 saved (unique) Tracebacks and 1 referenced Tracebacks" in browser.contents
True

Finally, we remove all errors:

>>> browser.open(logbook_url)
>>> browser.getControl(name="form.button.deleteall").click()
>>> 'Congratulations, there are 0 Errors in your Plone Site!' in browser.contents
True

Technical Details

This section gives an overview how collective.logbook works.

from Products.SiteErrorLog.SiteErrorLog import SiteErrorLog

_raising = SiteErrorLog.raising

def raising(self, info):
    enty_url = _raising(self, info)
    notify(ErrorRaisedEvent(self, enty_url))
    return enty_url

<!-- default storage adapter -->
<adapter
    for="*"
    factory=".storage.LogBookStorage"
  />

<subscriber
    for=".interfaces.INotifyTraceback"
    handler=".events.mailHandler"
  />

1.0.0 (2020-04-29)

• Fix Emails are generated in HTML but sent in plain text [ramonski]

• Clean installation/uninstallation [rafaelbco]

• Code cleanup [rafaelbco]

• Python 3 compatibility [ramonski]

• Updated build system and fixed TravisCI [ramonski]

• Fix #19: Cannot handle traceback when error occurs when accessing a method of a view [rafaelbco]

0.9.1 (2018-07-17)

• Fix #17 by making sure the context of a log entry is not acquisition-wrapped. [rafaelbco]

0.9.0 (2017-02-23)

• Fix #11 by adding upgrade step to create registry records. [rafaelbco]

• Fix #12: Error while trying to login into the ZMI. [rafaelbco]

0.8 (2017-01-27)

• Complete Code Rework, Cleanup and Refactoring for Plone 4/5 Compatibility. [ramonski]

• add Plone 5.0 pypi classifier, update README.rst to mention Plone 5 compatibility [tkimnguyen]

0.8b2 (2016-10-24)

• Cleanup/doc update for Plone 5 version [glemignot]

0.8b1 (2016-10-21)

• Initial port to Plone 5 [glemignot]

0.7 (2014-06-12)

• Fixed tests [ramonski]

• Add Plone4.3-compatibility. [WouterVH]

• Added Web Hook support [miohtama, sevanteri]

0.6 (2011-11-28)

• Log exceptions within exception handler [jfroche]

• Move delete all button, add show all button, show error message if error was not found. [jfroche]

• Add option that disable browsing stored errors. This option become useful if you have a site with many errors. [jfroche]

0.5 (2011-08-16)

• Move storage to OOBTree to avoid that logging error transactions get bigger and bigger. Add upgradehandler accordingly. [gotcha]

• Fix saving configuration. [gotcha]

• Logging initialization at startup time was broken with Zope 2.13 at least. [gotcha]

• Added support for i18n [macagua]

• Added support for Spanisn translation [macagua]

• Move the mail notifier into a view to use a template for better HTML email handling. [rossp]

• Include the REQUEST HTML for more useful debugging and troubleshooting. [rossp]

0.4 (2010-08-02)

• Add “z3c.autoinclude.plugin” entry point, so in Plone 3.3+ you can avoid loading the ZCML file. [WouterVH]

• expose send mail exception to the log message this fixes http://plone.org/products/collective.logbook/issues/3 [naro]

• fixed email notification for plone4 since MailHost.send signature changed (see Upgrade Information) [fRiSi]

• store and show user and date for referenced errors too this fixes http://plone.org/products/collective.logbook/issues/2 [fRiSi]

0.3.1 (2009-03-18)

• the error handler now starts a new transaction before saving it into the logbook [ramonski]

0.3 (2009-03-17)

• 0.2 release was broken, sorry for this re-release [ramonski]

• fixed issues which caused some ugly Database Conflict errors [ramonski]

• removed all Zope2.app() stuff [ramonski]

• mail handler stops when no emails specified [ramonski]

• fixed uninstall method of properties [ramonski]

0.2 (2009-03-17)

• added a configlet for plone control panel [ramonski]

• added a default notify traceback email handler [ramonski]

• added propert install/uninstall methods for the SiteErrorLog patch [ramonski]

• added 2 properties in the application root [ramonski]

0.1 - Unreleased

• Initial release [ramonski]