# `Insider.Collector.Calls`
[🔗](https://github.com/hiivemarkets/insider/blob/v0.1.0/lib/insider/collector/calls.ex#L1)

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](docs/live/live-runtime-evidence.md#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.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `flush`

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

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

# `inventory`

```elixir
@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`

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

# `status`

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

# `stop`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
