ctop is a new command line based tool available to monitor the processes at the container level. Containers provide operating system level virtualization environment by making use of the cgroups resource management functionality. This tool collects data related to memory, cpu, block IO and metadata like owner, uptime etc from cgroups and presents it in a user readable format so that one can quickly asses the overall health of the system. Based on the data collected, it tries to guess the underlying container technology. ctop is useful in detecting who is using large amounts of memory under low memory situations.
Some of the capabilities of ctop are:
Collect metrics for cpu, memory and blkio
Gather information regarding owner, container technology, task count
Sort the information using any column
Display the information using tree view
Fold/unfold cgroup tree
Select and follow a cgroup/container
Select a timeframe for refreshing the displayed data
Pause the refreshing of data
Detect containers that are based on systemd, Docker and LXC
Advance features for Docker and LXC based containers
open / attach a shell for further diagnosis
stop / kill container types
How to Install CTOP
ctop is written using Python and there are no other external dependencies other than having to use Python version 2.6 or greater (with built-in cursor support). Installation using Python's pip is the recommended method. Install pip if not already done and install ctop using pip.
Note: The examples shown in this article are from an Ubuntu (14.10) system
$ sudo apt-get install python-pip
Installing ctop using pip:
poornima@poornima-Lenovo:~$ sudo pip install ctop[sudo] password for poornima:
Running setup.py (path:/tmp/pip_build_root/ctop/setup.py) egg_info for package ctop
Installing collected packages: ctop
Running setup.py install for ctop
changing mode of build/scripts-2.7/ctop from 644 to 755
changing mode of /usr/local/bin/ctop to 755
Successfully installed ctop
If using pip is not an option, you can also install it directly from the github using wget:
poornima@poornima-Lenovo:~$ wget https://raw.githubusercontent.com/yadutaf/ctop/master/cgroup_top.py -O ctop
--2015-04-29 19:32:53-- https://raw.githubusercontent.com/yadutaf/ctop/master/cgroup_top.py
Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 18.104.22.168
Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|22.214.171.124|:443... connected.
HTTP request sent, awaiting response... 200 OK Length: 27314 (27K) [text/plain]
Saving to: ctop
100%[======================================>] 27,314 --.-K/s in 0s
2015-04-29 19:32:59 (61.0 MB/s) - ctop saved [27314/27314]
poornima@poornima-Lenovo:~$ chmod +x ctop
You might get an error message while launching ctop if cgroup-bin package is not installed. It can be resolved by installing the required package.
poornima@poornima-Lenovo:~$ ./ctop[ERROR] Failed to locate cgroup mountpoints.
poornima@poornima-Lenovo:~$ sudo apt-get install cgroup-bin
Here is a sample output screen of ctop:
ctop [--tree] [--refresh=] [--columns=] [--sort-col=] [--follow=] [--fold=, ...] ctop (-h | --help)
Once you are inside the ctop screen, use the up (↑) and down(↓) arrow keys to navigate between containers. Clicking on any container will select that particular container. Pressing q or Ctrl+C quits the container.
Let us now take a look at how to use each of the options listed above.
-h / --help - Show the help screen
poornima@poornima-Lenovo:~$ ctop -h
Usage: ctop [options]
-h, --help show this help message and exit
--tree show tree view by default
--refresh=REFRESH Refresh display every <seconds>
--follow=FOLLOW Follow cgroup path
--columns=COLUMNS List of optional columns to display. Always includes
--sort-col=SORT_COL Select column to sort by initially. Can be changed
--tree - Display tree view of the containers
By default, list view is displayed
Once you are inside the ctop window, you can use the F5 button to toggle tree / list view.
--fold=<name> - Fold the <name> cgroup path in the tree view.
This option needs to be used in combination with --tree.
Eg: ctop --tree --fold=/user.slice
Inside the ctop window, use the + / - keys to toggle child cgroup folding.
Note: At the time of writing this article, pip repository did not have the latest version of ctop which supports '--fold' option via command line.
--follow= - Follow/Highlight the cgroup path.
Eg: ctop --follow=/user.slice/user-1000.slice
As you can see in the screen below, the cgroup with the given path "/user.slice/user-1000.slice" gets highlighted and makes it easier for the user to follow it even when the display position gets changed.
You can also use the 'f' button to allow the highlighted line to follow the selected container. By default, follow is off.
--refresh= - Refresh the display at the given rate. Default 1 sec
This is useful in changing the refresh rate of the display as per user requirement. Use the 'p' button to pause the refresh and select the text.
--columns=<columns> - Can limit the display to selected <columns>. 'name' should be the first entry followed by other columns. By default, the columns include owner, processes,memory, cpu-sys, cpu-user, blkio, cpu-time.
Eg: ctop --columns=name,owner,type,memory
-sort-col=<sort-col> - column using which the displayed data should be sorted. By default it is sorted using cpu-user
Eg: ctop --sort-col=blkio
If there are additional containers supported like Docker and LXC, following options will also be available:
press 'a' - attach to console output
press 'e' - open a shell in the container context
press 's' – stop the container (SIGTERM)
press 'k' - kill the container (SIGKILL)
Python version of ctop is currently in active development by Jean-Tiare Le Bigot. Hopefully we would see more features in this tool like our native top command :-).
**Updating article on 2017-03-12**
Ctop Tool written in Golang
We found another interesting tool named same ctop itself written in go lang to view and monitor container's real time metrics in the terminal. It also provides a concise and condensed overview of real-time metrics from multiple containers. We covered its usages in a linux based docker host.
ctop currently comes with built-in support for Docker; connectors for other container and cluster systems are planned for future releases. Fetch the latest version of ctop and move it to any location pointed by PATH environment variable.
# wget https://github.com/bcicen/ctop/releases/download/v0.4/ctop-0.4-linux-amd64 -O ctop
# sudo mv ctop /usr/local/bin/
# sudo chmod +x /usr/local/bin/ctop
Thats all, you are now ready to view the container metrics in your terminal.
Usages of ctop monitoring tool
ctop does not require any arguments to run and will configure itself using the DOCKER_HOST environment variable. To run it simply type ctop in the shell.
Once you have executed the above command, all the container will be listed with their Name, Container ID, CPU usages, Memory usages and Network traffic.
Using the following key-bindings, you can manage the ctop screen.
|a||Toggle display of all (running and non-running) containers|
|f||Filter displayed containers|
|H||Toggle ctop header|
|h||Open help dialog|
|s||Select container sort field|
|r||Reverse container sort order|
Run ctop from shell, you can view all the containers (running/stopped) with their ID, CPU usages, memory usages and received/transmitted data.
Press 'f' to filter the view and type a letter/word. For this example, we will type 'g' to filter all the containers whose name start with 'g'
Once you have filtered the view, using backspace, clear the filter box and press enter, you will be taken to ctop main view. For help, press 'h'. Press
'ESC' to go back to main view.
Press 'H' to toggle ctop header
To select the sort field for ctop main view press 's' and select the field and press enter.
For expanded view, select the container using up/down arrow key in the ctop main view and press enter. You will be able to view the selected containers metrics in details.
There you have it - Monitor the container from the shell and view few basic parameters through it. Although not robust, but the developers have planned few enhancements like graph in the future releases.