macula_packet_trace (macula v4.3.0)
View SourcePer-flow packet trace toggle for macula-net.
Phase 4.1 — see PLAN_MACULA_NET_PHASE4_1_OBSERVABILITY.md.
Disabled by default. Operators enable by address (16-byte binary) or wildcard (enable_all/0). When enabled for an address, any envelope whose src or dst matches the address is logged via OTP logger at debug level under topic _macula.net.packet_trace.envelope.
The trace is stored as a persistent_term so the hot path can read it with no ETS lookup, no gen_server roundtrip. The trade-off: updates are slow (persistent_term is not designed for high-frequency mutation), but operators flip the trace at human cadence.
Summary
Functions
Remove an address from the enabled set. Disables the trace entirely if no addresses remain enabled.
Enable trace for a single 16-byte macula-net address. Idempotent.
Enable trace for ALL traffic. Use with care — high-volume.
True if Addr is currently being traced.
Snapshot of current trace state.
Log this envelope if the src/dst matches the enabled set. Cheap when disabled (one persistent_term lookup, one map check).
Types
Functions
-spec disable(addr()) -> ok.
Remove an address from the enabled set. Disables the trace entirely if no addresses remain enabled.
-spec disable_all() -> ok.
-spec enable(addr()) -> ok.
Enable trace for a single 16-byte macula-net address. Idempotent.
-spec enable_all() -> ok.
Enable trace for ALL traffic. Use with care — high-volume.
True if Addr is currently being traced.
-spec state() -> state().
Snapshot of current trace state.
-spec trace_envelope(direction(), addr(), addr(), iodata() | non_neg_integer()) -> ok.
Log this envelope if the src/dst matches the enabled set. Cheap when disabled (one persistent_term lookup, one map check).