Logging with Java can be maddeningly, unnecessarily hard. Particularly if all you want is something simple that works out the box.
tools.logging helps, but it doesn't save you from the mess of logger dependencies and configuration hell.
Timbre is an attempt to make simple logging simple and more complex logging possible.
Timbre was built in a day after I finally lost my patience trying to configure Log4j. I tried to keep the design simple and sensible but I didn't spend much time thinking about it so there may still be room for improvement. In particular the configuration and appender formats are still subject to change.
Depend on [timbre "0.5.1-SNAPSHOT"]
in your project.clj
and use
the library:
(ns my-app
(:use [timbre.core :as timbre :only (trace debug info warn error fatal spy)])
By default, Timbre gives you basic print output to *out*
/*err*
at a debug
logging level:
(info "This will print")
=> 2012-May-28 17:26:11:444 +0700 INFO [timbre.tests] - This will print
(trace "This won't print due to insufficient logging level")
=> nil
There's little overhead for checking logging levels:
(time (trace (Thread/sleep 5000)))
=> "Elapsed time: 0.054 msecs"
(time (when true))
=> "Elapsed time: 0.051 msecs"
First-argument exceptions generate a stack trace:
(info (Exception. "Oh noes") "arg1" "arg2")
=> 2012-May-28 17:35:16:132 +0700 INFO [timbre.tests] - arg1 arg2
java.lang.Exception: Oh noes
NO_SOURCE_FILE:1 timbre.tests/eval6409
Compiler.java:6511 clojure.lang.Compiler.eval
[...]
Easily adjust the current logging level:
(timbre/set-level! :warn)
And the default timestamp formatting for log messages:
(timbre/set-config! [:shared-appender-config :timestamp-pattern]
"yyyy-MMM-dd HH:mm:ss ZZ")
(timbre/set-config! [:shared-appender-config :locale]
(java.util.Locale/GERMAN))
Enable the standard Postal-based email appender:
(timbre/set-config! [:shared-appender-config :postal]
^{:host "mail.isp.net" :user "jsmith" :pass "sekrat!!1"}
{:from "me@draines.com" :to "foo@example.com"})
(timbre/set-config! [:appenders :postal :enabled?] true)
Rate-limit to one email per message per minute:
(timbre/set-config! [:appenders :postal :max-message-per-msecs] 60000)
And make sure emails are sent asynchronously:
(timbre/set-config! [:appenders :postal :async?] true)
Writing a custom appender is easy:
(timbre/set-config!
[:appenders :my-appender]
{:doc "Hello-world appender"
:min-level :debug
:enabled? true
:async? false
:max-message-per-msecs nil ; No rate limiting
:fn (fn [{:keys [ap-config level error? instant timestamp
ns message more] :as args}]
(when-not (:production-mode? ap-config)
(apply println timestamp "Hello world!" message more)))
And because appender fns are just regular Clojure fns, you have unlimited power: write to your database, send a message over the network, check some other state (e.g. environment config) before making a choice, etc.
See (doc timbre/config)
for more information on appenders.
ClojureWerkz is a growing collection of open-source, batteries-included Clojure libraries that emphasise modern targets, great documentation, and thorough testing.
Reach me (Peter Taoussanis) at ptaoussanis at gmail.com for questions/comments/suggestions/whatever. I'm very open to ideas if you have any!
I'm also on Twitter: @ptaoussanis.
Copyright © 2012 Peter Taoussanis
Distributed under the Eclipse Public License, the same as Clojure.
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close