TUI reference

The terminal UI shows a live, line-oriented view of one BEAM node. Type a shortcut and press Enter; an empty line means Enter by itself.

Quick start

Build the escript, then use the explicit tui command. This example uses the cookie already available to the controller:

rebar3 escriptize
./_build/default/bin/observer_cli tui app@host

Press D for the built-in shortcut page and q to quit. The old bare observer_cli NODE [COOKIE REFRESH_MS] form is not supported.

Start forms

From the generated escript:

observer_cli tui NODE [COOKIE REFRESH_MS]

REFRESH_MS defaults to 1500 and must be at least 1000. Supplying a cookie also requires the refresh value. The escript starts a hidden controller, loads a compatible TUI bundle into the target when needed, and starts the UI there. Auto-load requires the controller and target to use the same OTP major release; a compatible bundle already installed on the target is used without auto-load.

From an Erlang shell:

observer_cli:start().
observer_cli:start(2000).
observer_cli:start(RemoteNode).
observer_cli:start(RemoteNode, Cookie).
observer_cli:start(RemoteNode, [{cookie, Cookie}, {interval, 2000}]).

The integer form sets the refresh interval for most local pages; App keeps its default. The options form is for a remote node.

Main pages

flowchart TB
    NAV["Main pages · global shortcuts<br/>H Home · N Network · O Ports · K Sockets · S System<br/>E ETS · M Mnesia · A App · D Doc · P Plugins"]

    PICK_PROCESS["Choose a process<br/>Home ranking · plugin PID row"]
    PICK_PORT["Choose a port<br/>Network row · Ports row"]
    PICK_SOCKET["Choose a socket<br/>Sockets row"]

    PROCESS["Process detail<br/>Return: H · B to source page"]
    PORT["Port detail<br/>Return: N · O · H"]
    SOCKET["Socket detail<br/>Return: K · H"]

    NAV --> PICK_PROCESS --> PROCESS
    NAV --> PICK_PORT --> PORT
    NAV --> PICK_SOCKET --> SOCKET

The diagram separates two navigation mechanisms: global shortcuts among peer main pages, then context-specific row drill-down. Pages without a row-detail transition appear only in the global shortcut set. The tables below are authoritative for all shortcuts and behavior.

The Home, Network, Ports, Sockets, ETS, Mnesia, App, and Plugin lists use terminal height to choose the visible row count. If terminal geometry is unavailable, default_row_size defaults to 30 rows.

How to read values

The field tables below describe the labels rendered by the current TUI. The Source column identifies the source API and key where the value is fixed. Relevant API references are the Erlang/OTP erlang, persistent_term, inet, socket, ets, and mnesia modules, plus recon and recon_alloc.

• Values passed through the byte formatter use B, KiB, MiB, or GiB. Byte-valued exceptions rendered as raw integers, plus raw counts and words, are identified below.
• A total is cumulative for the VM or resource. An increment or delta is the current sample minus the preceding sample; it is not a per-second rate.
• A Recon count is a point-in-time ranking. A Recon window is the difference between two samples separated by the configured interval.
• dead means that a resource disappeared. unavailable means a required capability is missing. undefined marks an unsupported or absent property. - can represent an empty state or an endpoint that is not connected. Socket counters and options can vary with the OTP release, operating system, domain, type, and protocol.

Shared input

Most built-in main and list pages use the shared input parser below. A page ignores actions it does not implement; detail and plugin views document their own inputs later in this reference.

Pages that accept interval changes retain their own value while you navigate.

Home

The Home ranking has two collection modes:

• count mode calls recon:proc_count/2 once per refresh;
• window mode calls recon:proc_window/3 for the configured interval.

The first redraw after entering a window mode still uses proc_count; later redraws use proc_window.

Enabling scheduler utilization changes the node-wide scheduler_wall_time system flag while the view is active. observer_cli restores the preceding setting when it cleans up the Home view.

VM and OS fields

ps fields display -- when observer_cli cannot parse the command output.

Memory, IO, and GC fields

Scheduler utilization

Each scheduler row shows its scheduler ID and active-time percentage between two statistics(scheduler_wall_time) samples. The rows cover the normal and dirty CPU scheduler IDs returned by OTP, not dirty IO schedulers. observer_cli uses recon_lib:scheduler_usage_diff/2; values at or above 80% are red.

Top-N process fields

Only the selected ranking field uses the count or window value. The companion Memory, Reductions, and MsgQueue columns are current point-in-time reads. Window changes are second sample minus first and can be negative. A process present in only one sample retains that sample's absolute value. A reduction is a VM scheduling work unit, not elapsed CPU time.

Network

The page also displays VM input/output deltas from erlang:statistics(io). Ranked rows cover legacy inet Ports, not every host connection or the OTP socket registry.

Displayed fields

The first iw redraw uses count mode; later redraws use the configured window. For Ports present in both samples, all ranked metric columns use deltas from the same window. A Port present in only one sample retains that sample's absolute values. One-direction modes remain sorted by the selected direction. Port input and output totals appear under their matching headings.

Ports

The Ports page excludes inet Ports already represented on Network.

In Port detail, H opens Home, N opens Network, O returns to Ports, P keeps the current detail, and an integer at least 1000 changes the refresh interval.

Ports list fields

