taoensso.timbre

Liking cljdoc? Tell your friends :D

Mostly clj/s.
Exceptions indicated.

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

config^clj/s

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
    :?column         ; Integer, or nil
    :?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*`.

DEBUGGING INITIAL CONFIG
  See `:_init-config` for information re: Timbre's config on initial load.

source

context^clj/s

General-purpose dynamic logging context

source

-elide?^clj

(-elide? level-form ns-str-form)

Returns true iff level or ns are compile-time filtered.
Called only at macro-expansiom time.

source

-log!^clj/s

(-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?)

(-log! config
       level
       ?ns-str
       ?file
       ?line
       ?column
       msg-type
       ?err
       vargs_
       ?base-data
       callsite-id
       spying?)

Core low-level log fn. Implementation detail!

source

-spy^clj/smacro

(-spy loc config level name form)

source

ansi-color^clj

(ansi-color color)

source

color-str^clj

(color-str color)

(color-str color x)

(color-str color x y)

(color-str color x y & more)

source

console-appender^cljs

source

debug^clj/smacro

(debug & args)

source

debugf^clj/smacro

(debugf & args)

source

default-config^clj/s

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.

source

default-err^clj

source

default-out^clj

source

default-output-error-fn^clj/s

(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.

source

default-output-fn^clj/s

(default-output-fn data)

(default-output-fn base-output-opts 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.

source

default-output-msg-fn^clj/s

(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.

source

default-timestamp-opts^clj/s

Controls (:timestamp_ data)

source

error^clj/smacro

(error & args)

source

errorf^clj/smacro

(errorf & args)

source

fatal^clj/smacro

(fatal & args)

source

fatalf^clj/smacro

(fatalf & args)

source

get-?hostname^clj

(get-?hostname)

Returns live local hostname, or nil.

source

get-env^clj/smacro

(get-env)

source

get-hostname^clj

Returns cached hostname string.

source

handle-uncaught-jvm-exceptions!^clj

(handle-uncaught-jvm-exceptions! & [handler])

Sets JVM-global DefaultUncaughtExceptionHandler.

source

info^clj/smacro

(info & args)

source

infof^clj/smacro

(infof & args)

source

keep-callsite^clj/smacro

(keep-callsite & body)

The long-standing CLJ-865 unfortunately means that it's currently
not possible for an inner macro to access the &form metadata of an
outer macro.

This means that inner macros lose call site information like the
line number of the outer macro.

This util offers a workaround for macro authors:

  (defmacro inner  [] (meta &form))
  (defmacro outer1 []                `(inner))
  (defmacro outer2 [] (keep-callsite `(inner)))

  (inner)  => {:line _, :column _}
  (outer1) => nil
  (outer2) => {:line _, :column _}

source

level>=^clj/s

(level>= x y)

Implementation detail.

source

log^clj/smacro

(log level & args)

source

log!^clj/smacro

(log! {:as opts
       :keys [loc level msg-type args vargs config ?err ?base-data spying?]
       :or {config (quote taoensso.timbre/*config*) ?err :auto}})

(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 seq (ideally vec) for logging call
  * `opts`     - ks e/o #{:config ?err ?base-data spying?
                          :?ns-str :?file :?line :?column}

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/keep-callsite `(timbre/log! :info :p ~args)))

source

log*^clj/smacro

(log* config level & args)

source

log-and-rethrow-errors^clj/smacro

(log-and-rethrow-errors & body)

source

log-errors^clj/smacro

(log-errors & body)

source

logf^clj/smacro

(logf level & args)

source

logf*^clj/smacro

(logf* config level & args)

source

logged-future^clj/smacro

(logged-future & body)

source

may-log?^clj/s

(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.

source

merge-config!^clj/s

(merge-config! config)

source

println-appender^clj/s≠

clj

(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>}.

cljs

source (clj)source (cljs)

refer-timbre^clj

(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]])

source

report^clj/smacro

(report & args)

source

reportf^clj/smacro

(reportf & args)

source

set-config!^clj/s

(set-config! config)

source

set-min-level^clj/s

(set-min-level config min-level)

source

set-min-level!^clj/s

(set-min-level! min-level)

source

set-ns-min-level^clj/s≠

clj

(set-ns-min-level config ?min-level)

(set-ns-min-level config ns ?min-level)

cljs

