tools.logging 1.2.5-SNAPSHOT API
Clojure Home

API for clojure.tools.logging - tools.logging 1.2.5-SNAPSHOT (in development)

by Alex Taggart

Full namespace name: clojure.tools.logging

Overview

Project home page is https://.com/clojure/tools.logging/
Logging macros which delegate to a specific logging implementation.

A logging implementation is selected at runtime when this namespace is first
loaded. For more details, see the documentation for *logger-factory*.

If you want to test that your code emits specific log messages, see the
clojure.tools.logging.test namespace.

Public Variables and Functions


*force*

dynamic var
Overrides the default rules for choosing between logging directly or via an
agent. Defaults to nil. See log* for details.
Source

*logger-factory*
dynamic var
An instance satisfying the clojure.tools.logging.impl/LoggerFactory protocol,
which allows uniform access to an underlying logging implementation.

The default value will be obtained by invoking a no-arg function named by the
"clojure.tools.logging.factory" system property, or if unset, by invoking
clojure.tools.logging.impl/find-factory.

After loading, this var can be programmatically changed to a different
LoggerFactory implementation via binding or alter-var-root.

See the various factory functions in clojure.tools.logger.impl.
Source

*logging-agent*
dynamic var
The default agent used for performing logging when direct logging is
disabled. See log* for details.
Source

*tx-agent-levels*
dynamic var
The set of levels that will require using an agent when logging from within a
running transaction. Defaults to #{:info :warn}. See log* for details.
Source

debug
macro
Usage: (debug message & more)
       (debug throwable message & more)

Debug level logging using print-style args.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

debugf
macro
Usage: (debugf fmt & fmt-args)
       (debugf throwable fmt & fmt-args)

Debug level logging using format.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

enabled?
macro
Usage: (enabled? level)
       (enabled? level logger-ns)

Returns true if the specific logging level is enabled.  Use of this macro
should only be necessary if one needs to execute alternate code paths beyond
whether the log should be written to.
Source

error
macro
Usage: (error message & more)
       (error throwable message & more)

Error level logging using print-style args.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

errorf
macro
Usage: (errorf fmt & fmt-args)
       (errorf throwable fmt & fmt-args)

Error level logging using format.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

fatal
macro
Usage: (fatal message & more)
       (fatal throwable message & more)

Fatal level logging using print-style args.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

fatalf
macro
Usage: (fatalf fmt & fmt-args)
       (fatalf throwable fmt & fmt-args)

Fatal level logging using format.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

info
macro
Usage: (info message & more)
       (info throwable message & more)

Info level logging using print-style args.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

infof
macro
Usage: (infof fmt & fmt-args)
       (infof throwable fmt & fmt-args)

Info level logging using format.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

log
macro
Usage: (log level message)
       (log level throwable message)
       (log logger-ns level throwable message)
       (log logger-factory logger-ns level throwable message)

Evaluates and logs a message only if the specified level is enabled. See log*
for more details.
Source

log*
function
Usage: (log* logger level throwable message)

Attempts to log a message, either directly or via an agent; does not check if
the level is enabled.

For performance reasons, an agent will only be used when invoked within a
running transaction, and only for logging levels specified by
*tx-agent-levels*. This allows those entries to only be written once the
transaction commits, and are discarded if it is retried or aborted.  As
corollary, other levels (e.g., :debug, :error) will be written even from
failed transactions though at the cost of repeat messages during retries.

One can override the above by setting *force* to :direct or :agent; all
subsequent writes will be direct or via an agent, respectively.
Source

log-capture!
function
Usage: (log-capture! logger-ns)
       (log-capture! logger-ns out-level err-level)

Captures System.out and System.err, piping all writes of those streams to
the log. If unspecified, levels default to :info and :error, respectively.
The specified logger-ns value will be used to namespace all log entries.

Note: use with-logs to redirect output of *out* or *err*.

