API for logging
- ()
by Alex Taggart, with contributions and suggestions by Chris Dean, Phil
Hagelberg, Richard Newman, and Timothy Pratley
clojure-contrib is now deprecated
clojure-contrib is no longer being developed or maintained.
Rather than a single, monolithic, contributions library, Clojure now has
a set of separate libraries for each unit of functionality. The libraries
are in the Clojure GitHub organization at
https://github.com/clojure.
API documentation of the libraries can be found at
https://clojure.github.io.
If you're looking for a specific function or namespace from the old
clojure-contrib, see
"Where Did Clojure.Contrib Go".
Full namespace name:
clojure.contrib.logging
Overview
Logging macros which delegate to a specific logging implementation. At
runtime a specific implementation is selected from, in order, Apache
commons-logging, slf4j, log4j, and finally java.util.logging.
Logging levels are specified by clojure keywords corresponding to the
values used in log4j and commons-logging:
:trace, :debug, :info, :warn, :error, :fatal
Logging occurs with the log macro, or the level-specific convenience macros,
which write either directly or via an agent. See log* for more details
regarding direct vs agent logging.
The log macros will not evaluate their 'message' unless the specific logging
level is in effect. Alternately, you can use the spy macro when you have code
that needs to be evaluated, and also want to output the code and its result to
the log.
Unless otherwise specified, the current namespace (as identified by *ns*) will
be used as the log-ns (similar to how the java class name is usually used).
Note: your log configuration should display the name that was passed to the
logging implementation, and not perform stack-inspection, otherwise you'll see
some ugly and unhelpful text in your logs.
Use the enabled? macro to write conditional code against the logging level
(beyond simply whether or not to call log, which is handled automatically).
You can redirect all java writes of System.out and System.err to the log
system by calling log-capture!. To bind *out* and *err* to the log system
invoke with-logs. In both cases a log-ns (e.g., "com.example.captured")
must be specified in order to namespace the output.
For those new to using a java logging library, the following is a very basic
configuration for log4j. Place it in a file called "log4j.properties"
and place that file (and the log4j JAR) on the classpath.
log4j.rootLogger=WARN, A1
log4j.logger.user=DEBUG
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %-5p %c: %m%n
The above will print messages to the console for :debug or higher if one is
in the user namespace, and :warn or higher in all other namespaces.
Public Variables and Functions
*force*
var
This library, clojure-contrib, is deprecated. See here for more information.
Overrides the default rules for choosing between logging directly or via an
agent. Defaults to nil. See log* for details.
Source
*log-factory*
var
This library, clojure-contrib, is deprecated. See here for more information.
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
Source
*logging-agent*
var
This library, clojure-contrib, is deprecated. See here for more information.
The default agent used for performing logging when direct logging is
disabled. See log* for details.
Source
*tx-agent-levels*
var
This library, clojure-contrib, is deprecated. See here for more information.
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
Log
var
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
LogFactory
var
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
commons-logging
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (commons-logging)
Returns a commons-logging-based implementation of the LogFactory protocol, or
nil if not available. End-users should not need to call this.
Source
debug
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (debug message & more)
(debug throwable message & more)
Debug level logging using print-style args.
Source
debugf
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (debugf fmt & fmt-args)
(debugf throwable fmt & fmt-args)
Debug level logging using format.
Source
enabled?
macro
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
error
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (error message & more)
(error throwable message & more)
Error level logging using print-style args.
Source
errorf
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (errorf fmt & fmt-args)
(errorf throwable fmt & fmt-args)
Error level logging using format.
Source
fatal
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (fatal message & more)
(fatal throwable message & more)
Fatal level logging using print-style args.
Source
fatalf
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (fatalf fmt & fmt-args)
(fatalf throwable fmt & fmt-args)
Fatal level logging using format.
Source
find-factory
function
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
impl-enabled?
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (impl-enabled? log level)
Implementation-specific check if a particular level is enabled. End-users
should not need to call this.
impl-get-log
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (impl-get-log factory log-ns)
Returns an implementation-specific Log by namespace. End-users should not
need to call this.
impl-name
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (impl-name factory)
Returns some text identifying the underlying implementation.
impl-write!
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (impl-write! log level throwable message)
Implementation-specific write of a log message. End-users should not need
to call this.
info
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (info message & more)
(info throwable message & more)
Info level logging using print-style args.
Source
infof
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (infof fmt & fmt-args)
(infof throwable fmt & fmt-args)
Info level logging using format.
Source
java-util-logging
function
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
log
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (log level message)
(log level throwable message)
(log log-ns level throwable message)
(log log-factory log-ns level throwable message)
Evaluates and logs a message only if the specified level is enabled. See log*
for more details.
Source
log*
function
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
log-capture!
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (log-capture! log-ns)
(log-capture! log-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 log-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
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (log-stream level log-ns)
Creates a PrintStream that will output to the log at the specified level.
Source
log-uncapture!
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (log-uncapture!)
Restores System.out and System.err to their original values.
Source
log4j-logging
function
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (log4j-logging)
Returns a log4j-based implementation of the LogFactory protocol, or nil if
not available. End-users should not need to call this.
Source
logf
macro
This library, clojure-contrib, is deprecated. See here for more information.
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
This library, clojure-contrib, is deprecated. See here for more information.
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
slf4j-logging
function
This library, clojure-contrib, is deprecated. See here for more information.
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.
Source
spy
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (spy expr)
(spy level expr)
Evaluates expr and writes the form and its result to the log. Returns the
result of expr. Defaults to debug log level.
Source
trace
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (trace message & more)
(trace throwable message & more)
Trace level logging using print-style args.
Source
tracef
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (tracef fmt & fmt-args)
(tracef throwable fmt & fmt-args)
Trace level logging using format.
Source
warn
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (warn message & more)
(warn throwable message & more)
Warn level logging using print-style args.
Source
warnf
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (warnf fmt & fmt-args)
(warnf throwable fmt & fmt-args)
Warn level logging using format.
Source
with-logs
macro
This library, clojure-contrib, is deprecated. See here for more information.
Usage: (with-logs log-ns & body)
(with-logs [log-ns out-level err-level] & body)
Evaluates exprs in a context in which *out* and *err* write to the log. The
specified log-ns value will be used to namespace all log entries.
By default *out* and *err* write to :info and :error, respectively.
Source
