Bounded call tracing of selected functions as call, call.return,
call.exception, and call.stopped events.
It runs only in a collector session that names the :calls component, so
the trace belongs to the session and its owner, never to the process that
asked for it: it ends when the session stops, its lease expires, or an
amendment replaces the segment, and the session's cleanup receipt proves
the trace session and each of its function patterns are gone.
Tracing uses an isolated OTP trace session (Insider.Collector.Calls.Tracing,
OTP 28 and later), so it never touches trace state it did not set. The
bookkeeping, limits, and rendering are Insider.Collector.Calls.Trace.
Ingress has a soft byte bound, for development and test nodes only: the
runtime delivers a trace message before any code here can refuse it, so
the bound limits what reaches this process and stops the trace quickly,
not what the runtime may copy first (see
Call traces for the
measured worst cases).
- In the strict profile (
rich: false, the safe default) a call message carries only the arity: no argument is copied out of the calling process. Results still carry their value. - Trace messages go to an inlet process that measures each one as it
reads it, its external size plus, for a top-level binary argument or
result that is a sub-binary, the larger binary it keeps alive, and
forwards it here. The bytes forwarded and not yet handled here are
counted; a message that would take them above
:max_ingress_bytes(default 8 MiB) is dropped, the inlet removes the trace's patterns and process flags itself, and the trace recordscall.stoppedwith reasoningress_bytes. Neither this process nor the inlet is ever traced. - While more than
:max_waitingmessages wait here, the trace stops (overload). - As a last resort this process's heap, shared binaries included, is
limited to eight times the byte budget, at least 64 MiB: above it the
runtime kills it, which destroys the trace session, and the collector
session ends as
cleanup_incomplete.
Not bounded: the inlet's mailbox before it reads a message (measured peaks reach hundreds of thousands of messages under a tight-loop burst); a sub-binary nested inside an argument or result, charged only its own bytes; and one message larger than the budget, copied once before the inlet drops it.
flush/1 and stop/1 drain through the inlet. A stop whose drain does
not finish counts what the inlet still held, or had taken and not yet
forwarded, as undrained; when it cannot prove that count exact,
undrained_unknown says so.
Messages that arrive after a stop are counted as shed. Every received trace
message is counted once: as recorded, recorder_dropped, invalid, shed,
or as a result that pairs with its call without an event of its own.
Summary
Functions
Returns a specification to start this module under a supervisor.
Processes every trace message sent before the call, then returns the status.
The trace's inventory: its session's weak reference and the traced functions, which the collector session checks independently at cleanup.
Removes the trace, records what was sent before the removal, and stops.
Returns the final status and the removal observation (Tracing.remove/1).
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec flush(GenServer.server()) :: {:ok, map()} | {:error, :unavailable}
Processes every trace message sent before the call, then returns the status.
@spec inventory(GenServer.server()) :: {:ok, map()} | {:error, :unavailable}
The trace's inventory: its session's weak reference and the traced functions, which the collector session checks independently at cleanup.
@spec start_link(Insider.Recorder.Handle.t(), keyword()) :: GenServer.on_start() | {:error, atom()}
@spec status(GenServer.server()) :: {:ok, map()} | {:error, :unavailable}
@spec stop(GenServer.server()) :: {:ok, map()} | {:error, :unavailable}
Removes the trace, records what was sent before the removal, and stops.
Returns the final status and the removal observation (Tracing.remove/1).