Warning: if the logging implementation is configured to output to System.out
(as is the default with java.util.logging) then using this function will
result in StackOverflowException when writing to the log.
Source

log-stream
function
Usage: (log-stream level logger-ns)

Creates a PrintStream that will output to the log at the specified level.
Source

log-uncapture!
function
Usage: (log-uncapture!)

Restores System.out and System.err to their original values.
Source

logf
macro
Usage: (logf level fmt & fmt-args)
       (logf level throwable fmt & fmt-args)

Logs a message using a format string and args. Can optionally take a
throwable as its second arg. See level-specific macros, e.g., debugf.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

logp
macro
Usage: (logp level message & more)
       (logp level throwable message & more)

Logs a message using print style args. Can optionally take a throwable as its
second arg. See level-specific macros, e.g., debug.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

spy
macro
Usage: (spy expr)
       (spy level expr)

Evaluates expr and may write the form and its result to the log. Returns the
result of expr. Defaults to :debug log level.
Source

spyf
macro
Usage: (spyf fmt expr)
       (spyf level fmt expr)

Evaluates expr and may write (format fmt result) to the log. Returns the
result of expr. Defaults to :debug log level.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

trace
macro
Usage: (trace message & more)
       (trace throwable message & more)

Trace level logging using print-style args.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

tracef
macro
Usage: (tracef fmt & fmt-args)
       (tracef throwable fmt & fmt-args)

Trace level logging using format.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

warn
macro
Usage: (warn message & more)
       (warn throwable message & more)

Warn level logging using print-style args.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

warnf
macro
Usage: (warnf fmt & fmt-args)
       (warnf throwable fmt & fmt-args)

Warn level logging using format.
Use the 'logging.readable' namespace to avoid wrapping args in pr-str.
Source

with-logs
macro
Usage: (with-logs logger-ns & body)
       (with-logs [logger-ns out-level err-level] & body)

Evaluates exprs in a context in which *out* and *err* write to the log. The
specified logger-ns value will be used to namespace all log entries.

By default *out* and *err* write to :info and :error, respectively.
Source

clojure.tools.logging.impl
Protocols used to allow access to logging implementations.
This namespace only need be used by those providing logging
implementations to be consumed by the core api.

Protocols

Logger
Protocol
The protocol through which the core api will interact with an underlying logging
implementation.  Implementations should at least support the six standard
logging levels if they wish to work from the level-specific macros.
Known implementations: org.slf4j.Logger

enabled?
function
Usage: (enabled? logger level)

Check if a particular level is enabled for the given Logger.

write!
function
Usage: (write! logger level throwable message)

Writes a log message to the given Logger.
Source

LoggerFactory
Protocol
The protocol through which the core api will obtain an instance satisfying Logger
as well as providing information about the particular implementation being used.
Implementations should be bound to *logger-factory* in order to be picked up by
this library.
Known implementations: 

get-logger
function
Usage: (get-logger factory logger-ns)

Returns an implementation-specific Logger by namespace.

name
function
Usage: (name factory)

Returns some text identifying the underlying implementation.
Source
Public Variables and Functions

cl-factory
function
Usage: (cl-factory)

Returns a Commons Logging-based implementation of the LoggerFactory protocol, or
nil if not available.
Source

class-found?
function
Usage: (class-found? name)

Returns true if the Class associated with the given classname can be found
using the context ClassLoader for the current thread.
Source

disabled-logger
var
A Logger that is not enabled and does nothing on write.
Source

disabled-logger-factory
var
A LoggerFactory that always provides the disabled-logger.
Source

find-factory
function
Usage: (find-factory)

Returns the first non-nil value from slf4j-factory, cl-factory,
log4j2-factory, log4j-factory, and jul-factory.
Source

jul-factory
function
Usage: (jul-factory)

Returns a java.util.logging-based implementation of the LoggerFactory protocol,
or nil if not available.
Source

log4j-factory
function
Usage: (log4j-factory)

Returns a Log4j-based implementation of the LoggerFactory protocol, or nil if
not available.
Source

