swarmexec

swarmexec › Docs › TUI: inspect a service or task

TUI: inspect a service or task_

service inspect and task inspect, as a table you can move through.

Need the exact image digest a task runs, or the service spec in full? That is the raw json view of this overlay (3) — the same JSON docker service inspect prints, so there is no reason to leave the TUI for it. What else each tool is for: Next to docker.

The inspect overlay

i opens an inspect overlay for the node under the cursor — on a service it shows docker service inspect, and on a container leaf the swarm task inspect (the manager's view of that instance: state, slot, node, container id, container spec, resources and status history). Both come from the swarm manager. The overlay opens on a tabular, operator-first summary with sections ordered by operational relevance — networks, labels, volumes/mounts and secrets (and configs) first, then ports, image, mode, env, resources, placement and update policy (plus state, node and container id for a container/task), with ids and timestamps last. The overlay's first line, inside the border and pinned above the scrolling content, is a tab strip naming its three views — table 1   stats 2   raw json 3 — with the current one in the accent colour; it is the same shape as the main window's tab bar, a label followed by the digit that selects it. 1, 2 and 3 jump straight to table, stats and raw daemon JSON, and t still cycles table → stats → raw json and back. The footer hint is simply 1-3/t view, and the border title no longer repeats the current view's name — it just reads inspect service foo, because the strip already says where you are. Note this tabular view is the manager's task view, not a full node-local docker container inspect of the running container — a real container inspect via the agent is planned.

The stats view

The middle of the three is live resource usage — the same readings that mark the tree, so opening it costs no extra call and the numbers keep refreshing while it is open. It is a table, one row per container of the service (or the single container of a task inspect):

RESOURCE USAGE measured on each node, refreshed with the tree CONTAINER NODE HEALTH CPU MEMORY gl_gitlab.1 docker3v2 healthy 0.07 / 4.00 cores (2%) 6.823GiB / 8GiB (85%) limits are the container's own where it has one, otherwise the node's capacity

A table, because a bare percentage is not readable if you do not already know how the tool measures — 94% of what? Every cell carries its own units, so 0.07 / 4.00 cores needs no legend and the percentage sits next to the figure it is a percentage of; and several replicas are compared by scanning a column rather than by comparing stacked blocks. The HEALTH column words the verdict — healthy, unhealthy, starting, or none for a container that declares no healthcheck. none and healthy are deliberately different words rather than a word and a blank: no healthcheck configured and the probe passes are different facts, and a blank would read as the second. A container the agents did not report — unreachable node, an agent too old for the Stats RPC, or one started since the last reading — shows no reading in both resource columns rather than a zero, which would read as idle.

The last minutes

Under the table each container gets two sparklines, CPU and memory, over the last readings — so you can tell a service that stands at 90% from one that just shot up to 90%. Both use a fixed 0–100% scale of the same denominator as the table, so two containers' lines compare and an idle one stays flat. The history is kept in memory only, for at most 15 minutes, and readings keep arriving while the view is open. A blank is a stretch without readings — a node that did not answer, a cluster you were not looking at — never a drop to zero.

LAST MINUTES gl_gitlab.1 cpu ▁▁▂▂▁▁▃▇██▇▅▃▂▁ ▁▁▂▂▁▁▁ mem ▆▆▆▆▆▆▇▇▇▇▇▇▇▇▇ ▇▇▇▇▇▇▇ last 9 min share of each container's limit (or its node), oldest left; a blank is no reading, not zero

The footnote under the table names the denominator: the container's own limit where it has one, otherwise the node's capacity. That is the thing that makes a percentage mean something — 85% of an 8 GiB limit and 85% of a 64 GiB node are different conversations. Memory is shown in binary units (MiB/GiB), the same units the node detail uses and the same ones docker itself reports, so the same figure never reads differently in two places. With more than one measured container the view adds a roll-up under the table: CPU and memory of the worst replica — not an average, which hides the one container about to be OOM-killed — plus the total memory across them. The ? help overlay's t entry reads cycle table / stats / raw JSON accordingly.

Moving and copying

The overlay is navigable and selectable, not just a plain scroll: data lines are individually selectable and you move the cursor line by line with ↑/↓ or j/k (section headers and blank lines are skipped). y always copies the selected line to your clipboard over OSC52 — the same yank mechanism used elsewhere — so you can grab a single id, mount or address without selecting text by hand. Enter also copies, except on a collapsible NETWORKS row, where it instead expands/collapses that row (see below). All three views (the tabular summary, the stats view and the raw JSON, reached with 1–3 or cycled with t) are selectable and copyable line by line. A footer always lists the available keys, so what you can do is visible at a glance; for a service the footer also shows the edit keys.

KeyAction
↑ ↓ j kmove the selection between data lines (headers/blanks skipped)
ycopy the selected line to the clipboard (OSC52) — always
Enteron a collapsible NETWORKS row, expand/collapse that level — the rows nest two deep, a network and its N containers drill-down; on any other line, copy it (OSC52)
1 2 3select a view directly — 1 tabular summary, 2 stats (live CPU / memory, see above), 3 raw daemon JSON; these are the digits the tab strip shows
tcycle the three views — tabular summary → stats (live CPU / memory, see above) → raw daemon JSON → back; all three selectable, and the tab strip at the top marks the one you are in
aactions menu — every service editor and action in one list, each selectable by its letter or with Enter (service only; see edit a service)
u d s f ethe actions that also run directly — image version / diff / scale / force-update / env (service only; see edit a service). Every other action — the capitals D S R P and p l n v r — is reached through a, so a missed Shift cannot open the wrong editor
Xremove the service, behind a confirm (service only)
Esc q iclose the overlay

Networks

The NETWORKS section is collapsible, and it answers “which address is this reached at” before you expand anything: each attached network shows as a collapsed row + <network> 🔒 vip 10.0.5.2/24 (2 dns names). A 🔒 lock icon after the network name marks an encrypted overlay network (data-plane encryption, --opt encrypted); its absence means unencrypted. On a service inspect the address is labelled vip — the service's virtual IP on that network, the address the swarm load balancer answers on, taken from the manager's ServiceInspect (Endpoint.VirtualIPs). On a container/task inspect it is labelled addr: that container's own address there. A service in dnsrr endpoint mode has no VIP at all — that is by design, not missing data — so instead of a blank the expanded network carries the line no vip — dnsrr endpoint mode, the DNS name resolves to the containers. The ingress network is listed here too, even though no spec ever mentions it — swarm attaches the service to it by itself (see ingress). It is appended after the networks the spec declares, never interleaved with them, and its header reads + ingress vip 10.0.0.250/24 (routing mesh): the (routing mesh) note stands in for a dns-name count that could only ever say (0 dns names).

Move onto a network row and press Enter to expand or collapse it. Expanded, it lists the DNS names that resolve to the service/container on that network — the service name, tasks.<service> and any custom aliases — so you can see under which DNS name it is reached and which aliases it carries, per network. Below them sits a second collapsible row, + 2 containers (singularised, + 1 container), and Enter on that opens the deepest level: one column-aligned row per container, web.1 10.0.1.5/24 host-a — task name, its address on this network, and the node it runs on (replicated tasks are named <service>.<slot>, global ones <service>.<node>, having no slot).

What is listed is filtered on the task's desired state, not its current one — every task the manager still wants running appears, including ones that are only preparing, assigned or starting: they already hold their address, and during a rolling update that is most of them, so filtering on the current state would empty the drill-down exactly when it is most interesting. A task the manager has given up on — desired state shutdown, i.e. replaced by a rolling update, scaled away or failed — is not listed: its address has been released and may already belong to a different container, so showing it would be actively wrong. A task that is not serving traffic yet carries its state in brackets at the end of its row, web.1 10.0.1.5/24 host-a (starting); a running one has no suffix. The rows come from a manager-API TaskList filtered to the service and are best-effort — an API error just leaves the drill-down empty. The two levels collapse independently; collapsing the network hides the container level with it.

The ingress row

The ingress row is the one that is in no spec. Swarm joins a service to the ingress network on its own as soon as the service publishes a port in ingress mode, and that attachment appears nowhere in the service spec — yet its vip is the address the routing mesh actually answers on, which is the first thing you want when a published port misbehaves. So it gets a row of its own, appended after the networks the spec declares and shaped slightly differently. No service DNS name resolves on ingress, so where another network counts its names this header carries the note (routing mesh); expanded, the row lists instead the ingress-published ports that put the service there — the reason the row exists at all — one line each, published 2222 -> 22/tcp. Ports published in host mode bypass the routing mesh and are deliberately not listed there. Below them it drills down to the containers exactly like every other network row: the same + 1 container level, with each container's own address on the ingress network. A service that publishes no ingress port has no ingress VIP — and therefore no such row at all.

A GitLab service publishing SSH on 2222, both levels expanded:

- dbnet vip 10.0.1.137/24 (2 dns names) gl_gitlab tasks.gl_gitlab - 1 container gl_gitlab.1 10.0.1.54/24 docker3v2 - ingress vip 10.0.0.250/24 (routing mesh) published 2222 -> 22/tcp - 1 container gl_gitlab.1 10.0.0.64/24 docker3v2

Copying inside NETWORKS yields the address without its mask — 10.0.5.2, the form you paste into a curl or a ping: on a network row its vip/addr, on a container row that container's address. A network row that has no address (dnsrr) copies the network name, as before. On both kinds of collapsible row Enter toggles; on every other line it copies (and y always copies).

On a service the overlay also edits it: see edit a service.