Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Merge branch 'dev': v0.7.0.

  • Loading branch information...
commit bfa33a7e8e39dfcf667fbc4dd241f4af9ec80785 2 parents df0d26e + c1c34be
Peter Taoussanis authored
39 README.md
Source Rendered
... ... @@ -1,9 +1,14 @@
1 1 Current [semantic](http://semver.org/) version:
2 2
3 3 ```clojure
4   -[com.taoensso/timbre "0.6.1"] ; Please note that the repo and ns have changed recently
  4 +[com.taoensso/timbre "0.7.0"]
5 5 ```
6 6
  7 +**Breaking changes** since _0.6.x_ (see updated README examples for any necessary changes):
  8 + * Affecting **users of the standard email appender**:
  9 + * Postal appender moved to own ns: `taoensso.timbre.appenders.postal`.
  10 + * `com.draines/postal` no longer automatically included as a dependency.
  11 +
7 12 # Timbre, a (sane) logging library for Clojure
8 13
9 14 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
37 42 Depend on Timbre in your `project.clj`:
38 43
39 44 ```clojure
40   -[com.taoensso/timbre "0.6.1"]
  45 +[com.taoensso/timbre "0.7.0"]
41 46 ```
42 47
43 48 and `use` the library:
@@ -99,12 +104,11 @@ Configuring Timbre couldn't be simpler. Let's check out (some of) the defaults:
99 104
100 105 :appenders
101 106 {:standard-out { <...> }
102   - :postal { <...> }}
  107 + <...> }
103 108
104 109 :shared-appender-config
105 110 {:timestamp-pattern "yyyy-MMM-dd HH:mm:ss ZZ"
106   - :locale nil
107   - :postal nil}}
  111 + :locale nil}}
108 112 ```
109 113
110 114 Easily adjust the current logging level:
@@ -127,14 +131,27 @@ Filter logging output by namespaces:
127 131 (timbre/set-config! [:ns-whitelist] ["some.library.core" "my-app.*"])
128 132 ```
129 133
130   -Enable the standard [Postal](https://github.com/drewr/postal)-based email appender:
  134 +### Email Appender
  135 +
  136 +To enable the standard [Postal](https://github.com/drewr/postal)-based email appender, add the Postal dependency to your `project.clj`:
  137 +
  138 +```clojure
  139 +[com.draines/postal "1.8.0"]
  140 +```
  141 +
  142 +And add the appender to your `ns` declaration:
131 143
132 144 ```clojure
  145 +(:require [taoensso.timbre.appenders (postal :as postal-appender)])
  146 +```
  147 +
  148 +Then adjust your Timbre config:
  149 +
  150 +```clojure
  151 +(timbre/set-config! [:appenders :postal] postal-appender/postal-appender)
133 152 (timbre/set-config! [:shared-appender-config :postal]
134 153 ^{:host "mail.isp.net" :user "jsmith" :pass "sekrat!!1"}
135 154 {:from "me@draines.com" :to "foo@example.com"})
136   -
137   -(timbre/set-config! [:appenders :postal :enabled?] true)
138 155 ```
139 156
140 157 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
180 197 Let's add it to our app's `ns` declaration:
181 198
182 199 ```clojure
183   -(ns my-app
184   - (:use [taoensso.timbre :as timbre :only (trace debug info warn error fatal spy)]
185   - [taoensso.timbre.profiling :as profiling :only (p profile)]))
  200 +(:use [taoensso.timbre.profiling :as profiling :only (p profile)])
186 201 ```
187 202
188 203 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
225 240
226 241 A simple **sampling profiler** is also available: `taoensso.timbre.profiling/sampling-profile`.
227 242
228   -## Timbre Supports the ClojureWerkz Project Goals
  243 +## Timbre supports the ClojureWerkz Project Goals
229 244
230 245 ClojureWerkz is a growing collection of open-source, batteries-included [Clojure libraries](http://clojurewerkz.org/) that emphasise modern targets, great documentation, and thorough testing.
231 246
5 project.clj
... ... @@ -1,10 +1,9 @@
1   -(defproject com.taoensso/timbre "0.6.1"
  1 +(defproject com.taoensso/timbre "0.7.0"
2 2 :description "Simple, flexible, all-Clojure logging. No XML!"
3 3 :url "https://github.com/ptaoussanis/timbre"
4 4 :license {:name "Eclipse Public License"}
5 5 :dependencies [[org.clojure/clojure "1.3.0"]
6   - [clj-stacktrace "0.2.4"]
7   - [com.draines/postal "1.8.0"]]
  6 + [clj-stacktrace "0.2.4"]]
8 7 :profiles {:1.3 {:dependencies [[org.clojure/clojure "1.3.0"]]}
9 8 :1.4 {:dependencies [[org.clojure/clojure "1.4.0"]]}
10 9 :1.5 {:dependencies [[org.clojure/clojure "1.5.0-master-SNAPSHOT"]]}}
45 src/taoensso/timbre.clj
@@ -2,8 +2,7 @@
2 2 "Simple, flexible, all-Clojure logging. No XML!"
3 3 {:author "Peter Taoussanis"}
4 4 (:require [clojure.string :as str]
5   - [clj-stacktrace.repl :as stacktrace]
6   - [postal.core :as postal])
  5 + [clj-stacktrace.repl :as stacktrace])
7 6 (:import [java.util Date Locale]
8 7 [java.text SimpleDateFormat]))
9 8
@@ -19,20 +18,22 @@
19 18 "Like `println` but prints all objects to output stream as a single
20 19 atomic string. This is faster and avoids interleaving race conditions."
21 20 [& xs]
22   - (print (str (str/join \space xs) \newline)))
  21 + (print (str (str/join \space xs) \newline))
  22 + (flush))
