Internals

StreamState

Internal state for the single global trace buffer and its (optional) background writer task.

Events live in a fixed-size ring buffer (slots) that is written to without locks: a producer claims a slot by atomically bumping write_idx, stores its event, then publishes the slot by writing the claimed sequence number into slot_seq. The drain side only consumes a slot once its slot_seq matches the sequence it expects, so a slot that has been claimed but not yet filled is never read.

_make_stream_state(capacity::Int) -> StreamState

Allocate a fresh StreamState with a ring buffer of capacity slots and no background writer attached.

_ensure_stream_state() -> StreamState

Return the process-global StreamState, lazily creating one with DEFAULT_BUFFER_LIMIT slots if it does not exist yet.

_append_event!(stream::StreamState, event) -> Bool

Append event to stream's ring buffer without locking.

Returns true if the event was stored, or false if the buffer was full, in which case the event is dropped and stream.dropped is incremented. Dropping rather than blocking keeps tracing overhead bounded on the hot path.

_drain_buffer!(stream::StreamState) -> Vector{Dict{String,Any}}

Remove and return every fully-published event from stream's ring buffer, in the order the events were recorded.

Only one thread drains at a time; if another drain is already in progress this returns an empty vector immediately. Draining also stops at the first slot that has been claimed by a producer but not yet published, so events are never returned out of order or half-written.

_reset_buffer!(stream::StreamState)

Discard every buffered event in stream and reset its ring buffer indices and dropped-event counter back to their initial values.

_flush_stream_state(stream::StreamState; finalize::Bool=false) -> Int

Drain stream's buffer and append the events to its open trace file, returning the number of events written. Returns 0 if stream is not currently writing to a file.

When finalize is true, the closing ] is written and the file is closed, so the trace on disk is a complete JSON array.

_now_ts() -> Int

Current monotonic timestamp in microseconds, the unit for the ts field.

_normalize_args(args)

Convert args into a Dict with String keys, so that it round-trips through JSON as an object. Dicts, NamedTuples, generators and tuples of pairs are all accepted; anything else is returned unchanged.

_coerce_trace_key(key) -> String

Convert a trace event key (a Symbol, AbstractString, or anything else) into a String suitable for use as a JSON object key.

_write_json_array(path, events) -> Int

Write events to path as a single JSON array, creating the containing directory if needed. Returns the number of events written.