Context
PR #1330 removed runtime/utils/aether_tracing.c: it compiled into every build and its header was emitted into all generated C, but no code path ever called it, and the README advertised a message-tracing capability that did not exist. This issue is the place to design the real thing before any code returns.
What the removed sketch had (useful as a feature list, not as a base): per-actor send/receive/process event logging with timestamps, per-actor filters, enable/disable toggles, and a log-file writer. What it never had: call sites, an activation surface, docs, or an overhead story.
Design questions
- Cost when off. Hot-path message send is the runtime's core loop. The existing
-DAETHER_PROFILE pattern (docs/profiling-guide.md: macros compile to ((void)0) without the flag) is the proven shape; a runtime branch on every send needs justification.
- Hook points.
scheduler_send_local / scheduler_send_remote, the direct-send bypass, SPSC enqueue, mailbox receive, and step dispatch, so a trace shows the actual delivery path taken, not just "sent".
- Readable identity. The runtime sees message types as ints and actors as IDs. Codegen knows the message names; emitting a name table into generated C would make traces human-readable without runtime cost.
- Output. JSONL vs binary ring buffer dumped at exit; activation via env (
AETHER_TRACE=file) vs flag; interaction with multi-threaded schedulers (per-core buffers, merge at exit) to avoid a global lock on the hot path.
Acceptance
- Zero measured overhead when disabled (benchmark before/after on ping-pong and fork-join).
- Wired into the real delivery paths listed above, with a test that traces a known message sequence and asserts the events.
- Documented; the README/feature claim returns only once it is true.
Context
PR #1330 removed
runtime/utils/aether_tracing.c: it compiled into every build and its header was emitted into all generated C, but no code path ever called it, and the README advertised a message-tracing capability that did not exist. This issue is the place to design the real thing before any code returns.What the removed sketch had (useful as a feature list, not as a base): per-actor send/receive/process event logging with timestamps, per-actor filters, enable/disable toggles, and a log-file writer. What it never had: call sites, an activation surface, docs, or an overhead story.
Design questions
-DAETHER_PROFILEpattern (docs/profiling-guide.md: macros compile to((void)0)without the flag) is the proven shape; a runtime branch on every send needs justification.scheduler_send_local/scheduler_send_remote, the direct-send bypass, SPSC enqueue, mailbox receive, and step dispatch, so a trace shows the actual delivery path taken, not just "sent".AETHER_TRACE=file) vs flag; interaction with multi-threaded schedulers (per-core buffers, merge at exit) to avoid a global lock on the hot path.Acceptance