hive-ttracking.span — io.github.hive-agi/hive-ttracking 0.1.4

BC-3 Spans — span sink abstraction + pure helpers over Span values.

Wave-2: helpers for closing/tagging/hierarchy. Sinks are Wave-3. See PLAN.md §2 BC-3.

add-sample clj

(add-sample span k v)

Append {:k k :v v :at nanoTime} onto the span's :samples vector. Preserves insertion order.

close clj

(close span result)

(close span result t1)

Return a closed copy of span stamped with t1 (defaults to nanoTime) and a result value. Pure — does not emit events or mutate sinks.

closed? clj

(closed? span)

True iff span has :t1 set.

descendant? clj

(descendant? maybe-child maybe-ancestor)

True iff maybe-child claims maybe-ancestor as its direct parent. Shallow (one-hop) — full-chain walks require an external index.

elapsed-ms clj

(elapsed-ms span)

Milliseconds elapsed. See elapsed-ns. Returns nil if malformed.

elapsed-ns clj

(elapsed-ns {:keys [t0 t1] :as _span})

Nanoseconds from span open. Uses :t1 if closed, else nanoTime - :t0. Returns nil if span has no :t0 (malformed).

ISpanSink clj protocol

flush! clj

(flush! this)

Force-flush any buffered spans. Returns Result.

query clj

(query this filter-fn)

Query stored spans by predicate. Returns Result.

record! clj

(record! this span)

Persist a closed Span. Returns Result.

noop-sink clj

(noop-sink)

tag clj

(tag span tag-map)

(tag span k v)

Attach a tag (or merge a map of tags) onto a span. Returns updated span.

with-parent clj

(with-parent child parent)

Return child with :parent-id bound to parent's :id. Accepts either a Span record or a raw id keyword/uuid/string for parent.