nx_trace.nx

nx_trace.nx -- span-based tracing. Structured call-tree observability. When a function enters + exits, emit a pair of span events with matching IDs, so offline analysis can reconstruct the exact call path and timing profile. Design draws from: OpenTelemetry tracing data model -- span id, parent id, start/end, attributes Google Dapper (Sigelman et al 2010) -- distributed tracing origin paper Rust tracing crate -- in-process span primitives Linux ftrace -- kernel-mode per-function trace perf probe -- USDT tracepoints Span events are emitted through nx_log, so all existing level/tag/filter infrastructure applies. Format: <seq> DEBUG span.enter <tag> id=<N> parent=<P> <seq> DEBUG span.exit <tag> id=<N> dt=<elapsed_ticks> Matching pairs reconstruct the tree off-line via seq ordering. `dt` is a monotonic tick counter the tracer maintains (NOT wall-clock, by design -- reproducible across runs). Not yet (deferred): * rdtime CSR read for real wall-clock nanoseconds. Needs inline asm in NishiLang, which we don't have yet. When it lands, dt gets real ns units. * Sampling -- limit overhead by only tracing every N calls. * Remote export -- emit spans to a socket in OTLP / Zipkin protobuf format for external analyzers. Span IDs are monotonic per-context. Parent id = id of the enclosing span, or 0 for root spans. For single-threaded v0.0.1 we track a stack of active span ids. When threading arrives, per-thread span stacks + flush-on-thread-join are the pattern.