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

BC-1 Tracking — span lifecycle + track/track-race macros.

Wave-2: AtomTracker + real track*. Wave-3 fills track-race*. See PLAN.md §2 BC-1.

*default-tracker* clj

current-tracker clj

(current-tracker)

(current-tracker opt-tracker)

Resolve the active tracker: explicit opt > default-tracker > shared default.

default-log-sink clj

(default-log-sink {:keys [label elapsed-ms n]})

Default telemetry sink used by timed-query. Logs elapsed-ms + n at :info on non-empty results, :warn on zero-row completion (fork-join fallback symptom). Overridable via dependency injection at the call site.

ITracker clj protocol

Owns span lifecycle. Pure when backed by atom-sink; async when pool-backed.

end-span clj

(end-span this span result)

Close span, emit :tt/span-ended, return closed Span.

record-sample clj

(record-sample this span-id k v)

Attach a typed sample to an open span (latency subcomponent, counter, ...).

start-span clj

(start-span this span-name tags)

Return an open Span value with :id :parent :t0.

make-atom-tracker clj

(make-atom-tracker)

(make-atom-tracker {:keys [max-open max-closed ttl-ms on-evict]
                    :or {max-open 10000 max-closed 10000 ttl-ms 3600000}})

Construct an AtomTracker.

Options: :max-open — cap on concurrently open spans (default 10_000) :max-closed — cap on retained closed spans (default 10_000) :ttl-ms — TTL for both maps (default 1h; nil = no TTL) :on-evict — optional (fn [{:keys [name evicted-count reason entries]}])

make-span clj

(make-span {:keys [id parent-id name tags]})

timed-query clj

(timed-query label qfn)

(timed-query label qfn sink)

Wrap a query thunk with elapsed-ms + row-count telemetry.

Returns a thunk of no arguments. Invoking it runs qfn, measures wall time, counts rows in the result, and calls sink with the observation before returning the original result unchanged.

Args: label — string used in telemetry (e.g. "catchup-hierarchy") qfn — 0-arg fn that performs the query and returns a countable result sink — optional 1-arg fn receiving {:label :elapsed-ms :n :result} Defaults to default-log-sink.

Shape is DI-friendly: call sites never reach into hive-ttracking internals; they hand in (tt/timed-query label qfn) and the addon decides how to emit.

Example — plug into a fork-join task: [:hierarchy (tt/timed-query "hierarchy" #(query-milvus ...)) []]

track* clj

(track* {:keys [name tags tracker budget-ms policy]
         :or {tags {} policy :partial}}
        thunk)

Wrap a thunk with a budget-enforced span. Returns {:span closed-span :result <thunk-result-or-nil> :error <Throwable-or-nil>}.

opts: :name keyword or string — span name (required) :budget-ms long — optional deadline :policy #{:hard :soft :partial} (default :partial) :tags map — tags attached to span + events :tracker ITracker — override current-tracker

Semantics:

• Thunk runs inside (try ... (catch Throwable t ...)) so AssertionError does not leak past the tracker (axiom 3d0e1f7c).
• On thunk success, budget is checked; :hard violation throws ex-info with :tt/budget-exceeded after the span is closed and events published.
• On thunk throw, span is closed with {:ok false :error msg} and the Throwable is returned in :error (not re-thrown — callers decide).

track-race* clj

(track-race* _opts branches-map)

Wave-3. Races branches-map under a single budget using hive-weave pool. Returns {branch-key Result}. Replaces the ad-hoc future/deref/cancel pattern seen in hive-mcp.tools.catchup.scope/query-axioms.