Yeller Notifier for Clojure

This is the Clojure client library for http://yellerapp.com. It lets you automatically detect errors in your application, and reports them via Yeller's API, so you can debug and fix them quickly.

Integrating Yeller into your Clojure App

Installation

Grab it from clojars:

[yeller-clojure-client "1.2.1"]

For Ring Apps

The easiest way to start reporting errors to Yeller is via the Ring middleware:

(require 'yeller.clojure.ring)

(yeller.clojure.ring/wrap-ring
  your-app
  {:token "YOUR TOKEN HERE"
   :environment "production"})

This middleware captures exceptions thrown whilst calling your-app, and sends them to Yeller, including a whole bunch of context out of the http request. Note that it raises exceptions further up the stack, so you can render them how you want to in a higher middleware.

For Other Clojure Apps

If you're working on an non-ring app, or you want to send errors from part of your app that isn't ring, you can use the client directly:

(require '[yeller.clojure.client :as yeller])

(def client (yeller/client {:token "YOUR API TOKEN HERE"}))

(try
  ; your exception throwing code here
  (catch Exception e
    (yeller/report client e)))

Setting An Uncaught Exception Handler

Yeller's client returns an object that satisfies java.lang.Thread.UnhandledExceptionHandler. To set it as the default uncaught thread exception handler:

(Thread/setDefaultUncaughtExceptionHandler yeller-client)

Note that it does not do this by default - touching global mutable state across the JVM in libraries is real bad.

Shipping Extra Information

yeller.clojure.client/report takes an optional map of optional additional information.

If you're using the ring middleware, it includes a lot of information about the http request the user was seeing out of the box, but you can add extra information by adding :yeller/context as an extra key to the request.

{
   ;; the url the user was hitting when this exception happened
   :url "http://example.com"

   ;; the environment the application is deployed into
   :environment "production"

   ;; which handler is responding to the request
   :location "my-ring-handler"

   ;; a map of any additional debugging information you want
   ;; it's suggested you include as much as possible here -
   ;; it'll save you in the future
   :custom-data
   {:params ...}
}

Robustness

The Yeller Clojure Client builds on top of the java client

As such, it inherits that client's retry functionality - if there's an error communicating with yeller's servers, the client will retry multiple times.

Application Packages

Yeller can highlight stacktrace lines coming from your application, and hide those that don't. This can make a big difference when reading what would otherwise be very long Clojure stacktraces:

To activate this feature, Yeller has to know which packages are the root of your application. By default it guesses based on the name of the leiningen project via project.clj (reading it from the uberjar if you're running like that in production), but if that's not available, you can specify them manually:

(yeller/client
  {:token "YOUR TOKEN HERE"
   ; other options to the client go here
   :application-packages ["com.myapp"]})

Note that this doesn't affect which frames you can see - you can always display all the frames:

Questions

If you have any questions, feel free to shoot me an email, .

Bugs? Improvements? This Client Library is Open Source

If you're curious about this library, it's open source, and available on: github

Clients