salutem.core.checks — io.logicblocks/salutem.core 0.1.9-RC2

Provides constructors, predicates and evaluation functions for checks.

attempt clj

(attempt dependencies trigger-id check)

(attempt dependencies trigger-id check context)

(attempt dependencies trigger-id check context result-channel)

Attempts to obtain a result for a check, handling timeouts and exceptions.

Takes the following parameters:

• dependencies: A map of dependencies used by attempt in obtaining the result, currently supporting only a :logger entry with a cartus.core/Logger value.
• trigger-id: An ID identifying the attempt in any subsequently produced messages and used in logging.
• check: the check to be attempted.
• context: an optional map containing arbitrary context required by the check in order to run and passed to the check functions as the first argument; defaults to an empty map.
• result-channel: an optional channel on which to send the result message; defaults to a channel with a buffer length of 1.

The attempt is performed asynchronously and the result channel is returned immediately.

In the case that the attempt takes longer than the check's timeout, an unhealthy result is produced, including :salutem/reason as :timed-out.

In the case that the attempt throws an exception, an unhealthy result is produced, including :salutem/reason as :exception-thrown and including the exception at :salutem/exception.

In all other cases, the result produced by the check is passed on to the result channel.

All produced results include a :salutem/evaluation-duration entry with the time taken to obtain the result, which can be overridden within check functions if required.

background-check clj

(background-check check-name check-fn)

(background-check check-name check-fn opts)

Constructs a background check with the provided name and check function.

A background check is one that is evaluated periodically with the result cached in a registry until the next evaluation, conducted by a maintenance pipeline, which will occur once the time to re-evaluation of the check has passed.

Background checks are useful for external dependencies where it is important not to perform the check too frequently and where the health status only needs to be accurate on the order of the time to re-evaluation.

Takes the following parameters:

• check-name: a keyword representing the name of the check
• check-fn: an arity-2 function, with the first argument being a context map as provided during evaluation or at maintenance pipeline construction and the second argument being a callback function which should be called with the result of the check to signal the check is complete; note, check functions must be non-blocking.
• opts: an optional map of additional options for the check, containing:
  • :salutem/timeout: a [[salutem.time/duration]] representing the amount of time to wait for the check to complete before considering it failed, defaulting to 10 seconds.
  • :salutem/time-to-re-evaluation: a [[salutem.time/duration]] representing the time to wait after a check is evaluated before attempting to re-evaluate it, defaulting to 10 seconds.

Any extra entries provided in the opts map are retained on the check for later use.

Note that a result for a background check may live for longer than the time to re-evaluation since evaluation takes time and the result will continue to be returned from the registry whenever the check is resolved until the evaluation has completed and the new result has been added to the registry.

background? clj

(background? check)

Returns true if the provided check is a background check, false otherwise.

check-name clj

(check-name check)

Returns the name of the provided check.

evaluate clj

(evaluate check)

(evaluate check context)

(evaluate check context callback-fn)

Evaluates the provided check, returning the result of the evaluation.

Optionally takes a context map containing arbitrary context required by the check in order to run and passed to the check function as the first argument.

By default, the check is evaluated synchronously. If a callback function is provided, the function starts evaluation asynchronously, returns immediately and invokes the callback function with the result once available.

realtime-check clj

(realtime-check check-name check-fn)

(realtime-check check-name check-fn opts)

Constructs a realtime check with the provided name and check function.

A realtime check is one that is re-evaluated whenever the check is resolved, with no caching of results taking place.

Realtime checks are useful when the accuracy of the check needs to be very high or where the check itself is inexpensive.

Takes the following parameters:

• check-name: a keyword representing the name of the check
• check-fn: an arity-2 function, with the first argument being a context map as provided during evaluation or at maintenance pipeline construction and the second argument being a callback function which should be called with the result fo the check to signal the check is complete; note, check functions must be non-blocking.
• opts: an optional map of additional options for the check, containing:
  • :salutem/timeout: a [[salutem.time/duration]] representing the amount of time to wait for the check to complete before considering it failed, defaulting to 10 seconds.

Any extra entries provided in the opts map are retained on the check for later use.

realtime? clj

(realtime? check)

Returns true if the provided check is a realtime check, false otherwise.