NAME

cowdiag - live diagnostics dashboard for cow and River

SYNOPSIS

cowdiag [-hv] [-i milliseconds]

cowdiag -j [-w] [-i milliseconds]

DESCRIPTION

cowdiag is a read-only terminal dashboard for cow(1). It combines CoW's status snapshot with internal manage/render timing counters and process statistics for CoW and River.

The timing panels distinguish work performed inside CoW callbacks from time spent waiting at the CoW/River protocol boundary. They do not measure River's GPU rendering or frame presentation time.

The interactive display adapts to the terminal width. Wide terminals show process, session, manage, render, and rolling-history panels. Narrow terminals use a compact layout.

OPTIONS

-h

Print usage and exit.

-i milliseconds

Set the sampling interval. The default is 1000 milliseconds. Values from 100 through 60000 are accepted.

-j

Emit one combined JSON sample instead of opening the terminal dashboard. The command waits for one sampling interval so CPU percentages are based on two observations.

-v

Print the version and exit.

-w

With -j, continue emitting newline-delimited JSON samples until interrupted.

KEYS

q, Escape

Quit.

Space

Pause or resume sampling.

Clear the local graph history. CoW's process-lifetime counters are not changed.

Tab, Left, Right, 1 through 4

Select the line graph: combined CoW and River CPU, CoW RSS, manage wait, or render wait.

Toggle an expanded graph-only view. This also makes the graph available in narrow terminals where the normal stacked layout has no graph panel.

Show or hide key help.

METRICS

The manage panel reports:

•requests registered by CoW and requests coalesced into the same cycle;

•delay from the first pending request to River's manage_start event; and

•time spent by CoW handling a manage cycle.

The render panel reports:

•delay from CoW's manage_finish request to River's next render_start; and

•time spent by CoW handling a render cycle.

CoW CPU time, process lifetime, and peak resident memory are portable. cowdiag also shows current CoW and River RSS and River CPU usage on Linux, FreeBSD, OpenBSD, and NetBSD. Linux uses procfs; the BSD implementations use their native process sysctl interfaces. River is identified from the peer credentials of the Wayland socket. Unsupported process fields are displayed as n/a on other systems. CPU percentages use a per-core scale: one fully occupied CPU is 100 percent.

ENVIRONMENT

XDG_RUNTIME_DIR

Used to locate CoW's command and status sockets.

WAYLAND_DISPLAY

Selects the CoW instance and identifies the River process.

COW_IPC_SOCKET, COW_STATUS_SOCKET

Override the normal command and status socket paths.