Honeybadger for Clojure

Hi there! You've found Honeybadger's guide to Clojure exception and error tracking. Once installed, Honeybadger will report errors in your Clojure application.

Getting Started

Source Code

The library only has one public endpoint: notify. You can pass notify a String, or anything which inherits from Throwable (e.g. Exception):

• :api-key is the only required entry in the configuration map.
• notify returns a Manifold deferred wrapping the ID (String) of the newly-created Honeybadger fault--or nil if a filter (see below) caused the data not to be sent to Honeybadger. Because a deferred is used, the call returns immediately, not blocking your (e.g., web server) thread. This comes with the typical Clojure caveats about exceptions thrown on background threads, so I strongly recommend dereferencing these calls on the main thread unless / until you have an async error handling plan in place.
• Honeybadger fault IDs can be handy--log them, pass them to other systems, or display them to your users as incident identifiers they can send to your support team. Manifold offers ways of receiving this data asynchronously, but for a simple (synchronous) approach, simply deref the return value:

Metadata

The optional third parameter to notify can be used to pass all manner of additional Honeybadger metadata. The following example shows all possible metadata values:

All metadata is optional, so pick and choose what is useful for your project. Keys and tags can be strings or keywords. :context and :request support nested values. If you're working with Ring, use the corresponding ring-honeybadger library and the :request metadata will be populated for you.

Filters

For more advanced behavior, the library allows us to provide a sequence of functions which will be invoked with all key details (viz. exception + configuration) prior to reporting to Honeybadger. These functions can be used to transform the data in arbitrary ways, or they can return nil, halting the function chain and indicating that nothing should be reported.

For maximum flexibility we can provide a custom function, but we can handle many common cases with the preexisting filters / filter combinators in honeybadger.filter:

In this example, the first two filters are used to control which errors get reported to Honeybadger, and the third is used to transform the data we do send.

More precisely, the first two filter lines say only report errors in the production environment, and don't report errors of type ArithmeticException. The third filter uses the obscure-params convenience function to replace parameters at the given keypaths with a fixed string so that sensitive parameters are not sent to be stored in Honeybadger. (Of course there isn't a param at [:config :password] in this case as we haven't provided any request metadata, so the filter won't change anything here).

To make filtering both possible and convenient, all details about the error / config / metadata / etc. are bundled up in a consistent format which filters are expected to consume and produce (with the sole exception of filters which return nil to suppress reporting of an error). You can see the details of that format at honeybadger.schemas/Event, and if you use Prismatic/schema in your own project, then you can use the provided schemas to enforce correctness. One detail worth calling out is that all map keys are normalized to keywords so that filters don't have to handle variations.

Here's an example of a fully-custom filter, applying a logged-in tag to all exception reports where we have a session-id:

Using that is as simple as adding tag-logged-in to the list of filters.

Filters that suppress certain errors can typically be written with a simple predicate function over Events which is passed to only? or except?:

Last but not least, note that the (deferred) value returned by notify allows us to ascertain whether or not a given error was reported because it will be nil iff the error reporting was filtered out. We can use this to take conditional actions:

Ring

If you'd like to use this project with Ring, check out camdez/ring-honeybadger.