io.pedestal.log — io.pedestal/pedestal.log 0.7.0-rc-1

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

Over time, this namespace has also accumulated other visibility-related functionality, including metrics (via the Codahale library) and telemetry (via OpenTelemetry) - these protocols and functions have been deprecated in 0.7.0 and will be removed in the future in favor of new implementations in the io.pedestal/pedestal-telemetry library (see [[io.pedestal.metrics]] and [[io.pedestal.telemetry]]).

*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.

active-span clj deprecated

(active-span)

Return the current active span; Returns nil if there isn't an active span.

add-span-baggage! clj deprecated

(add-span-baggage! span m)

(add-span-baggage! span k v)

(add-span-baggage! span bag-k bag-v & kvs)

counter clj deprecated

(counter metric-name delta)

(counter recorder metric-name delta)

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.

default-recorder clj deprecated

This is the default recorder of all metrics. This value is configured by setting the JVM Property io.pedestal.log.defaultMetricsRecorder or the environment variable PEDESTAL_METRICS_RECORDER. The value of the setting should be a namespaced symbol that resolves to a 0-arity function or nil. That function should return something that satisfies the MetricRecorder protocol. If no function is found, metrics will be reported only to JMX via a DropWizard MetricRegistry.

default-tracer clj deprecated

This is the default Tracer, registered as the OpenTracing's GlobalTracer. This value is configured by setting the JVM Property io.pedestal.log.defaultTracer or the environment variable PEDESTAL_TRACER. The value of the setting should be a namespaced symbol that resolves to a 0-arity function or nil. That function should return something that satisfies the TracerOrigin protocol. If no function is found, the GlobalTracer will default to the NoopTracer and GlobalTracer/isRegistered will be false.

error clj macro

(error & keyvals)

finish-span clj deprecated

(finish-span span)

Given a span, finish the span and return it.

format-name clj deprecated

(format-name n)

Format a given metric name, regardless of type, into a string

gauge clj deprecated

(gauge metric-name value-fn)

(gauge recorder metric-name value-fn)

histogram clj deprecated

(histogram metric-name value)

(histogram recorder metric-name value)

info clj macro

(info & keyvals)

jmx-reporter clj deprecated

(jmx-reporter registry)

log clj deprecated

(log keyvals)

(log keyvals default-level)

This function provides basic/core logging functionality as a function. You may prefer to use this if you need custom logging functionality beyond what is offered by the standard Pedestal logging macros (which in turn just call the protocols).

Deprecated with no replacement; the LoggerSource protocol and various configurable options for the main logging macros should be sufficient.

Given a map of logging information, and optionally a default log-level keyword (if not found in the map) -- default is :info, Determine the appropriate logger to use, determine if logging-level is enabled, format the logging message, and return the result of calling the appropriate logging function, dispatched to the logging protocols.

Special keys within the log message:

Key	Value	Description
:level	keyword	Log level to use for this message, defaults to default-level
:exception	Throwable
::logger	LoggerSource	The logger to use for this message, defaults to the override-logger or the SLF4J logger
::logger-name	String	Logger name to use, defaults to *ns*, which may be clojure.core depending on execution, so explicit is desired
::formatter	Function	A single argument function that converts a map to a loggable String; defaults to pr-str, via default-formatter

If using this function within a macro, you're encouraged to merge all 'meta' information (like line info) into the log message map.

For example:

