Insider.Collector.Calls (Insider v0.1.0)

Copy Markdown View Source

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 records call.stopped with reason ingress_bytes. Neither this process nor the inlet is ever traced.
  • While more than :max_waiting messages 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

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

flush(server)

@spec flush(GenServer.server()) :: {:ok, map()} | {:error, :unavailable}

Processes every trace message sent before the call, then returns the status.

inventory(server)

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

start_link(recorder, options)

@spec start_link(Insider.Recorder.Handle.t(), keyword()) ::
  GenServer.on_start() | {:error, atom()}

status(server)

@spec status(GenServer.server()) :: {:ok, map()} | {:error, :unavailable}

stop(server)

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