io.pedestal.log — io.pedestal/pedestal.log 0.8.0-alpha-1

A logging wrapper around SLF4J (but adaptable to other logging systems). Primary macros are trace, debug, info, warn, and error.

*mdc-context* clj

This map is copied into the SLF4J MDC by the with-context macro.

You are free to take control of it for MDC-related purposes as it doesn't directly affect Pedestal's logging implementation.

This map also includes all options that were passed into with-context.

debug clj macro

(debug & keyvals)

default-formatter clj

(default-formatter)

Returns the default formatter (used to convert the event map to a string) used when the :io.pedestal.log/formatter key is not present in the log event. The default is pr-str, but can be overridden via JVM property io.pedestal.log.formatter or environment variable PEDESTAL_LOG_FORMATTER.

error clj macro

(error & keyvals)

info clj macro

(info & keyvals)

log-level-dispatch clj deprecated

Used internally by the logging macros to map from a level keyword to a protocol method on LoggerSource.

LoggerSource clj protocol

Adapts an underlying logger (such as defined by SLF4J) to io.pedestal.log.

For -trace, -debug, etc., the body will typically be a String, formatted from the event map; if you write code that directly invokes these methods, but use the io.pedestal.log implementation of LoggerSource for SLF4J, then Strings will pass through unchanged, but other Clojure types will be converted to strings via pr-str.

If you write your own LoggerSource, you understand the same requirements: io.pedestal.log's macros will only supply a String body, but other code may pass other types.

-debug clj

(-debug t body)

(-debug t body throwable)

Log a DEBUG message, and optionally handle a special Throwable/Exception related to the message. The body may be any of Clojure's literal data types, but a map or string is encouraged.

-error clj

(-error t body)

(-error t body throwable)

Log an ERROR message, and optionally handle a special Throwable/Exception related to the message. The body may be any of Clojure's literal data types, but a map or string is encouraged.

-info clj

(-info t body)

(-info t body throwable)

Log an INFO message, and optionally handle a special Throwable/Exception related to the message. The body may be any of Clojure's literal data types, but a map or string is encouraged.

-level-enabled? clj

(-level-enabled? t level-key)

Given the log level as a keyword, return a boolean if that log level is currently enabled.

-trace clj

(-trace t body)

(-trace t body throwable)

Log a TRACE message, and optionally handle a special Throwable/Exception related to the message. The body may be any of Clojure's literal data types, but a map or string is encouraged.

-warn clj

(-warn t body)

(-warn t body throwable)

Log a WARN message, and optionally handle a special Throwable/Exception related to the message. The body may be any of Clojure's literal data types, but a map or string is encouraged.

LoggingMDC clj protocol

-clear-mdc clj

(-clear-mdc t)

Remove all entries within the MDC and return the MDC instance.

-get-mdc clj

(-get-mdc t k)

(-get-mdc t k not-found)

Given a String key and optionally a not-found value (which should be a String), lookup the key in the MDC and return the value (A String); Returns nil if the key isn't present, or not-found if value was supplied.

-put-mdc clj

(-put-mdc t k v)

Given a String key and a String value, Add an entry to the MDC, and return the MDC instance.

If k is nil, the original MDC is returned.

-remove-mdc clj

(-remove-mdc t k)

Given a String key, remove the key-value entry in the MDC if the key is present And return the MDC instance.

-set-mdc clj

(-set-mdc t m)

Given a map (of String keys and String values), Copy all key-values from the map to the MDC and return the MDC instance.

make-logger clj

(make-logger logger-name)

Returns a logger which satisfies the LoggerSource protocol.

maybe-init-java-util-log clj

(maybe-init-java-util-log)

Invoke this once when starting your application to redirect all java.util.logging log messages to SLF4J. The current project's dependencies must include org.slf4j/jul-to-slf4j.

mdc-context-key clj

The key to use when formatting *mdc-context* for storage into the MDC (via [[-put-mdc]]). io.pedestal.log uses only this single key of the underlying LoggingMDC implementation.

override-logger clj

Override of the default logger source, from symbol property io.pedestal.log.overrideLogger or environment variable PEDESTAL_LOGGER.

spy clj macro

(spy expr)

Logs expr and its value at DEBUG level, returns value.

trace clj macro

(trace & keyvals)

warn clj macro

(warn & keyvals)

with-context clj macro

(with-context ctx-map & body)

Given a map of keys/values/options and a body, Set the map into the MDC via the mdc-context binding.

The MDC used defaults to the SLF4J MDC unless the :io.pedestal.log/mdc option is specified (see Options).

By default, the map is formatted into a string value and stored under the "io.pedestal" key.

Caveats: SLF4J MDC, only maintains thread-local bindings, users are encouraged to use app-specific MDC implementations when needed.

Since SLF4J MDC manages data on a per-thread basis, false information may be contained in the MDC if threads are recycled. Refer to the slf4j docs for more information.

Options:

Key	Value	Description
::formatter	Function	Converts map to loggable value (a String), default via default-formatter is pr-str
::mdc	LoggingMDC	Defaults to the SLFJ MDC.