taoensso.timbre

Simple, flexible logging for Clojure/Script. No XML.

*config*

dynamic

This config map controls all Timbre behaviour including:
  - When to log (via min-level and namespace filtering)
  - How  to log (which appenders to use, etc.)
  - What to log (how log data will be transformed to final
                 output for use by appenders)

Initial config value will be (in descending order of preference):

  1. `taoensso.timbre.config.edn`   JVM property  (read as EDN)
  2. `TAOENSSO_TIMBRE_CONFIG_EDN`   Env var       (read as EDN)
  3. `./taoensso.timbre.config.edn` resource file (read as EDN)
  4. Value of `default-config`

For all EDN cases (1-3): the EDN can represent either a Clojure map
to merge into `default-config`, or a qualified symbol that'll
resolve to a Clojure map to merge into `default-config`.

See `default-config` for more info on the base/default config.

You can modify the config value with standard `alter-var-root`,
or `binding`.

For convenience, there's also some dedicated helper utils:

  - `set-config!`, `merge-config!`        ; Mutate *config*
  - `set-min-level!`, `set-min-ns-level!` ; Mutate *config* :min-level
  - `with-config`, `with-merged-config`   ; Bind *config*
  - `with-min-level`                      ; Bind *config* :min-level


MAIN CONFIG OPTIONS

  :min-level
    Logging will occur only if a logging call's level is >= this
    min-level. Possible values, in order:

      :trace  = level 0
      :debug  = level 1 ; Default min-level
      :info   = level 2
      :warn   = level 3
      :error  = level 4 ; Error type
      :fatal  = level 5 ; Error type
      :report = level 6 ; High general-purpose (non-error) type

    It's also possible to set a namespace-specific min-level by
    providing a vector that maps `ns-pattern`s to min-levels, e.g.:
    `[[#{"taoensso.*"} :error] ... [#{"*"} :debug]]`.

    Example `ns-pattern`s:
      #{}, "*", "foo.bar", "foo.bar.*", #{"foo" "bar.*"},
      {:allow #{"foo" "bar.*"} :deny #{"foo.*.bar.*"}}.

    See also `set-min-ns-level!` for a helper tool.

  :ns-filter
    Logging will occur only if a logging call's namespace is permitted
    by this ns-filter. Possible values:

      - Arbitrary (fn may-log-ns? [ns]) predicate fn.
      - An `ns-pattern` (see :min-level docs above).

    Useful for turning off logging in noisy libraries, etc.

  :middleware
    Vector of simple (fn [data]) -> ?new-data fns (applied left->right)
    that transform the data map dispatched to appender fns. If any middleware
    returns nil, NO dispatch will occur (i.e. the event will be filtered).

    Useful for layering advanced functionality. Similar to Ring middleware.

  :timestamp-opts ; Config map, see `default-timestamp-opts`
  :output-fn      ; (fn [data]) -> final output for use by appenders,
                  ; see `default-output-fn` for example
  :output-opts    ; Optional map added to data sent to output-fn

  :appenders ; {<appender-id> <appender-map>}

    Where each appender-map has keys:
      :enabled?        ; Must be truthy to log
      :min-level       ; Optional *additional* appender-specific min-level
      :ns-filter       ; Optional *additional* appender-specific ns-filter

      :async?          ; Dispatch using agent? Useful for slow appenders (clj only)
                       ; Tip: consider calling (shutdown-agents) as part of your
                       ; application shutdown if you have this enabled for any
                       ; appenders.

      :rate-limit      ; [[<ncalls-limit> <window-msecs>] ...], or nil
                       ; Appender will noop a call after exceeding given number
                       ; of the "same" calls within given rolling window/s.
                       ;
                       ; Example:
                       ;   [[100  (encore/ms :mins  1)]
                       ;    [1000 (encore/ms :hours 1)]] will noop a call after:
                       ;
                       ;   - >100  "same" calls in 1 rolling minute, or
                       ;   - >1000 "same" calls in 1 rolling hour
                       ;
                       ; "Same" calls are identified by default as the
                       ; combined hash of:
                       ;   - Callsite (i.e. each individual Timbre macro form)
                       ;   - Logging level
                       ;   - All arguments provided for logging
                       ;
                       ; You can manually override call identification:
                       ;   (timbre/infof ^:meta {:id "my-limiter-call-id"} ...)
                       ;

      :timestamp-opts  ; Optional appender-specific override for top-level option
      :output-fn       ; Optional appender-specific override for top-level option
      :output-opts     ; Optional appender-specific override for top-level option

      :fn              ; (fn [data]) -> side-effects, with keys described below

LOG DATA
  A single map with keys:
    :config          ; Entire active config map
    :context         ; `*context*` value at log time (see `with-context`)
    :appender-id     ; Id of appender currently dispatching
    :appender        ; Entire map of appender currently dispatching
    :instant         ; Platform date (java.util.Date or js/Date)
    :level           ; Call's level keyword (e.g. :info) (>= active min-level)
    :error-level?    ; Is level e/o #{:error :fatal}?
    :spying?         ; Is call occuring via the `spy` macro?
    :?ns-str         ; String,  or nil
    :?file           ; String,  or nil
    :?line           ; Integer, or nil ; Waiting on CLJ-865
    :?err            ; First-arg platform error, or nil
    :?meta           ; First-arg map when it has ^:meta metadata, used as a
                       way of passing advanced per-call options to appenders
    :vargs           ; Vector of raw args provided to logging call
    :timestamp_      ; Forceable - string
    :hostname_       ; Forceable - string (clj only)
    :output-fn       ; (fn [data]) -> final output for use by appenders
    :output_         ; Forceable result of calling (output-fn <this-data-map>)

    **NB** - any keys not specifically documented here should be
    considered private / subject to change without notice.

COMPILE-TIME LEVEL/NS ELISION
  To control :min-level and :ns-filter at compile-time, use:

    - `taoensso.timbre.min-level.edn`  JVM property (read as EDN)
    - `taoensso.timbre.ns-pattern.edn` JVM property (read as EDN)

    - `TAOENSSO_TIMBRE_MIN_LEVEL_EDN`  env var      (read as EDN)
    - `TAOENSSO_TIMBRE_NS_PATTERN_EDN` env var      (read as EDN)

  Note that compile-time options will OVERRIDE options in `*config*`.

*context*

dynamic

General-purpose dynamic logging context

-elide?

(-elide? level-form ns-str-form)
Returns true iff level or ns are compile-time filtered.
Called only at macro-expansiom time.

-log!

(-log! config level ?ns-str ?file ?line msg-type ?err vargs_ ?base-data)(-log! config level ?ns-str ?file ?line msg-type ?err vargs_ ?base-data callsite-id)(-log! config level ?ns-str ?file ?line msg-type ?err vargs_ ?base-data callsite-id spying?)
Core low-level log fn. Implementation detail!

-log-and-rethrow-errors

macro

(-log-and-rethrow-errors ?line & body)

-log-errors

macro

(-log-errors ?line & body)

-logged-future

macro

(-logged-future ?line & body)

-spy

macro

(-spy ?line config level name expr)

ansi-color

(ansi-color color)

color-str

(color-str color)(color-str color x)(color-str color x y)(color-str color x y & more)

debug

macro

(debug & args)

debugf

macro

(debugf & args)

default-config

Default/example Timbre `*config*` value:

{:min-level :debug #_[["taoensso.*" :error] ["*" :debug]]
 :ns-filter #{"*"} #_{:deny #{"taoensso.*"} :allow #{"*"}}

 :middleware [] ; (fns [data]) -> ?data, applied left->right

 :timestamp-opts default-timestamp-opts ; {:pattern _ :locale _ :timezone _}
 :output-fn default-output-fn ; (fn [data]) -> final output for use by appenders

 :appenders
 #?(:clj
    {:println (println-appender {:stream :auto})
     ;; :spit (spit-appender    {:fname "./timbre-spit.log"})
     }

    :cljs
    (if (exists? js/window)
      {:console (console-appender {})}
      {:println (println-appender {})}))}