(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*`.

source

set-ns-min-level!^clj/smacro

(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.

source

shutdown-appenders!^clj/s

(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.

source

sometimes^clj/smacro

(sometimes probability & body)

Handy for sampled logging, etc.

source

spit-appender^clj

(spit-appender &
               [{:keys [fname append? locking?]
                 :or {fname "./timbre-spit.log" append? true locking? true}}])

Returns a simple `spit` file appender for Clojure.

source

spy^clj/smacro

(spy form)

(spy level form)

(spy level name form)

(spy config level name form)

Evaluates named form and logs its result. Always returns the result.
Defaults to `:debug` logging level, and unevaluated form as name:
  (spy (+ 3 2)) => (timbre/debug '(+ 3 2) "=>" 5)

source

swap-config!^clj/s

(swap-config! f & args)

source

trace^clj/smacro

(trace & args)

source

tracef^clj/smacro

(tracef & args)

source

warn^clj/smacro

(warn & args)

source

warnf^clj/smacro

(warnf & args)

source

with-config^clj/smacro

(with-config config & body)

source

with-context^clj/smacro

(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+`.

source

with-context+^clj/smacro

(with-context+ context & body)

Like `with-context`, but merges given context into current context.

source

with-default-outs^clj/smacro

(with-default-outs & body)

source

with-merged-config^clj/smacro

(with-merged-config config & body)

source

with-min-level^clj/smacro

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

source

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcuts Report a problem cljdoc on GitHub

× close

taoensso.timbre

*config*clj/s

*context*clj/s

-elide?clj

-log!clj/s

-spyclj/smacro

ansi-colorclj

color-strclj

console-appendercljs

debugclj/smacro

debugfclj/smacro

default-configclj/s

default-errclj

default-outclj

default-output-error-fnclj/s

default-output-fnclj/s

default-output-msg-fnclj/s

default-timestamp-optsclj/s

errorclj/smacro

errorfclj/smacro

fatalclj/smacro

fatalfclj/smacro

get-?hostnameclj

get-envclj/smacro

get-hostnameclj

handle-uncaught-jvm-exceptions!clj

infoclj/smacro

infofclj/smacro

keep-callsiteclj/smacro

level>=clj/s

logclj/smacro

log!clj/smacro

log*clj/smacro

log-and-rethrow-errorsclj/smacro

log-errorsclj/smacro

logfclj/smacro

logf*clj/smacro

logged-futureclj/smacro

may-log?clj/s

merge-config!clj/s

println-appenderclj/s≠

refer-timbreclj

reportclj/smacro

reportfclj/smacro

set-config!clj/s

set-min-levelclj/s

set-min-level!clj/s

set-ns-min-levelclj/s≠

set-ns-min-level!clj/smacro

shutdown-appenders!clj/s

sometimesclj/smacro

spit-appenderclj

spyclj/smacro

swap-config!clj/s

traceclj/smacro

tracefclj/smacro

warnclj/smacro

warnfclj/smacro

with-configclj/smacro

with-contextclj/smacro

with-context+clj/smacro

with-default-outsclj/smacro

with-merged-configclj/smacro

with-min-levelclj/smacro

config^clj/s

context^clj/s

-elide?^clj

-log!^clj/s

-spy^clj/smacro

ansi-color^clj

color-str^clj

console-appender^cljs

debug^clj/smacro

debugf^clj/smacro

default-config^clj/s

default-err^clj

default-out^clj

default-output-error-fn^clj/s

default-output-fn^clj/s

default-output-msg-fn^clj/s

default-timestamp-opts^clj/s

error^clj/smacro

errorf^clj/smacro

fatal^clj/smacro

fatalf^clj/smacro

get-?hostname^clj

get-env^clj/smacro

get-hostname^clj

handle-uncaught-jvm-exceptions!^clj

info^clj/smacro

infof^clj/smacro

keep-callsite^clj/smacro

level>=^clj/s

log^clj/smacro

log!^clj/smacro

log*^clj/smacro

log-and-rethrow-errors^clj/smacro

log-errors^clj/smacro

logf^clj/smacro

logf*^clj/smacro

logged-future^clj/smacro

may-log?^clj/s

merge-config!^clj/s

println-appender^clj/s≠

refer-timbre^clj

report^clj/smacro

reportf^clj/smacro

set-config!^clj/s

set-min-level^clj/s

set-min-level!^clj/s

set-ns-min-level^clj/s≠

set-ns-min-level!^clj/smacro

shutdown-appenders!^clj/s

sometimes^clj/smacro

spit-appender^clj

spy^clj/smacro

swap-config!^clj/s

trace^clj/smacro

tracef^clj/smacro

warn^clj/smacro

warnf^clj/smacro

with-config^clj/smacro

with-context^clj/smacro

with-context+^clj/smacro

with-default-outs^clj/smacro

with-merged-config^clj/smacro

with-min-level^clj/smacro