path: root/docs/glances-doc.rst

=======
Glances
=======

This manual describes *Glances* version 2.4.2.

Copyright © 2011-2015 Nicolas Hennion <nicolas@nicolargo.com>

May 2015

.. contents:: Table of Contents

Introduction
============

Glances is a cross-platform curses-based system monitoring tool which
aims to present a maximum of information in a minimum of space, ideally
to fit in a classical 80x24 terminal or higher to have additional
information. It can adapt dynamically the displayed information depending
on the terminal size.

Glances can also work in client/server mode. Remote monitoring could be
done via terminal or web interface.

Glances is written in Python and uses the `psutil`_ library to get
information from your system.

Console (80x24)

.. image:: images/screenshot.png

Full view (>80x24)

.. image:: images/screenshot-wide.png

Web interface (Firefox)

.. image:: images/screenshot-web.png

Usage
=====

Standalone Mode
---------------

Simply run:

.. code-block:: console

    $ glances

Client/Server Mode
------------------

If you want to remotely monitor a machine, called ``server``, from
another one, called ``client``, just run on the server:

.. code-block:: console

    server$ glances -s

and on the client:

.. code-block:: console

    client$ glances -c @server

where ``@server`` is the IP address or hostname of the server.

Glances can centralize available Glances servers using the ``--browser``
option. The server list can be statically defined in the Glances
configuration file (section ``[serverlist]``).

Glances can also detect and display all Glances servers available on your
network (auto-discover mode is based on the the ``zeroconf`` protocol,
which is only available on GNU/Linux and OS X):

.. code-block:: console

    client$ glances --browser

It is possible to disable the auto discover mode ``--disable-autodiscover``.

In server mode, you can set the bind address ``-B ADDRESS`` and listening
TCP port ``-p PORT``.

In client mode, you can set the TCP port of the server ``-p PORT``.

You can set a password to access to the server ``--password``.

Default binding address is ``0.0.0.0`` (Glances will listen on all the
available network interfaces) and TCP port is ``61209``.

In client/server mode, limits are set by the server side.

Glances is ``IPv6`` compatible. Just use the ``-B ::`` option to bind to
all IPv6 addresses.

As an experimental feature, if Glances server is not detected by the
client, the latter will try to grab stats using the ``SNMP`` protocol:

.. code-block:: console

    client$ glances -c @snmpserver

*Note*: stats grabbed by SNMP request are limited (OS dependent).

Web Server Mode
---------------

If you want to remotely monitor a machine, called ``server``, from any
device with a web browser, just run the server with the ``-w`` option:

.. code-block:: console

    server$ glances -w

and on the client enter the following URL in your favorite web browser:

::

    http://@server:61208

where ``@server`` is the IP address or hostname of the server.

To change the refresh rate of the page, just add the period in seconds
at the end of the URL. For example, to refresh the page every 10s:

::

    http://@server:61208/10

The Glances web interface follows responsive web design principles.

Screenshot from Chrome on Android

.. image:: images/screenshot-web2.png

Command Reference
=================

Command-Line Options
--------------------

  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -d, --debug           enable debug mode
  -C CONF_FILE, --config CONF_FILE
                        path to the configuration file
  --disable-network     disable network module
  --disable-ip          disable IP module
  --disable-diskio      disable disk I/O module
  --disable-fs          disable file system module
  --disable-sensors     disable sensors module
  --disable-hddtemp     disable hddtemp module
  --disable-raid        disable RAID module
  --disable-docker      disable Docker module
  --disable-left-sidebar
                        disable network, disk I/O, file system and
                        sensors modules (py3sensors needed)
  --disable-process     disable process module
  --disable-log         disable log module
  --disable-quicklook   disable quick look module
  --disable-bold        disable bold mode in the terminal
  --enable-process-extended
                        enable extended stats on top process
  --enable-history      enable the history mode (matplotlib needed)
  --path-history PATH_HISTORY
                        set the export path for graph history
  --export-csv EXPORT_CSV
                        export stats to a CSV file
  --export-influxdb     export stats to an InfluxDB server (influxdb needed)
  --export-statsd       export stats to a StatsD server (statsd needed)
  --export-rabbitmq     export stats to a RabbitMQ server (pika needed)
  -c CLIENT, --client CLIENT
                        connect to a Glances server by IPv4/IPv6 address or
                        hostname
  -s, --server          run Glances in server mode
  --browser             start the client browser (list of Glances servers)
  --disable-autodiscover
                        disable autodiscover feature
  -p PORT, --port PORT  define the client/server TCP port [default: 61209]
  -B BIND_ADDRESS, --bind BIND_ADDRESS
                        bind server to the given IPv4/IPv6 address or hostname
  --password            define a client/server password
  --snmp-community SNMP_COMMUNITY
                        SNMP community
  --snmp-port SNMP_PORT
                        SNMP port
  --snmp-version SNMP_VERSION
                        SNMP version (1, 2c or 3)
  --snmp-user SNMP_USER
                        SNMP username (only for SNMPv3)
  --snmp-auth SNMP_AUTH
                        SNMP authentication key (only for SNMPv3)
  --snmp-force          force SNMP mode
  -t TIME, --time TIME  set refresh time in seconds [default: 3 sec]
  -w, --webserver       run Glances in web server mode (bottle needed)
  -q, --quiet           do not display the curses interface
  -f PROCESS_FILTER, --process-filter PROCESS_FILTER
                        set the process filter pattern (regular expression)
  --process-short-name  force short name for processes name
  --hide-kernel-threads
                        hide kernel threads in process list
  --tree                display processes as a tree
  -b, --byte            display network rate in byte per second
  -1, --percpu          start Glances in per CPU mode
  --fs-free-space       display file system free space instead of used
  --theme-white         optimize display colors for white background

