ken.core — com.amperity/ken 1.1.0

Core user API namespace for ken instrumentation.

There are really three significant phases where data is collected to form an event or 'span':

1. At the beginning of a span, to initialize the event data:
   • base: label, time, level
   • callsite: ns, line
   • trace: trace-id, parent-id, span-id
   • sampling: sample-rate, keep?
2. During a span:
   • using annotate, error, and time
3. At the end of a span:
   • context collection
   • thread name
   • duration

An observe call performs the first and third phases back-to-back and immediately sends an event, while watch will wrap a body of code, providing time to enrich it with extra data in phase two.

annotate clj

(annotate data)

Add fields to the enclosing span event.

error clj

(error ex)

Annotate the enclosing span with an error that was encountered during execution.

Sets the following attributes:

• :ken.event/level to :error
• :ken.event/fault? to true
• :ken.event/error to the given exception

observe clj macro

(observe data)

(observe data timeout-ms)

Observe an event about the system. Returns true if the event was accepted or false if it was dropped.

By default this returns immediately. If a timeout is given, this will block until the event is accepted or the timeout expires.

time clj macro

(time event-key & body)

Time the given body of expressions and annotate the enclosing span with the duration in milliseconds under the given key.

watch clj macro

(watch data & body)

Wrap a span event observation around a body of expressions.

The data provided may be a string or a keyword, in which case it will be used directly as the event's label. To pass additional event attributes, you can instead provide a map (which must include a value for ::event/label).

;; shorthand
(ken/watch "my.code/do-the-thing"
  ,,,)

;; shorthand with auto-resolved keyword
(ken/watch ::do-the-thing
  ,,,)

;; expanded form
(ken/watch {::ken.evt/label "my.code/do-the-thing"
            ::something 123
            ,,,}
  ,,,)

The provided data will be merged into the base event, which will also include timing and tracing properties.

with-context clj macro

(with-context ctx & body)

Evaluate the body of expressions with the given data merged into the local context.