Merge branch 'dev': v0.7.0.

This commit is contained in:
Peter Taoussanis 2012-07-13 18:10:03 +07:00
commit bfa33a7e8e
5 changed files with 67 additions and 46 deletions

View File

@ -1,9 +1,14 @@
Current [semantic](http://semver.org/) version:
```clojure
[com.taoensso/timbre "0.6.1"] ; Please note that the repo and ns have changed recently
[com.taoensso/timbre "0.7.0"]
```
**Breaking changes** since _0.6.x_ (see updated README examples for any necessary changes):
* Affecting **users of the standard email appender**:
* Postal appender moved to own ns: `taoensso.timbre.appenders.postal`.
* `com.draines/postal` no longer automatically included as a dependency.
# Timbre, a (sane) logging library for Clojure
Logging with Java can be maddeningly, unnecessarily hard. Particularly if all you want is something *simple that works out the box*.
@ -37,7 +42,7 @@ lein2 all test
Depend on Timbre in your `project.clj`:
```clojure
[com.taoensso/timbre "0.6.1"]
[com.taoensso/timbre "0.7.0"]
```
and `use` the library:
@ -99,12 +104,11 @@ Configuring Timbre couldn't be simpler. Let's check out (some of) the defaults:
:appenders
{:standard-out { <...> }
:postal { <...> }}
<...> }
:shared-appender-config
{:timestamp-pattern "yyyy-MMM-dd HH:mm:ss ZZ"
:locale nil
:postal nil}}
:locale nil}}
```
Easily adjust the current logging level:
@ -127,14 +131,27 @@ Filter logging output by namespaces:
(timbre/set-config! [:ns-whitelist] ["some.library.core" "my-app.*"])
```
Enable the standard [Postal](https://github.com/drewr/postal)-based email appender:
### Email Appender
To enable the standard [Postal](https://github.com/drewr/postal)-based email appender, add the Postal dependency to your `project.clj`:
```clojure
[com.draines/postal "1.8.0"]
```
And add the appender to your `ns` declaration:
```clojure
(:require [taoensso.timbre.appenders (postal :as postal-appender)])
```
Then adjust your Timbre config:
```clojure
(timbre/set-config! [:appenders :postal] postal-appender/postal-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:
@ -180,9 +197,7 @@ And these certaily do the job. But as with many Java tools, they can be a little
Let's add it to our app's `ns` declaration:
```clojure
(ns my-app
(:use [taoensso.timbre :as timbre :only (trace debug info warn error fatal spy)]
[taoensso.timbre.profiling :as profiling :only (p profile)]))
(:use [taoensso.timbre.profiling :as profiling :only (p profile)])
```
Wrap forms that you'd like to profile with the `p` macro and give them a name:
@ -225,7 +240,7 @@ And since `p` and `profile` **always return their body's result** regardless of
A simple **sampling profiler** is also available: `taoensso.timbre.profiling/sampling-profile`.
## Timbre Supports the ClojureWerkz Project Goals
## Timbre supports the ClojureWerkz Project Goals
ClojureWerkz is a growing collection of open-source, batteries-included [Clojure libraries](http://clojurewerkz.org/) that emphasise modern targets, great documentation, and thorough testing.

View File

@ -1,10 +1,9 @@
(defproject com.taoensso/timbre "0.6.1"
(defproject com.taoensso/timbre "0.7.0"
:description "Simple, flexible, all-Clojure logging. No XML!"
:url "https://github.com/ptaoussanis/timbre"
:license {:name "Eclipse Public License"}
:dependencies [[org.clojure/clojure "1.3.0"]
[clj-stacktrace "0.2.4"]
[com.draines/postal "1.8.0"]]
[clj-stacktrace "0.2.4"]]
:profiles {:1.3 {:dependencies [[org.clojure/clojure "1.3.0"]]}
:1.4 {:dependencies [[org.clojure/clojure "1.4.0"]]}
:1.5 {:dependencies [[org.clojure/clojure "1.5.0-master-SNAPSHOT"]]}}

View File

@ -2,8 +2,7 @@
"Simple, flexible, all-Clojure logging. No XML!"
{:author "Peter Taoussanis"}
(:require [clojure.string :as str]
[clj-stacktrace.repl :as stacktrace]
[postal.core :as postal])
[clj-stacktrace.repl :as stacktrace])
(:import [java.util Date Locale]
[java.text SimpleDateFormat]))
@ -19,20 +18,22 @@
"Like `println` but prints all objects to output stream as a single
atomic string. This is faster and avoids interleaving race conditions."
[& xs]
(print (str (str/join \space xs) \newline)))
(print (str (str/join \space xs) \newline))
(flush))
(def config
"This map atom controls everything about the way Timbre operates. In
particular note the flexibility to add arbitrary appenders.
(defonce config
^{:doc
"This map atom controls everything about the way Timbre operates. In
particular note the flexibility to add arbitrary appenders.
An appender is a map with keys:
:doc, :min-level, :enabled?, :async?, :max-message-per-msecs, :fn?
An appender is a map with keys:
:doc, :min-level, :enabled?, :async?, :max-message-per-msecs, :fn?
An appender's fn takes a single map argument with keys:
:ap-config, :level, :error?, :instant, :timestamp, :ns, :message, :more,
:profiling-stats (when applicable)
An appender's fn takes a single map argument with keys:
:ap-config, :level, :error?, :instant, :timestamp, :ns, :message, :more,
:profiling-stats (when applicable)
See source code for examples."
See source code for examples."}
(atom {:current-level :debug
;;; Allow log filtering by namespace patterns (e.g. ["my-app.*"]).
@ -54,29 +55,13 @@
:max-message-per-msecs nil
:fn (fn [{:keys [error? more] :as args}]
(binding [*out* (if error? *err* *out*)]
(apply str-println (prefixed-message args) more)))}
:postal
{:doc (str "Sends an email using com.draines/postal.\n"
"Needs :postal config map in :shared-appender-config.")
:min-level :error :enabled? false :async? true
:max-message-per-msecs (* 60 60 2)
:fn (fn [{:keys [ap-config more] :as args}]
(when-let [postal-config (:postal ap-config)]
(postal/send-message
(assoc postal-config
:subject (prefixed-message args)
:body (if (seq more) (str/join " " more)
"<no additional arguments>")))))}}
(apply str-println (prefixed-message args) more)))}}
;; Will be given to all appenders via :ap-config key
:shared-appender-config
{:timestamp-pattern "yyyy-MMM-dd HH:mm:ss ZZ" ; SimpleDateFormat pattern
:locale nil ; A Locale object, or nil
;; A Postal message map, or nil.
;; ^{:host "mail.isp.net" :user "jsmith" :pass "sekrat!!1"}
;; {:from "me@draines.com" :to "foo@example.com"}
:postal nil}}))
}}))
(defn set-config! [[k & ks] val] (swap! config assoc-in (cons k ks) val))
(defn set-level! [level] (set-config! [:current-level] level))

View File

@ -0,0 +1,22 @@
(ns taoensso.timbre.appenders.postal
"Email appender for com.draines/postal.
Ref: https://github.com/drewr/postal."
{:author "Peter Taoussanis"}
(:require [clojure.string :as str]
[postal.core :as postal]
[taoensso.timbre :as timbre]))
(def postal-appender
{:doc (str "Sends an email using com.draines/postal.\n"
"Needs :postal config map in :shared-appender-config, e.g.:
^{:host \"mail.isp.net\" :user \"jsmith\" :pass \"sekrat!!1\"}
{:from \"Bob's logger <me@draines.com>\" :to \"foo@example.com\"}")
:min-level :error :enabled? true :async? true
:max-message-per-msecs (* 60 60 2)
:fn (fn [{:keys [ap-config more] :as args}]
(when-let [postal-config (:postal ap-config)]
(postal/send-message
(assoc postal-config
:subject (timbre/prefixed-message args)
:body (if (seq more) (str/join " " more)
"<no additional arguments>")))))})

View File

@ -1,4 +1,4 @@
(ns test-taoensso.timbre
(ns test-timbre.main
(:use [clojure.test]
[taoensso.timbre :as timbre :only (info)]
[taoensso.timbre.profiling :as profiling :only (p profile)]))