Interactive Commands
--------------------

The following commands (key pressed) are supported while in Glances:

``ENTER``
    Set the process filter
    Filter is a regular expression pattern:

    - gnome: all processes starting with the gnome string
    - .*gnome.*: all processes containing the gnome string
``a``
    Sort process list automatically

    - If CPU iowait ``>60%``, sort processes by I/O read and write
    - If CPU ``>70%``, sort processes by CPU usage
    - If MEM ``>70%``, sort processes by memory usage
``b``
    Switch between bit/s or Byte/s for network I/O
``c``
    Sort processes by CPU usage
``d``
    Show/hide disk I/O stats
``e``
    Enable/disable top extended stats
``f``
    Show/hide file system stats
``F``
    Switch between file system used and free space
``g``
    Generate graphs for current history
``h``
    Show/hide the help screen
``i``
    Sort processes by I/O rate
``l``
    Show/hide log messages
``m``
    Sort processes by MEM usage
``n``
    Show/hide network stats
``p``
    Sort processes by name
``q`` or ``ESC``
    Quit the current Glances session
``r``
    Reset history
``s``
    Show/hide sensors stats
``t``
    Sort process by CPU times (TIME+)
``T``
    View network I/O as combination
``u``
    Sort processes by USER
``U``
    View cumulative network I/O
``w``
    Delete finished warning log messages
``x``
    Delete finished warning and critical log messages
``z``
    Show/hide processes stats
``1``
    Switch between global CPU and per-CPU stats
``2``
    Enable/disable left sidebar
``3``
    Enable/disable the quick look module
``/``
    Switch between short name / command line (processes name)

In the Glances client browser (accessible through the ``--browser``
command line argument):

``ENTER``
    Run Glances client to the selected server
``UP``
    Up in the servers list
``DOWN``
    Down in the servers list
``q`` or ``ESC``
    Quit Glances

Configuration
=============

No configuration file is mandatory to use Glances.

Furthermore a configuration file is needed to modify limit alerts, to
set up monitored processes list, to hide disks or network interfaces or
to define alias.

Location
--------

You can put the configuration file ``glances.conf`` in the following
locations:

:Linux: ``~/.config/glances, /etc/glances``
:\*BSD: ``~/.config/glances, /usr/local/etc/glances``
:OS X: ``~/Library/Application Support/glances, /usr/local/etc/glances``
:Windows: ``%APPDATA%\glances``

On Windows XP, the ``%APPDATA%`` path is:

::

    C:\Documents and Settings\<User>\Application Data

Since Windows Vista and newer versions:

::

    C:\Users\<User>\AppData\Roaming

User-specific options override system-wide options and options given on
the command line override either.

Syntax
------

Each plugin and export module can have a section.

Example for the CPU plugin:

.. code-block::

    [cpu]
    user_careful=50
    user_warning=70
    user_critical=90
    iowait_careful=50
    iowait_warning=70
    iowait_critical=90
    system_careful=50
    system_warning=70
    system_critical=90
    steal_careful=50
    steal_warning=70
    steal_critical=90

By default the ``steal`` CPU time alerts aren't logged. If you want to
enable log/alert, just add:

.. code-block::

    steal_log=True

Logs and debug mode
===================

Glances logs all its internal messages to a log file. By default, only
INFO & WARNING & ERROR &CRITICAL levels are logged, but DEBUG messages
can ben logged using the -d option on the command line.

By default, the log file is under:

:Linux, \*BSD, OS X: ``/tmp/glances.log``
:Windows: ``%APPDATA%\Local\temp\glances.log``

If ``glances.log`` is not writable, a new file will be created and
returned to the user console.

Anatomy Of The Application
==========================

Legend
------

