Skip to content

Runtime: message tracing for debugging, design + wire-up (zero cost when off) #1333

Description

@nicolas-maman

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

  1. 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.
  2. 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".
  3. 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.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions