Search documentation of macula

# macula_packet_trace (macula v4.4.1)

View Source

Per-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

## Types

addr/0
direction/0
state/0

## Functions

disable(Addr)

Remove an address from the enabled set. Disables the trace entirely if no addresses remain enabled.

disable_all()
enable(Addr)

Enable trace for a single 16-byte macula-net address. Idempotent.

enable_all()

Enable trace for ALL traffic. Use with care — high-volume.

is_enabled_for(Addr)

True if `Addr` is currently being traced.

state()

Snapshot of current trace state.

trace_envelope(Direction, Src, Dst, Payload)

Log this envelope if the src/dst matches the enabled set. Cheap when disabled (one persistent_term lookup, one map check).

# Types

# addr/0

    -type addr() :: <<_:128>>.

# direction/0

    -type direction() :: ingress | egress | relay.

# state/0

    -type state() :: #{enabled := boolean(), addrs := [addr()]}.

# Functions

# disable(Addr)

    -spec disable(addr()) -> ok.

Remove an address from the enabled set. Disables the trace entirely if no addresses remain enabled.

# disable_all()

    -spec disable_all() -> ok.

# enable(Addr)

    -spec enable(addr()) -> ok.

Enable trace for a single 16-byte macula-net address. Idempotent.

# enable_all()

    -spec enable_all() -> ok.

Enable trace for ALL traffic. Use with care — high-volume.

# is_enabled_for(Addr)

    -spec is_enabled_for(addr()) -> boolean().

True if `Addr` is currently being traced.

# state()

    -spec state() -> state().

Snapshot of current trace state.

# trace_envelope(Direction, Src, Dst, Payload)

    -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).