| ``GREEN`` stat counter is ``"OK"``
| ``BLUE`` stat counter is ``"CAREFUL"``
| ``MAGENTA`` stat counter is ``"WARNING"``
| ``RED`` stat counter is ``"CRITICAL"``

*Note*: only stats with colored background will be logged in the alert
view.

Header
------

.. image:: images/header.png

The header shows the hostname, OS name, release version, platform
architecture and system uptime (on the upper right corner).
Additionally, on GNU/Linux, it also shows the kernel version.

In client mode, the server connection status is displayed.

Connected:

.. image:: images/connected.png

Disconnected:

.. image:: images/disconnected.png

QuickLook
---------

The ``quicklook`` plugin is only displayed on wide screen and propose a
bar view for CPU and memory (virtual and swap).

.. image:: images/quicklook.png

*Note*: limit values can be overwritten in the configuration file under
the ``[quicklook]`` section.

CPU
---

Short view:

.. image:: images/cpu.png

If enough horizontal space is available, extended CPU information are
displayed.

Extended view:

.. image:: images/cpu-wide.png

To switch to per-CPU stats, just hit the ``1`` key:

.. image:: images/per-cpu.png

The CPU stats are shown as a percentage and for the configured refresh
time. The total CPU usage is displayed on the first line.

| If user|system CPU is ``<50%``, then status is set to ``"OK"``
| If user|system CPU is ``>50%``, then status is set to ``"CAREFUL"``
| If user|system CPU is ``>70%``, then status is set to ``"WARNING"``
| If user|system CPU is ``>90%``, then status is set to ``"CRITICAL"``

*Note*: limit values can be overwritten in the configuration file under
the ``[cpu]`` and/or ``[percpu]`` sections.

Load
----

.. image:: images/load.png

On the *No Sheep* blog, *Zachary Tirrell* defines the load average [1]_:

    "In short it is the average sum of the number of processes
    waiting in the run-queue plus the number currently executing
    over 1, 5, and 15 minutes time periods."

Glances gets the number of CPU core to adapt the alerts.
Alerts on load average are only set on 15 minutes time period.
The first line also displays the number of CPU core.

| If load average is ``<0.7*core``, then status is set to ``"OK"``
| If load average is ``>0.7*core``, then status is set to ``"CAREFUL"``
| If load average is ``>1*core``, then status is set to ``"WARNING"``
| If load average is ``>5*core``, then status is set to ``"CRITICAL"``

*Note*: limit values can be overwritten in the configuration file under
the ``[load]`` section.

Memory
------

Glances uses two columns: one for the ``RAM`` and one for the ``SWAP``.

.. image:: images/mem.png

If enough space is available, Glances displays extended information for
the ``RAM``:

.. image:: images/mem-wide.png

Alerts are only set for used memory and used swap.

| If used memory|swap is ``<50%``, then status is set to ``"OK"``
| If used memory|swap is ``>50%``, then status is set to ``"CAREFUL"``
| If used memory|swap is ``>70%``, then status is set to ``"WARNING"``
| If used memory|swap is ``>90%``, then status is set to ``"CRITICAL"``

*Note*: limit values can be overwritten in the configuration file under
the ``[memory]`` and/or ``[memswap]`` sections.

Network
-------

.. image:: images/network.png

Glances displays the network interface bit rate. The unit is adapted
dynamically (bits per second, kbits per second, Mbits per second, etc).

Alerts are only set if the maximum speed per network interface is available
(see sample in the configuration file).

*Note*: it is possibile to define a list of network interfaces to hide
and per-interface limit values in the ``[network]`` section of the
configuration file and aliases for interface name.

Disk I/O
--------

.. image:: images/diskio.png

Glances displays the disk I/O throughput. The unit is adapted dynamically.

There is no alert on this information.

*Note*: it is possible to define a list of disks to hide under the
``[diskio]`` section in the configuration file and aliases for disk name.

File System
-----------

.. image:: images/fs.png

Glances displays the used and total file system disk space. The unit is
adapted dynamically.

Alerts are set for used disk space.

| If used disk is ``<50%``, then status is set to ``"OK"``
| If used disk is ``>50%``, then status is set to ``"CAREFUL"``
| If used disk is ``>70%``, then status is set to ``"WARNING"``
| If used disk is ``>90%``, then status is set to ``"CRITICAL"``

*Note*: limit values can be overwritten in the configuration file under
the ``[filesystem]`` section.

If a RAID controller is detected on you system, its status will be displayed:

.. image:: images/raid.png

By default, the plugin only displays physical devices (hard disks, USB
keys) and ignore all others. To allow others FS type, you have to use the
following section in the configuration file:

::

    [fs]
    allow=zfs,misc

Sensors
-------

Glanc