Liking cljdoc? Tell your friends :D

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.

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.
raw docstring

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

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`.
sourceraw docstring

active-spanclj

(active-span)

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

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

add-span-baggage!clj

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

counterclj

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

debugcljmacro

(debug & keyvals)
source

default-recorderclj

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.

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.
sourceraw docstring

default-tracerclj

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.

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.
sourceraw docstring

errorcljmacro

(error & keyvals)
source

finish-spanclj

(finish-span span)

Given a span, finish the span and return it.

Given a span, finish the span and return it.
sourceraw docstring

format-nameclj

(format-name n)

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

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

gaugeclj

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

histogramclj

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

infocljmacro

(info & keyvals)
source

jmx-reporterclj

(jmx-reporter registry)
source

logclj

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

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)))
sourceraw docstring

log-level-dispatchclj

source

log-reporterclj

(log-reporter registry)
source

log-spanclj

(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

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

LoggerSourcecljprotocol

-debugclj

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

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.

-errorclj

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

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.

-infoclj

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

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.

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

-traceclj

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

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.

-warnclj

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

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

LoggingMDCcljprotocol

-clear-mdcclj

(-clear-mdc t)

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

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

-get-mdcclj

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

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

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

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

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

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

-set-mdcclj

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

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

make-loggerclj

(make-logger logger-name)

Returns a logger which satisfies the LoggerSource protocol.

Returns a logger which satisfies the LoggerSource protocol.
sourceraw docstring

maybe-init-java-util-logclj

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

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.
sourceraw docstring

mdc-context-keyclj

source

meterclj

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

metric-registryclj

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

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

MetricRecordercljprotocol

-counterclj

(-counter t metric-name delta)

Update a single Numeric/Long metric by the delta amount

Update a single Numeric/Long metric by the `delta` amount

-gaugeclj

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

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

-histogramclj

(-histogram t metric-name value)

Measure a distribution of Long values

Measure a distribution of Long values

-meterclj

(-meter t metric-name n-events)

Measure the rate of a ticking metric - a meter.

Measure the rate of a ticking metric - a meter.
source

override-loggerclj

source

spanclj

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

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.
sourceraw docstring

span-baggageclj

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

span-log-error-kindclj

source

span-log-error-objclj

source

span-log-eventclj

source

span-log-msgclj

source

span-log-stackclj

source

spycljmacro

(spy expr)

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

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

tag-spanclj

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

tracecljmacro

(trace & keyvals)
source

TraceOrigincljprotocol

-activate-spanclj

(-activate-span t span)

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

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

-active-spanclj

(-active-span t)

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

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

-registerclj

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

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`

-spanclj

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

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

TraceSpancljprotocol

-finish-spanclj

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

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

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

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

-tag-spanclj

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

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
source

TraceSpanBaggagecljprotocol

-get-baggageclj

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

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

(-get-baggage-map t)

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

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

-set-baggageclj

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

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

TraceSpanLogcljprotocol

-error-spanclj

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

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

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

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

TraceSpanLogMapcljprotocol

-log-span-mapclj

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

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
source

warncljmacro

(warn & keyvals)
source

with-contextcljmacro

(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

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

with-context-kvcljmacro

(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

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

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close