See `*config*` for more info.

default-err

default-out

default-output-error-fn

(default-output-error-fn {:keys [?err output-opts], :as data})
Default (fn [data]) -> string, used by `default-output-fn` to
generate output for `:?err` value in log data.

For Clj:
   Uses `io.aviso/pretty` to return an attractive stacktrace.
   Options:
     :stacktrace-fonts ; See `io.aviso.exception/*fonts*`

For Cljs:
   Returns simple stacktrace string.

default-output-fn

(default-output-fn base-output-opts data)(default-output-fn data)
Default (fn [data]) -> final output string, used to produce
final formatted output_ string from final log data.

Options (included as `:output-opts` in data sent to fns below):

  :error-fn ; When present and (:?err data) present,
            ; (error-fn data) will be called to generate output
            ; (e.g. a stacktrace) for the error.
            ;
            ; Default value: `default-output-error-fn`.
            ; Use `nil` value to exclude error output.

  :msg-fn   ; When present, (msg-fn data) will be called to
            ; generate a message from `vargs` (vector of raw
            ; logging arguments).
            ;
            ; Default value: `default-output-msg-fn`.
            ; Use `nil` value to exclude message output.

default-output-msg-fn

(default-output-msg-fn {:keys [msg-type ?msg-fmt vargs output-opts], :as data})
(fn [data]) -> string, used by `default-output-fn` to generate output
for `:vargs` value (vector of raw logging arguments) in log data.

