335 lines
9.3 KiB
Groff
335 lines
9.3 KiB
Groff
.\" Manual page for dockertop. View with: man -l docs/dockertop.1
|
|
.TH DOCKERTOP 1 "October 2026" "dockertop 1.0.0" "User Commands"
|
|
.SH NAME
|
|
dockertop \- htop\-style view of Docker containers and the processes inside them
|
|
.SH SYNOPSIS
|
|
.B dockertop
|
|
[\fB\-d\fR \fISECONDS\fR] [\fB\-s\fR \fICOLUMN\fR] [\fB\-t\fR] [\fB\-r\fR] [\fICONTAINER\fR]
|
|
.br
|
|
.B dockertop
|
|
\fB\-\-version\fR
|
|
.SH DESCRIPTION
|
|
.B dockertop
|
|
is a full\-screen terminal monitor, laid out like
|
|
.BR htop (1),
|
|
for Docker. The main screen lists every container with its CPU, memory,
|
|
network and block I/O usage, process count and status. Selecting a container
|
|
and pressing \fBEnter\fR opens an htop\-like view of the processes running
|
|
inside it.
|
|
.PP
|
|
It talks to the Docker Engine API directly over the daemon socket, so the
|
|
.BR docker (1)
|
|
command line is not needed. Container figures come from the same statistics
|
|
as
|
|
.BR "docker stats" .
|
|
Process figures are read from
|
|
.IR /proc
|
|
on the host, using the host PIDs that the daemon reports.
|
|
.PP
|
|
Lifecycle actions (stop, start, restart, pause, signal) are bound to single
|
|
letter keys and always ask for confirmation first.
|
|
.SH OPTIONS
|
|
Every option overrides the value loaded from the configuration file.
|
|
.TP
|
|
.BI \-d " SECONDS"
|
|
Refresh interval. Fractions are allowed. Default 2.
|
|
.TP
|
|
.BI \-s " COLUMN"
|
|
Sort column of the container list, one of
|
|
.BR CPU ,
|
|
.BR MEM ,
|
|
.BR NET ,
|
|
.BR IO ,
|
|
.BR PIDS ,
|
|
.BR NAME ,
|
|
.BR IMAGE ,
|
|
.BR STATE .
|
|
Default \fBCPU\fR.
|
|
.TP
|
|
.B \-t
|
|
Start in tree view, containers grouped by compose project.
|
|
.TP
|
|
.B \-r
|
|
Show running containers only. By default stopped ones are listed too.
|
|
.TP
|
|
.I CONTAINER
|
|
A container name or ID prefix. dockertop opens straight into that
|
|
container's process view.
|
|
.TP
|
|
.B \-\-version
|
|
Print the version and exit.
|
|
.TP
|
|
.B \-h
|
|
Print a short usage message and exit.
|
|
.SH DISPLAY
|
|
.SS Header
|
|
.TP
|
|
.B CPU
|
|
CPU used by all containers together, out of every core on the host.
|
|
.TP
|
|
.B Mem
|
|
Memory used by all containers together, out of the host's RAM.
|
|
.TP
|
|
Containers
|
|
How many containers are running, paused, stopped or restarting, then the
|
|
Docker version, host name, operating system and cgroup version.
|
|
.TP
|
|
Net, Block
|
|
Network traffic and block I/O per second, summed over every container, and
|
|
the current sort order.
|
|
.SS Columns
|
|
.TP
|
|
.B NAME
|
|
Container name. In tree view, containers are indented under a summary row
|
|
for their compose project.
|
|
.TP
|
|
.B CPU%
|
|
CPU time per second of wall time, as a percentage of one core: 100 is one
|
|
full core, as in
|
|
.B htop
|
|
and
|
|
.BR "docker stats" .
|
|
Shown as \fB\-\fR until two samples have been taken.
|
|
.TP
|
|
.B MEM
|
|
Memory charged to the container's cgroup, minus inactive page cache, the
|
|
same figure
|
|
.B docker stats
|
|
shows.
|
|
.TP
|
|
.B MEM%
|
|
\fBMEM\fR as a share of the container's memory limit, or of host RAM when
|
|
it has none. Yellow from 50%, red from 90%.
|
|
.TP
|
|
.BR "NET RX" ", " "NET TX"
|
|
Bytes received and sent per second, over all of the container's networks.
|
|
.TP
|
|
.BR READ ", " WRITE
|
|
Block device bytes read and written per second.
|
|
.TP
|
|
.B PIDS
|
|
Number of tasks (processes and threads) in the container.
|
|
.TP
|
|
.B STATUS
|
|
Docker's status text. Red for unhealthy, dead or a non\-zero exit,
|
|
yellow for paused or a health check still starting, grey for stopped.
|
|
.TP
|
|
.B IMAGE
|
|
Image name, or the command after pressing \fBc\fR.
|
|
.SS Process view
|
|
.B Enter
|
|
on a container shows the processes in it, like
|
|
.BR htop .
|
|
The header has the container's CPU against its limit (or all cores), memory
|
|
against its limit, task, thread and running counts, the pids limit, network
|
|
and block I/O rates and uptime. The columns are:
|
|
.TP
|
|
.B PID
|
|
Process ID on the host (not inside the container's PID namespace).
|
|
.TP
|
|
.B USER
|
|
User name from the container's own
|
|
.IR /etc/passwd ,
|
|
read through
|
|
.IR /proc/PID/root .
|
|
That needs root; otherwise UID 0 shows as \fBroot\fR and other users by
|
|
number, because host user names would be wrong for container UIDs.
|
|
.TP
|
|
.BR PRI ", " NI
|
|
Kernel priority and nice value.
|
|
.TP
|
|
.BR VIRT ", " RES
|
|
Virtual size and resident memory.
|
|
.TP
|
|
.B S
|
|
State: R running, S sleeping, D uninterruptible (red), Z zombie, T stopped.
|
|
.TP
|
|
.B CPU%
|
|
Share of one core over the last refresh.
|
|
.TP
|
|
.B MEM%
|
|
Resident memory as a share of the container's memory limit.
|
|
.TP
|
|
.B TIME+
|
|
User plus system CPU time used.
|
|
.TP
|
|
.B Command
|
|
Process name, or the full command line after pressing \fBc\fR. Indented
|
|
under its parent in tree view.
|
|
.SS Details and logs
|
|
.B d
|
|
shows the container's configuration: image, command, user, state, health
|
|
and the last health check, limits, current usage and totals since start,
|
|
networks and published ports, mounts and labels. Environment variables are
|
|
hidden, since they often hold secrets; \fBe\fR shows them.
|
|
.PP
|
|
.B l
|
|
shows the last 2000 lines of the container's log, stdout and stderr,
|
|
refreshed every interval and following the end. Scrolling up stops
|
|
following; \fBEnd\fR resumes. Colour escapes are stripped.
|
|
.SH KEYS
|
|
.TP
|
|
.B Up, Down, PgUp, PgDn, Home, End
|
|
Move the selection, or scroll details and logs.
|
|
.TP
|
|
.B Left, Right
|
|
Pan long lines in details and logs.
|
|
.TP
|
|
.B Enter
|
|
Process view of the selected container.
|
|
.TP
|
|
.B Esc, q
|
|
Back to the previous screen. \fBq\fR on the container list quits.
|
|
.TP
|
|
.B h, ?
|
|
Help.
|
|
.TP
|
|
.B /
|
|
Incremental search: over name, ID, image, compose project and status in
|
|
the list; over command line, name, user and PID in the process view.
|
|
\fBEnter\fR keeps the filter, \fBEsc\fR clears it.
|
|
.TP
|
|
.B N, C, M
|
|
Sort by name (command in the process view), CPU or memory.
|
|
.TP
|
|
.B s
|
|
Cycle the sort column. The process view sorts by
|
|
.BR CPU ,
|
|
.BR MEM ,
|
|
.BR TIME ,
|
|
.BR PID ,
|
|
.B USER
|
|
or
|
|
.BR COMMAND .
|
|
.TP
|
|
.B t
|
|
Toggle tree view: compose projects in the list, the process tree in the
|
|
process view.
|
|
.TP
|
|
.B a
|
|
Toggle showing stopped containers.
|
|
.TP
|
|
.B c
|
|
Toggle image or command in the list, process name or full command line in
|
|
the process view.
|
|
.TP
|
|
.B d
|
|
Details of the selected container.
|
|
.TP
|
|
.B l
|
|
Logs of the selected container.
|
|
.TP
|
|
.B e
|
|
Show or hide environment variables in the details view.
|
|
.TP
|
|
.B Ctrl\-C
|
|
Quit at once.
|
|
.SH ACTIONS
|
|
Each action asks for confirmation before doing anything. In the process
|
|
view, container actions apply to the container being viewed. Summary rows
|
|
of compose projects take no actions.
|
|
.TP
|
|
.B x \(em stop or start
|
|
Stops a running or paused container (SIGTERM, then SIGKILL once the
|
|
container's stop timeout, 10 seconds by default, has passed), or starts a
|
|
stopped one.
|
|
.TP
|
|
.B r \(em restart
|
|
Stops and starts the container.
|
|
.TP
|
|
.B p \(em pause
|
|
Freezes every process in the container with the cgroup freezer, or thaws a
|
|
paused one.
|
|
.TP
|
|
.B k \(em signal
|
|
Opens a picker of common signals (TERM, KILL, INT, HUP, QUIT, USR1, USR2,
|
|
STOP, CONT). In the list the signal goes to the container's main process
|
|
through the daemon. In the process view it goes to the selected process
|
|
directly, with
|
|
.BR kill (2),
|
|
which needs permission over that process: usually root.
|
|
.SH PERMISSIONS
|
|
dockertop needs the Docker socket, so its user must be root or in the
|
|
\fBdocker\fR group. Membership of that group is equivalent to root on the
|
|
host.
|
|
.PP
|
|
Everything else works without root, except the container's own user names
|
|
and signalling processes in the process view.
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B DOCKER_HOST
|
|
Daemon address, \fBunix://\fR\fIPATH\fR (default
|
|
\fIunix:///var/run/docker.sock\fR) or \fBtcp://\fR\fIHOST\fR:\fIPORT\fR.
|
|
TLS is not supported: when \fBDOCKER_TLS_VERIFY\fR is set dockertop refuses
|
|
to start. Forward the socket over
|
|
.BR ssh (1)
|
|
instead. Docker contexts are not read; set \fBDOCKER_HOST\fR.
|
|
.PP
|
|
With a remote daemon the container list works as usual, but the host PIDs
|
|
are not in the local
|
|
.IR /proc .
|
|
The process view then shows the daemon's own
|
|
.B ps
|
|
output, in which CPU% is a lifetime average, and processes cannot be
|
|
signalled.
|
|
.TP
|
|
.B XDG_CONFIG_HOME
|
|
Where the configuration lives, see
|
|
.BR FILES .
|
|
.SH CONFIGURATION
|
|
Settings are read from the file below at start\-up and written back when
|
|
.B dockertop
|
|
exits, so the sort orders, tree views, stopped\-container filter,
|
|
command\-line display and refresh interval persist between runs. The file
|
|
holds one
|
|
.I key = value
|
|
per line and may be edited by hand:
|
|
.PP
|
|
.nf
|
|
sort = CPU # container list, see \-s
|
|
proc_sort = CPU # process view
|
|
all = true # false lists running containers only
|
|
tree = false # group by compose project
|
|
proc_tree = false # process tree
|
|
full_cmd = false
|
|
refresh = 2 # seconds
|
|
.fi
|
|
.SH FILES
|
|
.TP
|
|
.I $XDG_CONFIG_HOME/dockertop/config
|
|
Configuration, normally
|
|
.IR ~/.config/dockertop/config .
|
|
When run under
|
|
.BR sudo (8)
|
|
this is root's home unless \fBXDG_CONFIG_HOME\fR is passed through.
|
|
.TP
|
|
.I /var/run/docker.sock
|
|
The Docker daemon socket.
|
|
.TP
|
|
.IR /proc/PID/stat ", " /proc/PID/status ", " /proc/PID/cmdline ", " /proc/PID/cgroup
|
|
Process figures for the process view. See
|
|
.BR proc (5).
|
|
.SH EXIT STATUS
|
|
0 on a normal quit, 1 if the daemon cannot be reached or the terminal cannot
|
|
be initialised, 2 on a bad option.
|
|
.SH NOTES
|
|
Statistics for every running container are requested in parallel on each
|
|
refresh. With hundreds of containers a longer interval (\fB\-d 5\fR) eases
|
|
the load on the daemon.
|
|
.PP
|
|
Block I/O counts every device the kernel charges, so I/O through RAID or
|
|
device\-mapper may be counted on each layer, as in
|
|
.BR "docker stats" .
|
|
.SH SEE ALSO
|
|
.BR htop (1),
|
|
.BR docker (1),
|
|
.BR docker\-stats (1),
|
|
.BR docker\-top (1),
|
|
.BR swaptop (1),
|
|
.BR proc (5),
|
|
.BR cgroups (7)
|
|
.SH AUTHOR
|
|
Andy Dixon <andy@dixon.cx>, https://www.dixon.cx
|
|
.SH BUGS
|
|
Report at https://github.com/andydixon/dockertop/issues
|