Realtime Packet Debug Capture And Triage

Use realtime packet debug capture when a client and server disagree about whether a stream message or datagram was sent, accepted, validated, dropped, or delivered on the expected transport path.

Purpose

Packet capture is a metadata-only debugging tool. It records packet direction, transport, name, stream message id when present, protocol hints, feature flags, and payload length without writing raw payload bytes. This keeps capture useful for protocol triage without turning it into a data dump.

Steps

Set AETHER_PACKET_DEBUG_CAPTURE_DIR before starting the client, server, or smoke harness. Each process writes {executable}-{pid}.jsonl under that directory. Reproduce the issue, then compare client and server files by timestamp, packet name, direction, and transport.

Use stream captures to inspect message ids and reliable lanes. Use datagram captures to inspect datagram kind and freshness-first traffic. Pair capture records with packet validation metrics when the packet appears in capture but does not affect state.

Expected Outputs

A useful capture has one JSON object per packet metadata record. For stream messages, expect a stable message_id. For datagrams, expect a datagram packet name rather than a stream id. Payload length should stay within the generated protocol budget.

Common Mistakes

Leaving the env var unset makes capture a no-op. Directory creation or file-open failures disable capture for that process. The bounded writer queue can drop capture records under heavy load, so missing rows are evidence, not proof that a packet never existed.

Do not commit capture output. Keep it in artifacts/, target/, or another ignored path.

Recovery Paths

For a missing packet, compare both process files and then inspect outbound queue drops. For wrong ordering, compare stream class and datagram freshness rules. For budget failures, use the capture payload length and generated registry budget. For datagram-vs-stream mismatch, inspect the registry row and the datagram codec page.