default-timestamp-opts

Controls (:timestamp_ data)

error

macro

(error & args)

errorf

macro

(errorf & args)

example-config

DEPRECATED, prefer `default-config`

fatal

macro

(fatal & args)

fatalf

macro

(fatalf & args)

get-?hostname

(get-?hostname)
Returns live local hostname, or nil.

get-env

macro

(get-env)

get-hostname

Returns cached hostname string.

handle-uncaught-jvm-exceptions!

(handle-uncaught-jvm-exceptions! & [handler])
Sets JVM-global DefaultUncaughtExceptionHandler.

info

macro

(info & args)

infof

macro

(infof & args)

level>=

(level>= x y)
Implementation detail.

load-config

(load-config edn source)(load-config)
Imlementation detail, use only for debugging, etc.
Returns Timbre config loaded from JVM property, Env var, or
resource file.

See `*config*` docstring for more info.

log

macro

(log level & args)

log!

macro

(log! level msg-type args & [opts])
Core low-level log macro. Useful for tooling/library authors, etc.

  * `level`    - must eval to a valid logging level
  * `msg-type` - must eval to e/o #{:p :f nil}
  * `args`     - arguments for logging call
  * `opts`     - ks e/o #{:config :?err :?ns-str :?file :?line :?base-data :spying?}

Supports compile-time elision when compile-time const vals
provided for `level` and/or `?ns-str`.