The list is a current snapshot of erlang:ports/0 and excludes Ports whose name or control name is tcp_inet, udp_inet, or sctp_inet.

Port detail fields

Legacy-inet detail adds current statistics from inet:getstat/1 through Recon. Transfer counters and packet-size aggregates are cumulative; send_pend is a current gauge.

The Options block attempts a fixed inet:getopts/2 allowlist: active, broadcast, buffer, bind_to_device, delay_send, deliver, dontroute, exit_on_close, header, high_msgq_watermark, high_watermark, low_msgq_watermark, low_watermark, ipv6_v6only, keepalive, linger, mode, netns, nodelay, packet, packet_size, priority, read_packets, recbuf, reuseaddr, send-timeout options send_timeout and send_timeout_close, show_econnreset, sndbuf, tos, and tclass. Unsupported options are shown explicitly.

Sockets

The Sockets page reads the OTP socket registry. A missing socket API produces an unavailable state.

A row number opens socket detail; K returns to the Sockets list. Counter sorting uses deltas after the first refresh. Identity sorting uses current metadata.

General socket fields

The General block comes from socket:info/0, with num_sockets and num_monitors taken from socket:number_of/0 and socket:number_of_monitors().

The page enumerates socket:which_sockets/0; sockets created with registry use disabled are not included.

Socket list fields

Counter decreases are clamped to zero. Sorting by ac uses acc_success + acc_tries, while the visible acceptance value in Pkt/Acc is acc_success only. Changing the sort, interval, or page restarts the list worker, so the next redraw again shows cumulative counters before later redraws become deltas.

Socket detail fields

read_byte, write_byte, read_pkg_max, and write_pkg_max are byte-formatted; the other preferred counters are counts. Additional runtime counters follow alphabetically. Unsupported, disconnected, and unimplemented options are identified rather than omitted.

System

The System page is a current snapshot. Its refresh interval controls redraw; the page does not calculate interval deltas.

Runtime, OS, and memory fields

System Processes and Atoms use the allocated-memory keys processes and atom; Home deliberately uses the used-memory keys processes_used and atom_used.

Runtime statistics and limits

Allocator fields

Rows cover binary_alloc, driver_alloc, eheap_alloc, ets_alloc, fix_alloc, ll_alloc, sl_alloc, std_alloc, and temp_alloc.

Distribution fields

On supported OTP 26–29 releases, the fourth dist_get_stat/1 value is pending output packets. It is not an output-queue byte count, even though the TUI compares it with dist_buf_busy_limit. Disabled distribution and no connected nodes produce explicit sentinel rows.

Allocator cache fields

ETS and Mnesia

Both table pages accept:

Mnesia also accepts hide to toggle system tables. These views report metadata only; they do not read table contents.

ETS fields

All values are current ets:all/0 and ets:info/1 metadata.

If a table disappears between enumeration and metadata collection, the current renderer can fail that redraw. Sorting uses raw memory words or object count.

Mnesia fields

The schema table is always hidden; hide toggles an additional fixed list of legacy system tables. OTP reports memory in words for ram_copies and disc_copies, but in bytes for disc_only_copies; only the word-valued forms are multiplied by VM word size.

App

The App page aggregates process resources by application.

Displayed fields

Processes are associated through application group leaders. All values and sorts are current snapshots; the page does not calculate interval deltas.

Process detail

Home rows and plugin PID rows without a configured handler open Process detail.

H returns Home. B returns to the source page: Home or the plugin sheet. An integer at least 1000 changes the detail refresh interval. State is a static capture in the built-in pager.

Process Info fields

The primary view requests only the displayed process_info/2 fields; it does not fetch the process dictionary or current stacktrace in the background.

Process status is one of the states returned by OTP, including exiting, waiting, running, runnable, garbage_collecting, or suspended. Links(N), Monitors(N), and MonitoredBy(N) show the full relationship counts and at most the first 30 values. Links are bidirectional process/Port links; Monitors are monitors created by the process; MonitoredBy lists entities monitoring it. The Reductions and Memory histories hold up to 20 point-in-time samples; reductions are cumulative and memory is current bytes.

Other process views

Messages, Dictionary, and State are collected and formatted in a monitored worker on the observed node. The worker has a five-second deadline and a 512 * 1024-word heap cap that includes shared binaries. Terms are refused above 64 KiB of external representation or structural depth 32. Formatter output is refused when the final rendered detail, including view prefixes, exceeds 65,536 characters or 64 KiB of UTF-8; every refusal displays too_large. These limits bound the helper and retained output, but the VM can still do transient work while copying a requested term, and a delivered system_get_state request can outlive its caller timeout.

Pager input is:

When B is reserved for returning to a plugin, use k for the previous pager page.

Plugin page

Application configuration supplies the Plugin menu and column shortcuts. Built-in input is:

See TUI plugins for callback, configuration, sorting, pagination, row-handler, and formatter contracts.

Redraw behavior

Main views clear the screen once, then redraw from the cursor origin without accumulating output. A view schedules its next refresh after collection. Window modes first sample for the configured interval, so collection and rendering add to the wall-clock cycle.

Home pause stops collection until resumed. Process state does not auto-refresh. Port and socket detail views render a dead or unavailable state when the selected resource disappears. Process detail renders a dead notice, but a shorter redraw can leave older rows visible.