16 files changed, 585 insertions, 0 deletions
diff --git a/docs/aoa/actions.rst b/docs/aoa/actions.rst
new file mode 100644
index 00000000..5ce40bcd
--- /dev/null
+++ b/docs/aoa/actions.rst
@@ -0,0 +1,34 @@
+.. _actions:
+
+Actions
+=======
+
+Glances can trigger actions on events.
+
+By ``action``, we mean all shell command line. For example, if you want
+to execute the ``foo.py`` script if the last 5 minutes load are critical
+then add the ``_action`` line to the Glances configuration file:
+
+.. code-block:: ini
+
+    [load]
+    critical=5.0
+    critical_action=python /path/to/foo.py
+
+All the stats are available in the command line through the use of the
+`{{mustache}}`_ syntax. Another example would be to create a log file
+containing used vs total disk space if a space trigger warning is
+reached:
+
+.. code-block:: ini
+
+    [fs]
+    warning=70
+    warning_action=echo {{mnt_point}} {{used}}/{{size}} > /tmp/fs.alert
+
+.. note::
+    You can use all the stats for the current plugin. See
+    https://github.com/nicolargo/glances/wiki/The-Glances-2.x-API-How-to
+    for the stats list.
+
+.. _{{mustache}}: https://mustache.github.io/
diff --git a/docs/aoa/cpu.rst b/docs/aoa/cpu.rst
new file mode 100644
index 00000000..8ac77855
--- /dev/null
+++ b/docs/aoa/cpu.rst
@@ -0,0 +1,41 @@
+.. _cpu:
+
+CPU
+===
+
+The CPU stats are shown as a percentage and for the configured refresh
+time. The total CPU usage is displayed on the first line.
+
+.. image:: ../_static/cpu.png
+
+If enough horizontal space is available, extended CPU information are
+displayed.
+
+.. image:: ../_static/cpu-wide.png
+
+To switch to per-CPU stats, just hit the ``1`` key:
+
+.. image:: ../_static/per-cpu.png
+
+By default, ``steal`` CPU time alerts aren't logged. If you want that,
+just add to the configuration file:
+
+.. code-block:: ini
+
+    [cpu]
+    steal_log=True
+
+Legend:
+
+================= ============
+CPU (user/system) Status
+================= ============
+``<50%``          ``OK``
+``>50%``          ``CAREFUL``
+``>70%``          ``WARNING``
+``>90%``          ``CRITICAL``
+================= ============
+
+.. note::
+    Limit values can be overwritten in the configuration file under
+    the ``[cpu]`` and/or ``[percpu]`` sections.
diff --git a/docs/aoa/disk.rst b/docs/aoa/disk.rst
new file mode 100644
index 00000000..37a32abf
--- /dev/null
+++ b/docs/aoa/disk.rst
@@ -0,0 +1,26 @@
+.. _disk:
+
+Disk I/O
+========
+
+.. image:: ../_static/diskio.png
+
+Glances displays the disk I/O throughput. The unit is adapted
+dynamically.
+
+There is no alert on this information.
+
+It's possible to define:
+
+- a list of disks to hide
+- aliases for disk name
+
+under the ``[diskio]`` section in the configuration file.
+
+For example, if you want to hide the loopback disks (loop0, loop1, ...)
+and the specific ``sda5`` partition:
+
+.. code-block:: ini
+
+    [diskio]
+    hide=sda5,loop.*
diff --git a/docs/aoa/docker.rst b/docs/aoa/docker.rst
new file mode 100644
index 00000000..b5bcd047
--- /dev/null
+++ b/docs/aoa/docker.rst
@@ -0,0 +1,11 @@
+.. _docker:
+
+Docker
+======
+
+If you use ``Docker``, Glances can help you to monitor your containers.
+Glances uses the Docker API through the `docker-py`_ library.
+
+.. image:: ../_static/docker.png
+
+.. _docker-py: https://github.com/docker/docker-py
diff --git a/docs/aoa/folders.rst b/docs/aoa/folders.rst
new file mode 100644
index 00000000..5f78e496
--- /dev/null
+++ b/docs/aoa/folders.rst
@@ -0,0 +1,34 @@
+.. _folders:
+
+Folders
+=======
+
+The folders plugin allows user, through the configuration file, to
+monitor size of a predefined folders list.
+
+.. image:: ../_static/folders.png
+
+Each item is defined by:
+
+- ``path``: absolute path to monitor (mandatory)
+- ``careful``: optional careful threshold (in MB)
+- ``warning``: optional warning threshold (in MB)
+- ``critical``: optional critical threshold (in MB)
+
+Up to ``10`` items can be defined.
+
+For example, if you want to monitor the ``/tmp`` folder, the following
+definition should do the job:
+
+.. code-block:: ini
+
+    [folders]
+    folder_1_path=/tmp
+    folder_1_careful=2500
+    folder_1_warning=3000
+    folder_1_critical=3500
+
+In client/server mode, the list is defined on the ``server`` side.
+
+.. warning::
+    Do **NOT** define folders containing lot of files and subfolders.
diff --git a/docs/aoa/fs.rst b/docs/aoa/fs.rst
new file mode 100644
index 00000000..1f8bc566
--- /dev/null
+++ b/docs/aoa/fs.rst
@@ -0,0 +1,55 @@
+.. _fs:
+
+File System
+===========
+
+.. image:: ../_static/fs.png
+
+Glances displays the used and total file system disk space. The unit is
+adapted dynamically.
+
+Alerts are set for used disk space.
+
+Legend:
+
+=========== ============
+Disk usage  Status
+=========== ============
+``<50%``    ``OK``
+``>50%``    ``CAREFUL``
+``>70%``    ``WARNING``
+``>90%``    ``CRITICAL``
+=========== ============
+
+.. note::
+    Limit values can be overwritten in the configuration file under
+    the ``[filesystem]`` section.
+
+By default, the plugin only displays physical devices (hard disks, USB
+keys). To allow other file system types, you have to enable them in the
+configuration file. For example, if you want to allow the ``zfs`` file
+system:
+
+.. code-block:: ini
+
+    [fs]
+    allow=zfs
+
+Also, you can hide mount points as well (in the following ``/boot``):
+
+.. code-block:: ini
+
+     [fs]
+     hide=/boot.*
+
+RAID
+----
+
+*Availability: Linux*
+
+Thanks to the `pymdstat`_ library, if a ``RAID`` controller is detected
+on you system, its status will be displayed as well:
+
+.. image:: ../_static/raid.png
+
+.. _pymdstat: https://github.com/nicolargo/pymdstat
diff --git a/docs/aoa/header.rst b/docs/aoa/header.rst
new file mode 100644
index 00000000..d62024e3
--- /dev/null
+++ b/docs/aoa/header.rst
@@ -0,0 +1,20 @@
+.. _header:
+
+Header
+======
+
+.. image:: ../_static/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 also displayed.
+
+**Connected**:
+
+.. image:: ../_static/connected.png
+
+**Disconnected**:
+
+.. image:: ../_static/disconnected.png
diff --git a/docs/aoa/index.rst b/docs/aoa/index.rst
new file mode 100644
index 00000000..097555a9
--- /dev/null
+++ b/docs/aoa/index.rst
@@ -0,0 +1,37 @@
+.. _aoa:
+
+Anatomy Of The Application
+==========================
+
+This document is meant to give an overview of the Glances interface.
+
+Legend:
+
+=========== ============
+``GREEN``   ``OK``
+``BLUE``    ``CAREFUL``
+``MAGENTA`` ``WARNING``
+``RED``     ``CRITICAL``
+=========== ============
+
+.. note::
+    Only stats with colored background will be shown in the alert view.
+
+.. toctree::
+   :maxdepth: 2
+
+   header
+   quicklook
+   cpu
+   load
+   memory
+   network
+   disk
+   fs
+   folders
+   sensors
+   ps
+   monitor
+   logs
+   docker
+   actions
diff --git a/docs/aoa/load.rst b/docs/aoa/load.rst
new file mode 100644
index 00000000..adc240d7
--- /dev/null
+++ b/docs/aoa/load.rst
@@ -0,0 +1,35 @@
+.. _load:
+
+Load
+====
+
+*Availability: Unix*
+
+.. image:: ../_static/load.png
+
+On the *No Sheep* blog, Zachary Tirrell defines the `load average`_:
+
+    "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.
+
+Legend:
+
+============= ============
+Load avg      Status
+============= ============
+``<0.7*core`` ``OK``
+``>0.7*core`` ``CAREFUL``
+``>1*core``   ``WARNING``
+``>5*core``   ``CRITICAL``
+============= ============
+
+.. note::
+    Limit values can be overwritten in the configuration file under
+    the ``[load]`` section.
+
+.. _load average: http://nosheep.net/story/defining-unix-load-average/
diff --git a/docs/aoa/logs.rst b/docs/aoa/logs.rst
new file mode 100644
index 00000000..c9365915
--- /dev/null
+++ b/docs/aoa/logs.rst
@@ -0,0 +1,21 @@
+.. _logs:
+
+Logs
+====
+
+.. image:: ../_static/logs.png
+
+A log messages list is displayed in the bottom of the screen if and only
+if:
+
+- at least one ``WARNING`` or ``CRITICAL`` alert was occurred
+- space is available in the bottom of the console/terminal
+
+Each alert message displays the following information:
+
+1. start datetime
+2. duration if alert is terminated or `ongoing` if the alert is still in
+   progress
+3. alert name
+4. {min,avg,max} values or number of running processes for monitored
+   processes list alerts
diff --git a/docs/aoa/memory.rst b/docs/aoa/memory.rst
new file mode 100644
index 00000000..0cd6afc8
--- /dev/null
+++ b/docs/aoa/memory.rst
@@ -0,0 +1,30 @@
+.. _memory:
+
+Memory
+======
+
+Glances uses two columns: one for the ``RAM`` and one for the ``SWAP``.
+
+.. image:: ../_static/mem.png
+
+If enough space is available, Glances displays extended information for
+the ``RAM``:
+
+.. image:: ../_static/mem-wide.png
+
+Alerts are only set for used memory and used swap.
+
+Legend:
+
+======== ============
+RAM/Swap Status
+======== ============
+``<50%`` ``OK``
+``>50%`` ``CAREFUL``
+``>70%`` ``WARNING``
+``>90%`` ``CRITICAL``
+======== ============
+
+.. note::
+    Limit values can be overwritten in the configuration file under
+    the ``[memory]`` and/or ``[memswap]`` sections.
diff --git a/docs/aoa/monitor.rst b/docs/aoa/monitor.rst
new file mode 100644
index 00000000..c0bdb3ee
--- /dev/null
+++ b/docs/aoa/monitor.rst
@@ -0,0 +1,65 @@
+.. _monitor:
+
+Monitored Processes List
+========================
+
+The monitored processes list allows user, through the configuration
+file, to group processes and quickly show if the number of running
+processes is not good.
+
+.. image:: ../_static/monitored.png
+
+Each item is defined by:
+
+- ``description``: description of the processes (max 16 chars).
+- ``regex``: regular expression of the processes to monitor.
+- ``command``: (optional) full path to shell command/script for extended
+- stat. Should return a single line string. Use with caution.
+- ``countmin``: (optional) minimal number of processes. A warning will
+- be displayed if number of processes < count.
+- ``countmax``: (optional) maximum number of processes. A warning will
+  be displayed if number of processes > count.
+
+Up to ``10`` items can be defined.
+
+For example, if you want to monitor the Nginx processes on a web server,
+the following definition should do the job:
+
+.. code-block:: ini
+
+    [monitor]
+    list_1_description=Nginx server
+    list_1_regex=.*nginx.*
+    list_1_command=nginx -v
+    list_1_countmin=1
+    list_1_countmax=4
+
+If you also want to monitor the PHP-FPM daemon processes, you should add
+another item:
+
+.. code-block:: ini
+
+    [monitor]
+    list_1_description=Nginx server
+    list_1_regex=.*nginx.*
+    list_1_command=nginx -v
+    list_1_countmin=1
+    list_1_countmax=4
+    list_2_description=PHP-FPM
+    list_2_regex=.*php-fpm.*
+    list_2_countmin=1
+    list_2_countmax=20
+
+In client/server mode, the list is defined on the server side.
+A new method, called `getAllMonitored`, is available in the APIs and
+get the JSON representation of the monitored processes list.
+
+Alerts are set as following:
+
+================= ============
+# of process       Status
+================= ============
+``0``             ``CRITICAL``
+``min < p < max`` ``OK``
+``p > max``       ``WARNING``
+================= ============
diff --git a/docs/aoa/network.rst b/docs/aoa/network.rst
new file mode 100644
index 00000000..56e8c7f8
--- /dev/null
+++ b/docs/aoa/network.rst
@@ -0,0 +1,28 @@
+.. _network:
+
+Network
+=======
+
+.. image:: ../_static/network.png
+
+Glances displays the network interface bit rate. The unit is adapted
+dynamically (bit/s, kbit/s, Mbit/s, etc).
+
+Alerts are only set if the maximum speed per network interface is
+available (see sample in the configuration file).
+
+It's also possibile to define:
+
+- a list of network interfaces to hide
+- per-interface limit values
+- aliases for interface name
+
+in the ``[network]`` section of the configuration file.
+
+For example, if you want to hide the loopback interface (lo) and all the
+virtual docker interface (docker0, docker1, ...):
+
+.. code-block:: ini
+
+    [network]
+    hide=lo,docker.*
diff --git a/docs/aoa/ps.rst b/docs/aoa/ps.rst
new file mode 100644
index 00000000..a85a7d96
--- /dev/null
+++ b/docs/aoa/ps.rst
@@ -0,0 +1,107 @@
+.. _ps:
+
+Processes List
+==============
+
+Compact view:
+
+.. image:: ../_static/processlist.png
+
+Full view:
+
+.. image:: ../_static/processlist-wide.png
+
+Filtered view:
+
+.. image:: ../_static/processlist-filter.png
+
+The process view consists of 3 parts:
+
+- Processes summary
+- Monitored processes list (optional)
+- Processes list
+
+The processes summary line displays:
+
+- Tasks number (total number of processes)
+- Threads number
+- Running tasks number
+- Sleeping tasks number
+- Other tasks number (not running or sleeping)
+- Sort key
+
+By default, or if you hit the ``a`` key, the processes list is
+automatically sorted by:
+
+- ``CPU``: if there is no alert (default behavior)
+- ``CPU``: if a CPU or LOAD alert is detected
+- ``MEM``: if a memory alert is detected
+- ``DISK I/O``: if a CPU iowait alert is detected
+
+The number of processes in the list is adapted to the screen size.
+
+Columns display
+---------------
+
+========================= ==============================================
+``CPU%``                  % of CPU used by the process
+
+                          If Irix/Solaris mode is off, the value is
+                          divided by logical core number
+``MEM%``                  % of MEM used by the process
+``VIRT``                  Virtual Memory Size
+
+                          The total amount of virtual memory used by the
+                          process
+``RES``                   Resident Memory Size
+
+                          The non-swapped physical memory a process is
+                          using
+``PID``                   Process ID
+``USER``                  User ID
+``NI``                    Nice level of the process
+``S``                     Process status
+
+                          The status of the process:
+
+                          - ``R``: running
+                          - ``S``: sleeping (may be interrupted)
+                          - ``D``: disk sleep (may not be interrupted)
+                          - ``T``: traced/stopped
+                          - ``Z``: zombie
+
+``TIME+``                 Cumulative CPU time used by the process
+``R/s``                   Per process I/O read rate in B/s
+``W/s``                   Per process I/O write rate in B/s
+``COMMAND``               Process command line or command name
+
+                          User can switch to the process name by
+                          pressing on the ``'/'`` key
+========================= ==============================================
+
+Extended info
+-------------
+
+.. image:: ../_static/processlist-top.png
+
+In standalone mode, additional information are provided for the top
+process:
+
+========================= ==============================================
+``CPU affinity``          Number of cores used by the process
+``Memory info``           Extended memory information about the process
+
+                          For example, on Linux: swap, shared, text,
+                          lib, data and dirty
+``Open``                  The number of threads, files and network
+                          sessions (TCP and UDP) used by the process
+``IO nice``               The process I/O niceness (priority)
+========================= ==============================================
+
+The extended stats feature can be enabled using the
+``--enable-process-extended`` option (command line) or the ``e`` key
+(curses interface).
+
+.. note::
+    Limit values can be overwritten in the configuration file under
+    the ``[process]`` section.
diff --git a/docs/aoa/quicklook.rst b/docs/aoa/quicklook.rst
new file mode 100644
index 00000000..d4e6c74f
--- /dev/null
+++ b/docs/aoa/quicklook.rst
@@ -0,0 +1,17 @@
+.. _quicklook:
+
+Quick Look
+==========
+
+The ``quicklook`` plugin is only displayed on wide screen and proposes a
+bar view for CPU and memory (virtual and swap).
+
+.. image:: ../_static/quicklook.png
+
+If the per CPU mode is on (by clicking the ``1`` key):
+
+.. image:: ../_static/quicklook-percpu.png
+
+.. note::
+    Limit values can be overwritten in the configuration file under
+    the ``[quicklook]`` section.
diff --git a/docs/aoa/sensors.rst b/docs/aoa/sensors.rst
new file mode 100644
index 00000000..d2d459ea
--- /dev/null
+++ b/docs/aoa/sensors.rst
@@ -0,0 +1,24 @@
+.. _sensors:
+
+Sensors
+=======
+
+*Availability: Linux*
+
+.. image:: ../_static/sensors.png
+
+Glances can displays the sensors information using ``lm-sensors``,
+``hddtemp`` and `batinfo`_.
+
+All of the above libraries are available only on Linux.
+
+As of ``lm-sensors``, a filter is being applied in order to display
+temperature and fan speed only.
+
+There is no alert on this information.
+
+.. note::
+    Limit values and sensors alias names can be defined in the
+    configuration file under the ``[sensors]`` section.
+
+.. _batinfo: https://github.com/nicolargo/batinfo