io.pedestal.log

Logging via slf4j. Each logging level is a macro: trace, debug,
info, warn, and error. Each namespace gets its own Logger. Arguments
are key-value pairs, which will be printed as with 'pr'. The special
key :exception should have a java.lang.Throwable as its value, and
will be passed separately to the underlying logging API.
One can override the logger via JVM or ENVAR settings.

*mdc-context*

dynamic

This map is copied into the SLF4J MDC when the `with-context` or
`with-context-kv` macros are used.  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

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

add-span-baggage!

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

counter

(counter metric-name delta)(counter recorder metric-name delta)

debug

macro

(debug & keyvals)

default-recorder

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

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

macro

(error & keyvals)

finish-span

(finish-span span)
Given a span, finish the span and return it.

format-name

(format-name n)
Format a given metric name, regardless of type, into a string

gauge

(gauge metric-name value-fn)(gauge recorder metric-name value-fn)

histogram

(histogram metric-name value)(histogram recorder metric-name value)

info

macro

(info & keyvals)

jmx-reporter

(jmx-reporter registry)

log

(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).

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:
 :level -- A keyword, the log level to use for this message, defaults to `default-level`
 :exception -- A Throwable/Exception to log
 :io.pedestal.log/logger -- The logger to use for this message,
                            defaults to the `override-logger` or the SLF4J logger
 :io.pedestal.log/logger-name -- A String, the loggerName to use if SLF4J logger is used,
                                 defaults to `*ns*` which may be 'clojure.core' depending on execution,
 :io.pedestal.log/formatter -- A single-arg function that when given a map, returns a String for logging,
                               defaults to `pr-str`

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

log-reporter

(log-reporter registry)

log-span

(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

protocol

members

-debug

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

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

(-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?

(-level-enabled? t level-key)
Given the log level as a keyword,
return a boolean if that log level is currently enabled.

-trace

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

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

protocol

members

-clear-mdc

(-clear-mdc t)
Remove all entries within the MDC
and return the MDC instance.

-get-mdc

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

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

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

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

maybe-init-java-util-log

(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

meter

(meter metric-name)(meter metric-name n-events)(meter recorder metric-name n-events)

metric-registry

(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

protocol

members

-counter

(-counter t metric-name delta)
Update a single Numeric/Long metric by the `delta` amount

-gauge

(-gauge t metric-name value-fn)
Register a single metric value, returned by a 0-arg function;
This function will be called everytime the Guage value is requested.

-histogram

(-histogram t metric-name value)
Measure a distribution of Long values

-meter

(-meter t metric-name n-events)
Measure the rate of a ticking metric - a meter.

override-logger

span

(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

(span-baggage span)(span-baggage span k)(span-baggage span k not-found)

span-log-error-kind

span-log-error-obj

span-log-event

span-log-msg

span-log-stack

spy

macro

(spy expr)
Logs expr and its value at DEBUG level, returns value.

tag-span

(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

macro

(trace & keyvals)

TraceOrigin

protocol

members

-activate-span

(-activate-span t span)
Given a Tracer/TraceOrigin and a span,
activate the span
and return the newly activated span.

-active-span

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

-register

(-register t)
Given a Tracer/TraceOrigin
perform whatver 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

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

protocol

members

-finish-span

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

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

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

protocol

members

-get-baggage

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

(-get-baggage-map t)
Given a span,
return a Map of all baggage items.

-set-baggage

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

protocol

members

-error-span

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

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

protocol

members

-log-span-map

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

macro

(warn & keyvals)

with-context

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 SLF4J MDC unless the `:io.pedestal.log/mdc`
option is specified (see Options).
All options from the map are removed when setting the MDC.

By default, the map is formatted into a string value and stored
under the 'io.pedestal' key, via `io.pedestal.log/mdc-context-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](https://logback.qos.ch/manual/mdc.html#autoMDC) for more
information.


Options:
 :io.pedestal.log/formatter - a single-arg function that when given the map, returns a formatted string
                              Defaults to `pr-str`
 :io.pedestal.log/mdc - An object that satisfies the LoggingMDC protocol
                        Defaults to the SLF4J MDC.

Note:
If you mix `with-context` with the more basic `with-context-kv`, you may see undesired keys/values in the log

with-context-kv

macro

(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 sets the *mdc-context* into the SLF4J MDC
 under the 'io.pedestal' key (via `io.pedestal.log/mdc-context-key`) using `pr-str` on the map for the MDC value.

Note:
No keys are are dissoc'd from *mdc-context* with this simplified version.
If you mix `with-context` and `with-context-kv`, you may see undesired keys/values in the log