# `Ascii.BEAM`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/beam.ex#L1)

This VM's readings, as options for the data pieces: an htop of the BEAM.
Its schedulers are cores, its memory is memory, its run queue is the load,
and its processes are the process list, busiest first by reductions.

    sample = Ascii.BEAM.sample()
    # a second later
    sample = Ascii.BEAM.sample(sample)

    Ascii.put_options!(meters, Ascii.BEAM.cpu_meters(sample))
    Ascii.put_options!(history, Ascii.BEAM.sparkline(sample))
    Ascii.put_options!(busy, Ascii.BEAM.gauge(sample))

Take a sample every second or so, each from the one before: scheduler
use, the load and the busiest processes are measured between two
samples, and the sparkline's history is the samples' own. `mix
ascii.top` plays them in a terminal; in a LiveView, give them to
`Ascii.Phoenix.live_player/1` from a timer.

Scheduler use needs the VM's `scheduler_wall_time` flag, which the first
sample turns on for as long as the process that took it lives (see
`:erlang.system_flag/2`), so take samples from one long-lived process.

# `t`

```elixir
@type t() :: %Ascii.BEAM{
  at: integer(),
  busy: float(),
  cores: [float()],
  history: [{float(), non_neg_integer(), non_neg_integer()}],
  load: [float()],
  memory: non_neg_integer(),
  memory_parts: [{atom(), float()}],
  processes: non_neg_integer(),
  reductions: %{optional(pid()) => non_neg_integer()},
  run_queue: non_neg_integer(),
  sched: term(),
  top: [map()],
  uptime: non_neg_integer()
}
```

One sample of the VM, and what it needs of the last to measure the next.

# `cpu_meters`

```elixir
@spec cpu_meters(sample :: t()) :: map()
```

Options for `cpu-meters`: the schedulers as cores, memory in gigabytes
against the next half gigabyte up, the run queue's averages as the load,
the process count as tasks, uptime, and the busiest processes.

# `gauge`

```elixir
@spec gauge(sample :: t()) :: map()
```

Options for `gauge`: the schedulers' average use.

# `progress_bar`

```elixir
@spec progress_bar(sample :: t()) :: map()
```

Options for `progress-bar`: where the memory goes, in percent of it.

# `sample`

```elixir
@spec sample(prev :: t() | nil) :: t()
```

A sample of the VM, measured from `prev` (`nil` for the first, which
measures no scheduler use and no busiest processes yet).

# `sparkline`

```elixir
@spec sparkline(sample :: t(), opts :: [{:rate, number()}]) :: map()
```

Options for `sparkline`: memory in megabytes, the process count and the
run queue, a sample at a time over the last 120. `rate` is
samples a second, for its time axis (default 1).

---

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