ken.trace — com.amperity/ken 1.0.2

Tracing support for instrumenting code.

Trace data is structured as events with a few special properties:

• ::trace/trace-id The parent identifier for the overall trace of all linked events.
• ::trace/span-id A unique identifier for this event.
• ::trace/parent-id The span which is the parent of this one.
• ::trace/keep? A boolean to represent a sampling decision for events sent to ken on whether to keep or drop the spans of a trace.
  • The absence of this key means the observed event will be kept and forwarded along. This is the default state.
  • false means to discard a span. This decision will be propagated to child spans, but can be overridden later by a child span that decides to force keep.
  • true means to forcibly keep a span and all of its child spans, ignoring all other sampling decisions in the subtree.

Additionally, trace events must have:

• ::event/time This indicates the instant the span started.
• ::event/duration The duration (in milliseconds) the span covers.

*data* clj/s

Dynamic context holding the data for the current trace. When inside a span, this should be bound to an atom containing a map with event data.

child-attrs clj/s

(child-attrs)

(child-attrs data)

Return a map of trace attributes for a new child of the current span, if any. Generates a new trace-id and span-id as necessary.

current-data clj/s

(current-data)

Return the current trace-id, span-id, and keep flag from the dynamic context, if any.

current-span-id clj/s

(current-span-id)

Return the current span-id from the trace context, if any.

current-trace-id clj/s

(current-trace-id)

Return the current trace-id from the trace context, if any.

format-header clj/s

(format-header data)

Construct a tracing header for inclusion in an HTTP request. Returns the constructed header string if the map of data provided has at least a trace-id and span-id.

gen-span-id clj/s

(gen-span-id)

Generate a new span identifier.

gen-trace-id clj/s

(gen-trace-id)

Generate a new trace identifier.

header-name clj/s

Name of the header typically used to propagate Ken traces.

maybe-sample clj/s

(maybe-sample event)

Apply sampling logic to the event, returning an updated event map.

parse-header clj/s

(parse-header value)

Parse a tracing header from an HTTP request. Header values must start with {version}-. Returns a map of trace properties, or nil if the header is absent or unrecognized.

sample? clj/s

(sample? sample-rate)

Randomly decide whether to keep or drop a span using the given rate. A result of false means drop and a result of true means keep.

with-data clj/s macro

(with-data data & body)

Evaluate the body with the tracing state bound to the given data.