Table of Contents

*allow-direct-logging*

A boolean indicating whether direct logging (as opposed to via an agent) is
allowed when not operating from within a transaction. Defaults to true.

*force*

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

*impl-name*

The name of the logging implementation used.

*log-factory*

An instance satisfying the LogFactory protocol. Used internally when needing
to obtain an instance satisfying the Log protocol. Defaults to the value
returned from find-factory. Can be rebound to provide alternate logging
implementations

*logging-agent*

The default agent used for performing logging durng a transaction or when
direct logging is disabled.

*tx-agent-levels*

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.

Log

The protocol through which macros will interact with an underlying logging
implementation.  Implementations should at least support the six specified
logging levels if they wish to benefit from the level-specific macros.

LogFactory

The protocol through which macros will obtain an instance satisfying Log as
well as providing information about the particular implementation being used.
Implementations should be bound to *log-factory* in order to be picked up by
this library.

debug

Usage: (debug message)
       (debug message throwable)

Logs a message at the debug level.

debugf

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

Debug level logging using format.

enabled?

Usage: (enabled? level)
       (enabled? level log-ns)

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

error

Usage: (error message)
       (error message throwable)

Logs a message at the error level.

errorf

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

Error level logging using format.

fatal

Usage: (fatal message)
       (fatal message throwable)

Logs a message at the fatal level.

fatalf

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

Fatal level logging using format.

find-factory

Usage: (find-factory)

Returns the first LogFactory found that is available from commons-logging,
slf4j-logging, log4j-logging, or java-util-logging. End-users should not need
to call this.

impl-enabled?

Implementation-specific check if a particular level is enabled. End-users
should not need to call this.

impl-get-log

Returns an implementation-specific log by string namespace. End-users should
not need to call this.

impl-name

Usage: (impl-name factory)

Returns some text identifying the underlying implementation.

impl-write!

Implementation-specific write of a log message. End-users should not need to
call this.

info

Usage: (info message)
       (info message throwable)

Logs a message at the info level.

infof

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

Info level logging using format.

java-util-logging

Usage: (java-util-logging)

Returns a java.util.logging-based implementation of the LogFactory protocol,
or nil if not available. End-users should not need to call this.

log

Usage: (log level message)
       (log level message throwable)
       (log level message throwable log-ns)

Logs a message, either directly or via an agent. Also see the level-specific
convenience macros.

log*

Usage: (log* log 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.

log-capture!

Usage: (log-capture! log-ns)

Captures System.out and System.err, redirecting all writes of those streams
to :info and :error logging, respectively. The specified log-ns value will
be used to namespace all redirected logging. NOTE: this will not redirect
output of *out* or *err*; for that, use with-logs.

log-stream

Usage: (log-stream level log-ns)

Creates a PrintStream that will output to the log. End-users should not need
to invoke this.

log-uncapture!

Usage: (log-uncapture!)

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

logf

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.

logp

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.

slf4j-logging

Usage: (slf4j-logging)

Returns a SLF4J-based implementation of the LogFactory protocol, or nil if
not available. End-users should not need to call this.

spy

Usage: (spy expr)

Evaluates expr and outputs the form and its result to the debug log; returns 
the result of expr.

trace

Usage: (trace message)
       (trace message throwable)

Logs a message at the trace level.

tracef

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

Trace level logging using format.

warn

Usage: (warn message)
       (warn message throwable)

Logs a message at the warn level.

warnf

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

Warn level logging using format.

with-logs

Usage: (with-logs log-ns & body)

Evaluates exprs in a context in which *out* and *err* are bound to :info and
:error logging, respectively. The specified log-ns value will be used to
namespace all redirected logging.