API for clojure.tools.logging - Logging Tools 0.3.1 (in development)

by Alex Taggart

Full namespace name: clojure.tools.logging

Overview

Logging macros which delegate to a specific logging implementation. At
runtime a specific implementation is selected from, in order, slf4j,
Apache commons-logging, log4j, and finally java.util.logging.

The logging implementation can be expliticly determined by using
binding or alter-var-root to change the value of *logger-factory* to
another implementation of clojure.tools.logging.impl/LoggerFactory
(see also the *-factory functions in the impl 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 impl/LoggerFactory protocol. Used internally to
obtain an impl/Logger. Defaults to the value returned from impl/find-factory.
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.
Source


debugf

macro
Usage: (debugf fmt & fmt-args)
       (debugf throwable fmt & fmt-args)
Debug level logging using format.
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.
Source


errorf

macro
Usage: (errorf fmt & fmt-args)
       (errorf throwable fmt & fmt-args)
Error level logging using format.
Source


fatal

macro
Usage: (fatal message & more)
       (fatal throwable message & more)
Fatal level logging using print-style args.
Source


fatalf

macro
Usage: (fatalf fmt & fmt-args)
       (fatalf throwable fmt & fmt-args)
Fatal level logging using format.
Source


info

macro
Usage: (info message & more)
       (info throwable message & more)
Info level logging using print-style args.
Source


infof

macro
Usage: (infof fmt & fmt-args)
       (infof throwable fmt & fmt-args)
Info level logging using format.
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.
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.
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.
Source


trace

macro
Usage: (trace message & more)
       (trace throwable message & more)
Trace level logging using print-style args.
Source


tracef

macro
Usage: (tracef fmt & fmt-args)
       (tracef throwable fmt & fmt-args)
Trace level logging using format.
Source


warn

macro
Usage: (warn message & more)
       (warn throwable message & more)
Warn level logging using print-style args.
Source


warnf

macro
Usage: (warnf fmt & fmt-args)
       (warnf throwable fmt & fmt-args)
Warn level logging using format.
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


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,
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


slf4j-factory

function
Usage: (slf4j-factory)
Returns a SLF4J-based implementation of the LoggerFactory protocol, or nil if
not available.
Source
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.