Skip to main content

Error/Exception collector and reporter

Project description


zilch is a small library for recording and viewing exceptions from Python. This library is inspired by (and uses several of the same functions from) David Cramer’s Sentry, but aims to implement just the core features in a smaller code/feature footprint.



Basic Usage

Reporting an Exception

In the application that wants to report errors, import zilch and configure the reporter to record directly to the database:

from import SQLAlchemyStore
import zilch.client = SQLAlchemyStore('sqlite:///exceptions.db')

Then to report an exception:

from zilch.client import capture_exception
    # do something that explodes
except Exception, e:

The error will then be recorded in the database for later viewing.

Advanced Usage

In larger cluster scenarios, or where latency is important, the reporting of the exception can be handed off to ZeroMQ to be recorded to a central recorder over the network. Both the client and recording machine must have ZeroMQ installed.

To setup the client for recording:

import zilch.client

zilch.client.recorder_host = "tcp://localhost:5555"

Then to report an exception:

from zilch.client import capture_exception
    # do something that explodes
except Exception, e:

The exception will then be sent to the recorder_host listening at the recorder_host specified.

Recording Exceptions Centrally

The recorder uses ZeroMQ to record exception reports delivered over the network. To run the recorder host, on the machine recording them run:

>> zilch-recorder tcp://localhost:5555 sqlite:///exceptions.db

Without a Recorder running, ZeroMQ will hold onto the messages until it is available. After which point, it will begin to block (In the future, an option will be added to configure the disk offloading of messages).

The recorder will create the tables necessary on its initial launch.

Viewing Recorded Exceptions

zilch comes with a Pyramid web application to view the database of recorded exceptions. Once you have installed Pyramid and WebHelpers, you can run the web interface by typing:

>> zilch-web sqlite:///exceptions.db

Additional web configuration parameters are available to designate the host/port that the web application should bind to (viewable by running zilch-web with the -h option).


zilch is offered under the MIT license.


zilch is made available by Ben Bangert.


zilch is considered feature-complete as the project owner (Ben Bangert) has no additional functionality or development beyond bug fixes planned. Bugs can be filed on github, should be accompanied by a test case to retain current code coverage, and should be in a Pull request when ready to be accepted into the zilch code-base.

For a more full-featured error collector, Sentry now has a stand-alone client that no longer requires Django called Raven. zilch was created before Raven was available, and the author now uses Raven rather than zilch most of the time.


0.1.3 (01/13/2012)


  • Applied pull request from Marius Gedminas to add prefix option support to the error view webapp.

0.1.2 (08/07/2011)

Bug Fixes

  • Cleanup session at end of request.

0.1.1 (07/25/2011)

Bug Fixes

  • Fix bug with webob imports in

0.1 (07/25/2011)


  • Exception reporting via SQLAlchemy and/or ZeroMQ

  • Recording Store can be pluggable

  • WSGI Middleware to capture exceptions with WSGI/CGI environment data

  • Web User Interface for the recorder to view collected exceptions

  • Event tagging to record additional information per exception such as the Hostname, Application, etc.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

zilch-0.1.3.tar.gz (26.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page