nicolargo/glances
1
1
Fork 0
mirror of https://github.com/nicolargo/glances.git synced 2024-12-29 12:12:53 +03:00
Code Issues Projects Releases Wiki Activity
e9024b3017
glances/docs/glances-doc.rst
nicolargo f2fb8d982b Update doc and correct grammatical errors
2016-01-10 09:53:48 +01:00

1009 lines
26 KiB
ReStructuredText
Raw Blame History

=======
Glances
=======
This manual describes *Glances* version 2.5.1.
Copyright © 2011-2015 Nicolas Hennion <nicolas@nicolargo.com>
October, 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
-3, --disable-quicklook
disable quick look module
-4, --full-quicklook
enable all but quick look and load
-5, --disable-top
Enable/disable the top menu (QuickLook, CPU, MEM and LOAD)
--disable-cpu disable CPU module
--disable-mem disable MEM module
--disable-swap disable SWAP module
--disable-load disable LOAD module
--disable-network disable network module
--disable-ip disable IP module
--disable-diskio disable disk I/O module
--disable-fs disable file system module
--disable-folder disable folders monitoring module
--disable-sensors disable sensors module
--disable-hddtemp disable hddtemp module
--disable-raid disable RAID module
--disable-docker disable Docker module
-2, --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-bg disable background colors in the terminal
--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-opentsdb export stats to an OpenTSDB server (potsdb 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
--disable-irix Task's cpu usage will be divided by the total number of CPUs
--hide-kernel-threads
hide kernel threads in process list
--tree display processes as a tree
-b, --byte display network rate in byte per second
--diskio-show-ramfs show RAM Fs in the disk IO plugin
--fahrenheit display temperature in Fahrenheit (default is Celsius)
-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
Note: On Mac OS, please use CTRL-H to delete 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
``E``
Erase current process filter
``f``
Show/hide file system and folder monitoring 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
``M``
Reset processes summary min/max
``n``
Show/hide network stats
``p``
Sort processes by name
``q`` or ``ESC``
Quit the current Glances session
``r``
Reset history
``R``
Show/Hide RAID plugins
``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
``0``
Task's cpu usage will be divided by the total number of CPUs
``1``
Switch between global CPU and per-CPU stats
``2``
Enable/disable left sidebar
``3``
Enable/disable the quick look module
``4``
Enable/disable all but quick look and load 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:: ini
[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:: ini
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
If the per CPU mode is on (click '1'):
.. image:: images/quicklook-percpu.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
Folders
-------
The folders plugin allows user, through the configuration file, to monitor size
of a predefined folders' list.
.. image:: images/folders.png
Each item is defined by:
* ``path``: absolute path to monitor.
* ``warning``: 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 (threshold careful if size is > 2.5 GB, warning if > 3 Gb and
critical if > 3.5 GB):
::
[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.
Note: do *NOT* define folder containing lot of files and subfolders.
Sensors
-------
Glances can displays the sensors information using `lm-sensors`,
`hddtemp` and `batinfo` [2]_.
All of the above libraries are available only on Linux.
As of lm-sensors, a filter is being applied in order to display
temperature only.
.. image:: images/sensors.png
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.
Processes List
--------------
Compact view:
.. image:: images/processlist.png
Full view:
.. image:: images/processlist-wide.png
Filtered view:
.. image:: images/processlist-filter.png
Three views are available for processes:
* Processes summary
* Optional monitored processes list (see below)
* Processes list
The processes summary line display:
* 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.
``CPU%``
% of CPU used by the process
If IRIX mode is off (aka Solaris mode), the value is divided by logical core number
``MEM%``
% of MEM used by the process
``VIRT``
Total program size - Virtual Memory Size (VMS)
``RES``
Resident Set Size (RSS)
``PID``
Process ID
``USER``
User ID
``NI``
Nice level of the process (niceness other than 0 is highlighted)
``S``
Process status (running process is highlighted)
``TIME+``
Cumulative CPU time used
``IOR/s``
Per process I/O read rate (in Byte/s)
``IOW/s``
Per process I/O write rate (in Byte/s)
``COMMAND``
Process command line
User cans switch to the process name by pressing on the ``/`` key
Process status legend:
``R``
Running
``S``
Sleeping (may be interrupted)
``D``
Disk sleep (may not be interrupted)
``T``
Traced / Stopped
``Z``
Zombie
In standalone mode, additional informations are provided for the top
process:
.. image:: images/processlist-top.png
* CPU affinity (number of cores used by the process)
* Extended memory information (swap, shared, text, lib, data and dirty on Linux)
* Open threads, files and network sessions (TCP and UDP)
* IO nice level
The extended stats feature could 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.
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:: images/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:
::
[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:
::
[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:
| If number of processes is 0, then status is set to ``"CRITICAL"``
| If number of processes is min < current < max, then status is set to ``"OK"``
| Else status is set to ``"WARNING"``
Logs
----
.. image:: images/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
Docker
------
If you use ``Docker``, Glances can help you to monitor your container.
Glances uses the Docker API through the ``docker-py`` library.
.. image:: images/docker.png
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)
Gateway to others services
==========================
CSV
---
It is possible to export statistics to CSV file.
.. code-block:: console
$ glances --export-csv /tmp/glances.csv
CSV file description:
- Stats description (first line)
- Stats (others lines)
InfluxDB
--------
You can export statistics to an ``InfluxDB`` server (time series server).
The connection should be defined in the Glances configuration file as
following:
.. code-block:: ini
[influxdb]
host=localhost
port=8086
user=root
password=root
db=glances
and run Glances with:
.. code-block:: console
$ glances --export-influxdb
InfluxDB 0.9.x or higher also supports an optional tags
configuration parameter specified as comma separated, key:value pairs.
For example:
.. code-block:: ini
[influxdb]
host=localhost
port=8086
user=root
password=root
db=glances
tags=foo:bar,spam:eggs
For Grafana users, Glances provides a dedicated `dashboard`_. Just import
the file in your ``Grafana`` web interface.
.. image:: images/grafana.png
OpenTSDB
--------
You can export statistics to an ``OpenTSDB`` server (time series server).
The connection should be defined in the Glances configuration file as
following:
.. code-block:: ini
[opentsdb]
host=localhost
port=4242
prefix=glances
tags=foo:bar,spam:eggs
and run Glances with:
.. code-block:: console
$ glances --export-opentsdb
Statsd
------
You can export statistics to a ``Statsd`` server (welcome to Graphite!).
The connection should be defined in the Glances configuration file as
following:
.. code-block:: ini
[statsd]
host=localhost
port=8125
prefix=glances
*Note*: the prefix option is optional ('glances by default')
and run Glances with:
.. code-block:: console
$ glances --export-statsd
Glances will generate stats as:
.. code-block:: text
'glances.cpu.user': 12.5,
'glances.cpu.total': 14.9,
'glances.load.cpucore': 4,
'glances.load.min1': 0.19,
...
RabbitMQ
--------
You can export statistics to an ``RabbitMQ`` server (AMQP Broker).
The connection should be defined in the Glances configuration file as
following:
.. code-block:: ini
[rabbitmq]
host=localhost
port=5672
user=glances
password=glances
queue=glances_queue
and run Glances with:
.. code-block:: console
$ glances --export-rabbitmq
APIs documentation
==================
Glances includes a `XML-RPC server`_ and a `RESTFUL-JSON`_ API which can
be used by another client software.
APIs documentation is available at:
- XML-RPC: https://github.com/nicolargo/glances/wiki/The-Glances-2.x-API-How-to
- RESTFUL-JSON: https://github.com/nicolargo/glances/wiki/The-Glances-RESTFULL-JSON-API
Support
=======
To post a question about Glances use cases, please post it to the
official Q&A `forum`_.
To report a bug or a feature request use the bug tracking system at
https://github.com/nicolargo/glances/issues.
Feel free to contribute !
.. [1] http://nosheep.net/story/defining-unix-load-average/
.. [2] https://github.com/nicolargo/batinfo
.. _psutil: https://code.google.com/p/psutil/
.. _XML-RPC server: http://docs.python.org/2/library/simplexmlrpcserver.html
.. _RESTFUL-JSON: http://jsonapi.org/
.. _forum: https://groups.google.com/forum/?hl=en#!forum/glances-users
.. _dashboard: https://github.com/nicolargo/glances/blob/master/conf/glances-grafana.json
Reference in New Issue View Git Blame Copy Permalink