v4.5.0

taoensso · Jun 26, 2016 · b1a2e8c · b1a2e8c
1 parent 49830fe
commit b1a2e8c
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 42 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,20 @@
 > This project uses [Break Versioning](https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md) as of **Aug 16, 2014**.
 
+## v4.5.0 / 2016 Jun 26
+
+```clojure
+[com.taoensso/timbre "4.5.0"]
+```
+
+> This is a **major, non-breaking release** focused on refactoring and performance (esp. profiling performance)
+
+* **BREAKING** (rarely): ids given to `timbre.profiling/pspy` and `timbre.profiling/profile` must now always be compile-time consts (e.g. keywords).
+* **DEPRECATED**: Appender args - `:?err_`, `:vargs_` (delays).
+* **New**: Appender args - `:?err`, `:vargs`, `:output_`.
+* **New**: Allow disabling ANSI colours with env var [#172 @ccfontes].
+* **Impl**: Minor logging perf improvements.
+* **Impl**: *Major* profiling perf improvements.
+
 ## v4.4.0 / 2016 Jun 10
 
 ```clojure

diff --git a/README.md b/README.md
@@ -5,47 +5,54 @@
 **[CHANGELOG]** | [API] | current [Break Version]:
 
 ```clojure
-[com.taoensso/timbre "4.4.0"] ; Stable
+[com.taoensso/timbre "4.5.0"] ; Stable
 ```
 
-Want to help [support taoensso/open-source]?
+> Please consider helping to [support my continued open-source Clojure/Script work]? 
+> 
+> Even small contributions can add up + make a big difference to help sustain my time writing, maintaining, and supporting Timbre and other Clojure/Script libraries. **Thank you!**
+>
+> \- Peter Taoussanis
 
 # Timbre
 
 ## A pure Clojure/Script logging library
 
-Java logging is a mess of complexity that buys you _nothing_. It can be comically hard to get even the simplest logging working, and it's no better at scale.
+Java logging is a Kafkaesque mess of complexity that buys you _nothing_. It can be comically hard to get even the simplest logging working, and it just gets worse at scale.
 
-Timbre offers an **all Clojure/Script** alternative that **works out the box**. It's fast, deeply flexible, and easy to configure. **No XML!**
+Timbre offers an **all Clojure/Script** alternative that's fast, deeply flexible, easy to configure, and that **works out the box**.  No XML.
+
+Supports optional interop with [tools.logging](https://github.com/ptaoussanis/timbre/blob/master/src/taoensso/timbre/tools/logging.clj) and [log4j/logback/slf4j](https://github.com/fzakaria/slf4j-timbre).
+
+Happy hacking!
 
 ## Features
- * Full **Clojure** + **ClojureScript** support (v4+)
- * No XML or properties files. **A single, simple config map**, and you're set
- * Deeply flexible **fn appender model** with **middleware**
- * **Great performance** at any scale
- * Filter logging by levels and **namespace whitelist/blacklist patterns**
- * **Zero overhead** with **complete Clj+Cljs elision** for compile-time level/ns filters
- * Useful built-in appenders for **out-the-box** Clj+Cljs logging
- * Powerful, easy-to-configure per-appender **rate limits** and **async logging**
- * [Logs as Clojure values][] (v3+)
- * [tools.logging] support (optional, useful when integrating with legacy logging systems)
- * Level and ns-filter aware **logging profiler**
- * Small, simple, cross-platform codebase
+ * Full **Clojure** + **ClojureScript** support (v4+).
+ * No XML or properties files. **A single, simple config map**, and you're set.
+ * Simple, flexible **fn appender model** with **middleware**.
+ * **Great performance** at any scale.
+ * Filter logging by levels, **namespace whitelist/blacklist patterns**, and more.
+ * **Zero overhead** with **complete Clj+Cljs elision** for compile-time level/ns filters.
+ * Includes a simple, high-performance **[logging profiler][]**.
+ * Useful built-in appenders for **out-the-box** Clj+Cljs logging.
+ * Powerful, easy-to-configure **rate limits** and **async logging**.
+ * [Logs as Clojure values][] (v3+).
+ * Small, simple, cross-platform codebase.
 
 ## 3rd-party tools, appenders, etc.
 
 Link                     | Description
 ------------------------ | -----------------------------------------------------
-[@palletops/log-config]  | Library to help manage Timbre logging config
 [@fzakaria/slf4j-timbre] | Route log4j/logback/sfl4j log output to Timbre
+[@palletops/log-config]  | Library to help manage Timbre logging config
 Your link here?          | **PR's welcome!**
 
 ## Getting started
 
 Add the necessary dependency to your project:
 
 ```clojure
-[com.taoensso/timbre "4.4.0"]
+[com.taoensso/timbre "4.5.0"]
 ```
 
 And setup your namespace imports:
@@ -68,7 +75,7 @@ And setup your namespace imports:
                      spy get-env log-env)]))
 ```
 
-> You can also call `(timbre/refer-timbre)` to configure Clj ns referrals **automatically**
+> You can also call `(timbre/refer-timbre)` to configure Clj ns referrals **automatically**.
 
 ### Logging
 
@@ -107,6 +114,8 @@ ANSI colors are enabled by default for stacktraces. To turn these off (e.g. for
 :output-fn (partial timbre/default-output-fn {:stacktrace-fonts {}})
 ```
 
+And/or you can set the `TIMBRE_DEFAULT_STACKTRACE_FONTS` environment variable (supports edn).
+
 ### Configuration
 
 This is the biggest win over Java logging IMO. **All** of Timbre's behaviour is controlled through a single, simple Clojure map.
@@ -189,34 +198,39 @@ This is the biggest win over Java logging IMO. **All** of Timbre's behaviour is
      :output-fn  :inherit
      :fn ; Appender's (fn [data]) -> side effects
      (fn [data]
-       (let [{:keys [output-fn]} data
-             formatted-output-str (output-fn data)]
+       (let [{:keys [output_]} data
+             formatted-output-str (force output_)]
          (println formatted-output-str)))}}})
 ```
 
 A few things to note:
+
  * Appenders are _trivial_ to write & configure - **they're just fns**. It's Timbre's job to dispatch useful args to appenders when appropriate, it's their job to do something interesting with them.
  * Being 'just fns', appenders have basically limitless potential: write to your database, send a message over the network, check some other state (e.g. environment config) before making a choice, etc.
 
 #### Log levels and ns filters
 
 The **log level** may be set:
- * At compile-time: (`TIMBRE_LEVEL` environment variable)
- * Statically using: `timbre/set-level!`/`timbre/merge-level!`
- * Dynamically using: `timbre/with-level`
+
+ * At compile-time: (`TIMBRE_LEVEL` environment variable).
+ * Statically using: `timbre/set-level!`/`timbre/merge-level!`.
+ * Dynamically using: `timbre/with-level`.
 
 The **ns filters** may be set:
- * At compile-time: (`TIMBRE_NS_WHITELIST`, `TIMBRE_NS_BLACKLIST` env vars)
- * Statically using: `timbre/set-config!`/`timbre/merge-config!`
- * Dynamically using: `timbre/with-config`
+
+ * At compile-time: (`TIMBRE_NS_WHITELIST`, `TIMBRE_NS_BLACKLIST` env vars).
+ * Statically using: `timbre/set-config!`/`timbre/merge-config!`.
+ * Dynamically using: `timbre/with-config`.
 
 There are also variants of the core logging macros that take an **explicit config arg**:
+
 ```clojure
 (timbre/log*  <config-map> <level> <& args>) ; or
 (timbre/logf* <config-map> <level> <& args>)
 ```
 
 Logging calls excluded by a compile-time option (e.g. during Cljs compilation) will be **entirely elided from your codebase**, e.g.:
+
 ```bash
 #!/bin/bash
 
@@ -241,6 +255,7 @@ lein uberjar        # Compile jar ''
 ```
 
 This gives us a high-performance Redis appender:
+
  * **All raw logging args are preserved** in serialized form (even errors).
  * Configurable number of entries to keep per log level.
  * Only the most recent instance of each **unique entry** is kept.
@@ -275,13 +290,17 @@ See also `car-appender/query-entries`.
 
 #### Other included appenders
 
-A number of 3rd-party appenders are included out-the-box [here](https://github.com/ptaoussanis/timbre/tree/master/src/taoensso/timbre/appenders/3rd_party). **Please see the relevant docstring for details**. Thank you to the respective authors! Just give me a shout if you've got an appender you'd like to have added.
+A number of 3rd-party appenders are included out-the-box [here](https://github.com/ptaoussanis/timbre/tree/master/src/taoensso/timbre/appenders/3rd_party). **Please see the relevant docstring for details**. Thanks goes to the respective authors! 
 
-## Profiling (currently Clj only)
+Just give me a shout if you've got an appender you'd like to have added.
+
+## Profiling
+
+> Currently Clj only
 
 The usual recommendation for Clojure profiling is: use a good **JVM profiler** like [YourKit], [JProfiler], or [VisualVM].
 
-And these certainly do the job. But as with many Java tools, they can be a little hairy and often heavy-handed - especially when applied to Clojure. Timbre includes an alternative.
+And these can certainly do the job. But as with many Java tools, they can be a little hairy and often heavy-handed. Timbre includes a simple, lightweight alternative.
 
 Wrap forms that you'd like to profile with the `p` macro and give them a name:
 
@@ -315,17 +334,15 @@ The `profile` macro can now be used to log times for any wrapped forms:
              Total                                                     100 405ms
 ```
 
-You can also use the `defnp` macro to conveniently wrap whole fns.
-
-Timbre profiling is fully **log level & ns filter aware**: if the level is insufficient or ns filtered, you **won't pay for profiling**.
+Timbre profiling is **log level & ns filter aware**: if the level is insufficient or ns filtered, you **won't pay for profiling**.
 
 And since `p` and `profile` **always return their body's result**, it becomes feasible to use profiling more often as part of your normal workflow: just *leave profiling code in production as you do logging code*.
 
-A simple sampling profiler is also included.
+See also `defnp`, `sampling-profile`.
 
 ## This project supports the ![ClojureWerkz-logo] goals
 
- * [ClojureWerkz] is a growing collection of open-source, **batteries-included Clojure libraries** that emphasise modern targets, great documentation, and thorough testing.
+[ClojureWerkz] is a growing collection of open-source, **batteries-included Clojure libraries** that emphasise modern targets, great documentation, and thorough testing.
 
 ## Contacting me / contributions
 
@@ -346,7 +363,7 @@ Copyright &copy; 2015-2016 [Peter Taoussanis].
 [@ptaoussanis]: https://www.taoensso.com
 [More by @ptaoussanis]: https://www.taoensso.com
 [Break Version]: https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md
-[support taoensso/open-source]: http://taoensso.com/clojure/backers
+[support my continued open-source Clojure/Script work]: http://taoensso.com/clojure/backers
 
 <!--- Standard links (repo specific) -->
 [CHANGELOG]: https://github.com/ptaoussanis/timbre/releases
@@ -357,10 +374,10 @@ Copyright &copy; 2015-2016 [Peter Taoussanis].
 [Hero]: https://raw.githubusercontent.com/ptaoussanis/timbre/master/hero.png "Title"
 
 <!--- Unique links -->
+[logging profiler]: #profiling
 [Logs as Clojure values]: #redis-carmine-appender-v3
 [@palletops/log-config]: https://github.com/palletops/log-config
 [@fzakaria/slf4j-timbre]: https://github.com/fzakaria/slf4j-timbre
-[tools.logging]: https://github.com/clojure/tools.logging
 [io.aviso.exception]: https://github.com/AvisoNovate/pretty
 [Carmine]: https://github.com/ptaoussanis/carmine
 [Postal]: https://github.com/drewr/postal

diff --git a/project.clj b/project.clj
@@ -1,4 +1,4 @@
-(defproject com.taoensso/timbre "4.4.0"
+(defproject com.taoensso/timbre "4.5.0"
   :author "Peter Taoussanis <https://www.taoensso.com>"
   :description "Pure Clojure/Script logging library"
   :url "https://github.com/ptaoussanis/timbre"
@@ -12,7 +12,7 @@
 
   :dependencies
   [[org.clojure/clojure "1.5.1"]
-   [com.taoensso/encore "2.53.1"]
+   [com.taoensso/encore "2.58.0"]
    [io.aviso/pretty     "0.1.26"]]
 
   :plugins
@@ -32,14 +32,14 @@
 
                          ;; Appender deps
                          [com.taoensso/nippy   "2.11.1"]
-                         [com.taoensso/carmine "2.12.2"]
-                         [com.draines/postal   "1.11.4"]
+                         [com.taoensso/carmine "2.13.1"]
+                         [com.draines/postal   "2.0.0"]
                          [irclj                "0.5.0-alpha4"]
                          [org.graylog2/gelfclient "1.4.0"]
                          [org.julienxx/clj-slack  "0.5.4"]
                          [org.clojure/java.jdbc   "0.6.1"]
                          [com.mchange/c3p0        "0.9.5.2"]
-                         [cheshire                "5.6.1"]]}
+                         [cheshire                "5.6.2"]]}
    :dev
    [:1.9 :test :server-jvm
     {:dependencies [[org.clojure/clojurescript "1.9.36"]]