log4j2-factory
function
Usage: (log4j2-factory)

Returns a Log4j2-based implementation of the LoggerFactory protocol, or nil if
not available.
Source

slf4j-factory
function
Usage: (slf4j-factory)

Returns a SLF4J-based implementation of the LoggerFactory protocol, or nil if
not available.
Source

clojure.tools.logging.readable
Logging macros that support printing message (some) arguments as
if wrapped in pr-str, the goal being to preserve their data representation
distinct from the explanatory text. See logp and logf for details regarding
which args are treated in this manner.

Examples:

(require '[clojure.tools.logging :as log]
         '[clojure.tools.logging.readable :as logr])

(def x "bar")
                                  ; Logged as...
(log/debug "foo" x "baz")         ; foo bar baz
(logr/debug "foo" x "baz")        ; foo "bar" baz
(log/debugf "foo %s %s" x "baz")  ; foo bar baz
(logr/debugf "foo %s %s" x "baz") ; foo "bar" "baz"


Public Variables and Functions

debug
macro
Usage: (debug message & more)
       (debug throwable message & more)

Debug level logging using print-style args. See logp for details.
Source

debugf
macro
Usage: (debugf fmt & fmt-args)
       (debugf throwable fmt & fmt-args)

Debug level logging using format. See logf for details.
Source

error
macro
Usage: (error message & more)
       (error throwable message & more)

Error level logging using print-style args. See logp for details.
Source

errorf
macro
Usage: (errorf fmt & fmt-args)
       (errorf throwable fmt & fmt-args)

Error level logging using format. See logf for details.
Source

fatal
macro
Usage: (fatal message & more)
       (fatal throwable message & more)

Fatal level logging using print-style args. See logp for details.
Source

fatalf
macro
Usage: (fatalf fmt & fmt-args)
       (fatalf throwable fmt & fmt-args)

Fatal level logging using format. See logf for details.
Source

info
macro
Usage: (info message & more)
       (info throwable message & more)

Info level logging using print-style args. See logp for details.
Source

infof
macro
Usage: (infof fmt & fmt-args)
       (infof throwable fmt & fmt-args)

Info level logging using format. See logf for details.
Source

logf
macro
Usage: (logf level fmt & fmt-args)
       (logf level throwable fmt & fmt-args)

Logs a message using a format string and args, where all format args will be
printed readably, as if wrapped in pr-str. Can optionally take a throwable as
its second arg. See level-specific macros, e.g., debugf.
Source

logp
macro
Usage: (logp level message & more)
       (logp level throwable message & more)

Logs a message using print style args, where message args that are not
literal strings will be printed readably, as if wrapped in pr-str. Can
optionally take a throwable as its second arg. See level-specific macros,
e.g., debug.
Source

spyf
macro
Usage: (spyf fmt expr)
       (spyf level fmt expr)

Evaluates expr and may write (logf level fmt result) to the log. Returns the
result of expr. Defaults to :debug log level.
Source

trace
macro
Usage: (trace message & more)
       (trace throwable message & more)

Trace level logging using print-style args. See logp for details.
Source

tracef
macro
Usage: (tracef fmt & fmt-args)
       (tracef throwable fmt & fmt-args)

Trace level logging using format. See logf for details.
Source

warn
macro
Usage: (warn message & more)
       (warn throwable message & more)

Warn level logging using print-style args. See logp for details.
Source

warnf
macro
Usage: (warnf fmt & fmt-args)
       (warnf throwable fmt & fmt-args)

Warn level logging using format. See logf for details.
Source

clojure.tools.logging.test
Support for testing whether logging calls are made.

Usage example:
  (require '[clojure.tools.logging :as log]
           '[clojure.tools.logging.test :refer [logged? with-log])

  (with-log
    (log/info "Hello World!")
    (log/error (Exception. "Did a thing") "Error: oops")
    (logged? 'user :info #"Hello")                           ; true
    (logged? 'user :error [Throwable #"thing"] #"Error:")    ; true
    (logged? 'user :debug "Hi"))                             ; false

Protocols

StatefulLog
Protocol
Known implementations: 

append!
function
Usage: (append! this logger-ns level throwable message)

Returns this log with a new log entry appended.

entries
function
Usage: (entries this)

Returns a vector of the entries in this log, oldest first.
Source
Types

LogEntry
record
Fields: [logger-ns level throwable message]
Protocols: MatchableLogEntry
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map
Public Variables and Functions

*stateful-log*
dynamic var
The instance of StatefulLog used by with-log. By default unbound.
Source

->LogEntry
function
Usage: (->LogEntry logger-ns level throwable message)

Positional factory function for class clojure.tools.logging.test.LogEntry.
Source

atomic-log
function
Usage: (atomic-log log-entry-fn)

Returns a StatefulLog, appending to an atom the result of invoking
log-entry-fn with the same args as append!
Source

logged?
function
Usage: (logged? logger-ns level message)
       (logged? logger-ns level throwable message)

Returns true if the log contains matching entries. See match-logger-ns?,
match-level?, match-throwable?, and match-message? for the default matching
behavior applied to the given args.

Must be invoked within a context where *stateful-log* is bound to an instance
of StatefulLog containing MatchableLogEntry items (e.g., inside with-log).
Source

logger-factory
function
Usage: (logger-factory stateful-log enabled-pred)

Returns a LoggerFactory that will append log entries to stateful-log. Levels
are enabled when (enabled-pred logger-ns level) is true.
Source

map->LogEntry
function
Usage: (map->LogEntry m#)

Factory function for class clojure.tools.logging.test.LogEntry, taking a map of keywords to field values.
Source

match-level?
multimethod
No usage documentation available
Returns true if expected matches the actual level. Used by
LogEntry/matches? implementation.

Dises on the types of expected and actual.

Provided methods' dis values and matching:
  :default      if equal
  [Fn Object]   if (f actual) is logically true
  [Set Object]  if set contains actual
Source

match-logger-ns?
multimethod
No usage documentation available
Returns true if expected matches the actual namespace. Used by
LogEntry/matches? implementation.

Dises on the types of expected and actual.

Provided methods' dis values and matching:
  :default            if equal
  [Fn Object]         if (f actual) is logically true
  [String Namespace]  if string equals namespace's string
  [Symbol Namespace]  if symbol equals namespace's symbol
Source

match-message?
multimethod
No usage documentation available
Returns true if expected matches the actual message. Used by
LogEntry/matches? implementation.

Dises on the types of expected and actual.

Provided methods' dis values and matching:
  :default          if equal
  [Fn Object]       if (f actual) is logically true
  [Pattern String]  if pattern matches actual
Source

match-throwable?
multimethod
No usage documentation available
Returns true if expected matches the actual throwable. Used by
LogEntry/matches? implementation.

Dises on the types of expected and actual. If expected is a vector, will
instead use a vector of the contained types.

Provided methods' dis values and matching:
  :default                     if equal
  [Fn Object]                  if (f actual) is logically true
  [Class Object]               if actual is an instance of Class
  [[Class String] Throwable]   ... and if string equals exception message
  [[Class Pattern] Throwable]  ... and if pattern matches exception message
Source

matches
function
Usage: (matches logger-ns level message)
       (matches logger-ns level throwable message)

Returns matching log entries, otherwise nil. See match-logger-ns?,
match-level?, match-throwable?, and match-message? for the default matching
behavior applied to the given args.

Must be invoked within a context where *stateful-log* is bound to an instance
of StatefulLog containing MatchableLogEntry items (e.g., inside with-log).
Source

the-log
function
Usage: (the-log)

Returns the vector of current log entries.

Must be invoked within a context where *stateful-log* is bound to an instance
of StatefulLog containing MatchableLogEntry items (e.g., inside with-log).
Source
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.