io.pedestal.log — io.pedestal/pedestal.log 0.5.11-beta-1

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

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 clj

(active-span)

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

add-span-baggage! clj

(add-span-baggage! span m)

(add-span-baggage! span k v)

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

counter clj

(counter metric-name delta)

(counter recorder metric-name delta)

debug clj macro

(debug & keyvals)

default-recorder clj

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

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

(finish-span span)

Given a span, finish the span and return it.

format-name clj

(format-name n)

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

gauge clj

(gauge metric-name value-fn)

(gauge recorder metric-name value-fn)

histogram clj

(histogram metric-name value)

(histogram recorder metric-name value)

info clj macro

(info & keyvals)

jmx-reporter clj

(jmx-reporter registry)

log clj

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

log-reporter clj

(log-reporter registry)

log-span clj

(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

-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

meter clj

(meter metric-name)

(meter metric-name n-events)

(meter recorder metric-name n-events)

metric-registry clj

(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

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

span clj

(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

(span-baggage span)

(span-baggage span k)

(span-baggage span k not-found)

span-log-error-kind clj

span-log-error-obj clj

span-log-event clj

span-log-msg clj

span-log-stack clj

spy clj macro

(spy expr)

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

tag-span clj

(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

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

-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

-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

-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

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