23 23
24   -(def config
25   - "This map atom controls everything about the way Timbre operates. In
26   - particular note the flexibility to add arbitrary appenders.
  24 +(defonce config
  25 + ^{:doc
  26 + "This map atom controls everything about the way Timbre operates. In
  27 + particular note the flexibility to add arbitrary appenders.
27 28
28   - An appender is a map with keys:
29   - :doc, :min-level, :enabled?, :async?, :max-message-per-msecs, :fn?
  29 + An appender is a map with keys:
  30 + :doc, :min-level, :enabled?, :async?, :max-message-per-msecs, :fn?
30 31
31   - An appender's fn takes a single map argument with keys:
32   - :ap-config, :level, :error?, :instant, :timestamp, :ns, :message, :more,
33   - :profiling-stats (when applicable)
  32 + An appender's fn takes a single map argument with keys:
  33 + :ap-config, :level, :error?, :instant, :timestamp, :ns, :message, :more,
  34 + :profiling-stats (when applicable)
34 35
35   - See source code for examples."
  36 + See source code for examples."}
36 37 (atom {:current-level :debug
37 38
38 39 ;;; Allow log filtering by namespace patterns (e.g. ["my-app.*"]).
@@ -54,29 +55,13 @@
54 55 :max-message-per-msecs nil
55 56 :fn (fn [{:keys [error? more] :as args}]
56 57 (binding [*out* (if error? *err* *out*)]
57   - (apply str-println (prefixed-message args) more)))}
58   -
59   - :postal
60   - {:doc (str "Sends an email using com.draines/postal.\n"
61   - "Needs :postal config map in :shared-appender-config.")
62   - :min-level :error :enabled? false :async? true
63   - :max-message-per-msecs (* 60 60 2)
64   - :fn (fn [{:keys [ap-config more] :as args}]
65   - (when-let [postal-config (:postal ap-config)]
66   - (postal/send-message
67   - (assoc postal-config
68   - :subject (prefixed-message args)
69   - :body (if (seq more) (str/join " " more)
70   - "<no additional arguments>")))))}}
  58 + (apply str-println (prefixed-message args) more)))}}
71 59
72 60 ;; Will be given to all appenders via :ap-config key
73 61 :shared-appender-config
74 62 {:timestamp-pattern "yyyy-MMM-dd HH:mm:ss ZZ" ; SimpleDateFormat pattern
75 63 :locale nil ; A Locale object, or nil
76   - ;; A Postal message map, or nil.
77   - ;; ^{:host "mail.isp.net" :user "jsmith" :pass "sekrat!!1"}
78   - ;; {:from "me@draines.com" :to "foo@example.com"}
79   - :postal nil}}))
  64 + }}))
80 65
81 66 (defn set-config! [[k & ks] val] (swap! config assoc-in (cons k ks) val))
82 67 (defn set-level! [level] (set-config! [:current-level] level))
22 src/taoensso/timbre/appenders/postal.clj
... ... @@ -0,0 +1,22 @@
  1 +(ns taoensso.timbre.appenders.postal
  2 + "Email appender for com.draines/postal.
  3 + Ref: https://github.com/drewr/postal."
  4 + {:author "Peter Taoussanis"}
  5 + (:require [clojure.string :as str]
  6 + [postal.core :as postal]
  7 + [taoensso.timbre :as timbre]))
  8 +
  9 +(def postal-appender
  10 + {:doc (str "Sends an email using com.draines/postal.\n"
  11 + "Needs :postal config map in :shared-appender-config, e.g.:
  12 + ^{:host \"mail.isp.net\" :user \"jsmith\" :pass \"sekrat!!1\"}
  13 + {:from \"Bob's logger <me@draines.com>\" :to \"foo@example.com\"}")
  14 + :min-level :error :enabled? true :async? true
  15 + :max-message-per-msecs (* 60 60 2)
  16 + :fn (fn [{:keys [ap-config more] :as args}]
  17 + (when-let [postal-config (:postal ap-config)]
  18 + (postal/send-message
  19 + (assoc postal-config
  20 + :subject (timbre/prefixed-message args)
  21 + :body (if (seq more) (str/join " " more)
  22 + "<no additional arguments>")))))})
2  test/test_taoensso/timbre.clj → test/test_timbre/main.clj
... ... @@ -1,4 +1,4 @@
1   -(ns test-taoensso.timbre
  1 +(ns test-timbre.main
2 2 (:use [clojure.test]
3 3 [taoensso.timbre :as timbre :only (info)]
4 4 [taoensso.timbre.profiling :as profiling :only (p profile)]))

0 comments on commit bfa33a7

Please sign in to comment.
Something went wrong with that request. Please try again.