(defmacro log-macro [log-map]
  (let [named-log-map (if (::logger-name log-map)
                        log-map
                        (assoc log-map ::logger-name (name (ns-name *ns*))))
        final-log-map (assoc named-log-map :line (:line (meta &form)))]
    `(log ~final-log-map :info)))

log-level-dispatch clj deprecated

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

log-reporter clj deprecated

(log-reporter registry)

log-span clj deprecated

(log-span span x)

(log-span span k v)

(log-span span k v & kvs)

Log to a given span, and return the span.

If the log message is a string, the message is logged as an info 'message'. If the log message is a keyword, the message is logged as an 'event', without a message. If the log message is a Throwable, the message is logged as an 'error', with info extracted from the Throwable If the log message is a map, the map is logged as a series of fields/values.

This also supports the same logging style as io.pedestal.log -- with any number of log keys and values.

You are encouraged to follow the OpenTracing semantics

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.

meter clj deprecated

(meter metric-name)

(meter metric-name n-events)

(meter recorder metric-name n-events)

metric-registry clj deprecated

(metric-registry & reporter-init-fns)

Create a metric-registry. Optionally pass in single-arg functions, which when passed a registry, create, start, and return a reporter.

MetricRecorder clj protocol deprecated

Metrics support in the pedestal.log library has been deprecated.

-counter clj

(-counter t metric-name delta)

Update a single Numeric/Long metric by the delta amount

-gauge clj

(-gauge t metric-name value-fn)

Register a single metric value, returned by a 0-arg function; This function will be called everytime the Gauge value is requested.

-histogram clj

(-histogram t metric-name value)

Measure a distribution of Long values

-meter clj

(-meter t metric-name n-events)

Measure the rate of a ticking metric - a meter.

override-logger clj

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

span clj deprecated

(span operation-name)

(span operation-name parent-span)

(span operation-name parent-span opts)

Given an operation name, and optionally a parent Span, and optionally a map of options return a new Span with the operation name set, started, and active.

Options are Tracer/TraceOrigin specific but all platforms support a minimum of: :initial-tags - a map of initial tags for the span

If the parent is not set, the span has no parent (ie: current active spans are ignored). If the parent is nil, the behavior is Tracer/TraceOrigin specific -- by default, the span has no parent.

span-baggage clj deprecated

(span-baggage span)

(span-baggage span k)

(span-baggage span k not-found)

span-log-error-kind clj deprecated

span-log-error-obj clj deprecated

span-log-event clj deprecated

span-log-msg clj deprecated

span-log-stack clj deprecated

spy clj macro

(spy expr)

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

tag-span clj deprecated

(tag-span span m)

(tag-span span k v)

(tag-span span tag-k tag-v & kvs)

Tag a given span.

Tags can be expressed as:

• a single tag key and tag value
• a sequence of tag-key tag-values.
• a map of tag-keys -> tag-values

trace clj macro

(trace & keyvals)

TraceOrigin clj protocol deprecated

Telemetry support in the pedestal.log library has been deprecated.

-activate-span clj

(-activate-span t span)

Given a Tracer/TraceOrigin and a span, activate the span and return the newly activated span.

-active-span clj

(-active-span t)

Given a Tracer/TraceOrigin, return the current, active Span or nil if there isn't an active span

-register clj

(-register t)

Given a Tracer/TraceOrigin perform whatever steps are necessary to register that Tracer/TraceOrigin to support the creation of spans, and return the Tracer/TraceOrigin.

It should not be necessary to make this call in application code. This call is only used when bootstrapping Pedestal's default-tracer

-span clj

(-span t operation-name)

(-span t operation-name parent)

(-span t operation-name parent opts)

Given a Tracer/TraceOrigin, an operation name, and optionally a parent Span, and a map of additional options return a new Span with the operation name set. If the parent is not set, the span has no parent (ie: current active spans are ignored).

Additional options are platform specific, but all platforms should support the following: :initial-tags - a map of initial tags for the span

** The span may be started on creation but should not be activated ** This should be left to application-specific span builders.

TraceSpan clj protocol deprecated

Telemetry support in the pedestal.log library has been deprecated.

-finish-span clj

(-finish-span t)

(-finish-span t micros)

Given a span, finish/complete and record the span optionally setting an explicit end timestamp in microseconds, and return the span. If no timestamp is specified, now/nanoTime is used, adjusted for microseconds. Multiple calls to -finishSpan should be noops

-set-operation-name clj

(-set-operation-name t operation-name)

Given a span and the operation name (String), set the logical operation this span represents, and return the Span.

-tag-span clj

(-tag-span t tag-key tag-value)

Given a span, a tag key (String), and a tag value (String), Set the tag key-value pair on the span for recording, and returns the Span.

Some trace systems support numeric, object, boolean and other values. The protocol encourages at a minimum String keys and values, but extensions of the protocols are free to make platform-specific type/arg optimizations. Some Trace platforms have semantics around tag keys/values, eg. https://github.com/opentracing/specification/blob/master/semantic_conventions.md

TraceSpanBaggage clj protocol deprecated

Telemetry support in the pedestal.log library has been deprecated.

-get-baggage clj

(-get-baggage t k)

(-get-baggage t k not-found)

Given a span, a baggage key, and optionally a not-found value, return the baggage value (String) for the corresponding key (if present). If the key isn't present, return not-found or nil.

-get-baggage-map clj

(-get-baggage-map t)

Given a span, return a Map of all baggage items.

-set-baggage clj

(-set-baggage t k v)

Given a span, a baggage key (String) and baggage value (String), add the key and value to the Span (and any additional context holding the span). and return the Span

Adding baggage allows keys/values to be smuggled across span boundaries, creating a powerful distributed context. Baggage is only propagated to children of the span.

TraceSpanLog clj protocol deprecated

Telemetry support in the pedestal.log library has been deprecated.

-error-span clj

(-error-span t throwable)

(-error-span t throwable micros)

Given a span, a Throwable, and optionally an explicit timestamp in microseconds, Record the error to the span as an 'error', attaching Message, Error.Kind and Error.Object to the span, and return the span.

-log-span clj

(-log-span t msg)

(-log-span t msg micros)

Given a span, a log message/event, and optionally an explicit timestamp in microseconds, Record the message to the span, and return the span.

If the message is a keyword, the message is recorded as an 'event', otherwise message is coerced into a string and recorded as a 'message'.

If no timestamp is specified, now/nanoTime is used, adjusted for microseconds.

TraceSpanLogMap clj protocol deprecated

Telemetry support in the pedestal.log library has been deprecated.

-log-span-map clj

(-log-span-map t msg-map)

(-log-span-map t msg-map micros)

Given a span, a map of fields, and optionally an explicit timestamp in microseconds, Record the event to the span, and return the span.

Semantic log fields can be found at: https://github.com/opentracing/specification/blob/master/semantic_conventions.md#log-fields-table

Some Trace Recorders don't fully support round-tripping maps -- use carefully. Some Trace platforms have semantics around key/values, eg. https://github.com/opentracing/specification/blob/master/semantic_conventions.md

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.

with-context-kv clj macro deprecated

(with-context-kv k v & body)

Given a key, value, and body, associates the key-value pair into the mdc-context only for the scope/execution of body, and formats and stores the mdc-context into the SLF4J MDC under the 'io.pedestal' key (via io.pedestal.log/mdc-context-key) using the formatter (from the :io.pedestal.log/formatter option, or default-formatter.

This macro has been deprecated, use with-context instead.

• This macro expands to nil if the provided k is nil; this is likely a day-1 bug
• This macro bypasses the LoggingMDC protocol, invoking SLF4J methods directly