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)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.
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-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.
make-logger
(make-logger logger-name)Returns a logger which satisfies the LoggerSource protocol.
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.
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.
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.
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
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
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 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