Logging wrapper examples:

  (defn     log-wrapper-fn    [& args]  (timbre/log! :info :p  args))
  (defmacro log-wrapper-macro [& args] `(timbre/log! :info :p ~args))

log*

macro

(log* config level & args)

log-and-rethrow-errors

macro

(log-and-rethrow-errors & body)

log-env

macro

(log-env)(log-env level)(log-env level name)(log-env config level name)

log-errors

macro

(log-errors & body)

log?

logf

macro

(logf level & args)

logf*

macro

(logf* config level & args)

logged-future

macro

(logged-future & body)

logging-enabled?

(logging-enabled? level compile-time-ns)

logp

macro

(logp & args)

may-log?

(may-log? level)(may-log? level ?ns-str)(may-log? level ?ns-str ?config)(may-log? default-min-level level ?ns-str ?config)
Implementation detail.
Returns true iff level and ns are runtime unfiltered.

merge-config!

(merge-config! config)

ordered-levels

println-appender

(println-appender & [{:keys [stream], :or {stream :auto}}])
Returns a simple `println` appender for Clojure/Script.
Use with ClojureScript requires that `cljs.core/*print-fn*` be set.

:stream (clj only) - e/o #{:auto :*out* :*err* :std-err :std-out <io-stream>}.

refer-timbre

(refer-timbre)
Shorthand for:
(require '[taoensso.timbre :as timbre
           :refer [log  trace  debug  info  warn  error  fatal  report
                   logf tracef debugf infof warnf errorf fatalf reportf
                   spy]])

report

macro

(report & args)

reportf

macro

(reportf & args)

set-config!

(set-config! config)

set-level!

(set-level! level)
DEPRECATED, prefer `set-min-level!`

set-min-level

(set-min-level config min-level)

set-min-level!

(set-min-level! min-level)

set-ns-min-level

(set-ns-min-level config ?min-level)(set-ns-min-level config ns ?min-level)
Returns given Timbre `config` with its `:min-level` modified so that
the given namespace has the specified minimum logging level.

When no namespace is provided, `*ns*` will be used.
When `?min-level` is nil, any minimum level specifications for the
*exact* given namespace will be removed.

See `*config*` docstring for more about `:min-level`.
See also `set-min-level!` for a util to directly modify `*config*`.

set-ns-min-level!

(set-ns-min-level! ?min-level)(set-ns-min-level! ns ?min-level)
Like `set-ns-min-level` but directly modifies `*config*`.

Can conveniently set the minimum log level for the current ns:
  (set-ns-min-level! :info) => Sets min-level for current *ns*

See `set-ns-min-level` for details.

shutdown-appenders!

(shutdown-appenders!)(shutdown-appenders! config)
Alpha, subject to change.

Iterates through all appenders in config (enabled or not), and
calls (:shutdown-fn appender) whenever that fn exists.

This signals to these appenders that they should immediately
close/release any resources that they may have open/acquired,
and permanently noop on future logging requests.

Returns the set of appender-ids that had a shutdown-fn called.

This fn is called automatically on JVM shutdown, but can also
be called manually.

sometimes

macro

(sometimes probability & body)
Handy for sampled logging, etc.

spit-appender

(spit-appender & [{:keys [fname append? locking?], :or {fname "./timbre-spit.log", append? true, locking? true}}])
Returns a simple `spit` file appender for Clojure.

spy

macro

(spy expr)(spy level expr)(spy level name expr)(spy config level name expr)
Evaluates named expression and logs its result. Always returns the result.
Defaults to :debug logging level and unevaluated expression as name.

stacktrace

(stacktrace err)(stacktrace err opts)
DEPRECATED, use `default-output-error-fn` instead

str-println

(str-println & xs)

swap-config!

(swap-config! f & args)

trace

macro

(trace & args)

tracef

macro

(tracef & args)

warn

macro

(warn & args)

warnf

macro

(warnf & args)

with-config

macro

(with-config config & body)

with-context

macro

(with-context context & body)
Executes body so that given arbitrary data will be passed (as `:context`)
to appenders for any enclosed logging calls.

(with-context
  {:user-name "Stu"} ; Will be incl. in data dispatched to appenders
  (info "User request"))

See also `with-context+`.

with-context+

macro

(with-context+ context & body)
Like `with-context`, but merges given context into current context.

with-default-outs

macro

(with-default-outs & body)

with-level

macro

(with-level level & body)
DEPRECATED, prefer `with-min-level`

with-log-level

macro

(with-log-level level & body)

with-logging-config

macro

(with-logging-config config & body)

with-merged-config

macro

(with-merged-config config & body)

with-min-level

macro

(with-min-level min-level & body)