diff --git a/docs/glances-doc.html b/docs/glances-doc.html index e69de29b..134b987d 100644 --- a/docs/glances-doc.html +++ b/docs/glances-doc.html @@ -0,0 +1,600 @@ + + + + + + +Glances + + + +
+

Glances

+ +

This manual describes Glances version 1.7.

+

Copyright © 2012-2013 Nicolas Hennion <nicolas@nicolargo.com>

+

August 2013

+
+

Table of Contents

+ +
+
+

Introduction

+

Glances is a cross-platform curses-based 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.

+

Glances can adapt dynamically the displayed information depending on the +terminal size. It can also work in a client/server mode for remote monitoring.

+

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

+

Console (80x24)

+images/screenshot.png +

Full view (>80x24)

+images/screenshot-wide.png +
+
+

Usage

+
+

Standalone mode

+

Simply run:

+
+$ glances
+
+
+
+

Client/Server mode

+

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

+
+server$ glances -s
+
+

and on the client:

+
+client$ glances -c @server
+
+

where @server is the IP address or host name of the server.

+

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.

+

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

+

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

+

You can also set a password to access to the server -P password.

+

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

+
+
+
+

Command reference

+
+

Command-line options

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+-bDisplay network rate in Bytes per second (default: Bits per second)
+-B IPBind server to the given IP or hostname (IPv4 or IPv6)
+-c IPConnect to a Glances server by IP or hostname (IPv4 or IPv6)
+-C filePath to the configuration file (default: {/usr/local,}/etc/glances/glances.conf)
+-dDisable disk I/O module
+-eEnable the sensors module (Linux-only)
+-f fileSet the output folder (HTML) or file (CSV)
+-hDisplay the help and exit
+-mDisable mount module
+-nDisable network module
+-o outputDefine additional output (available: HTML or CSV)
+-p PORTDefine the client or server TCP port (default: 61209)
+-P passwordDefine a client/server password
+-rDo not list processes (for low CPU consumption)
+-sRun Glances in server mode
+-t secSet the refresh time in seconds (default: 3 seconds)
+-vDisplay the version and exit
+-yEnable the hddtemp module (needs running hddtemp daemon)
+-zDo not use the bold color attribute
+-1Start Glances in per CPU mode
+
+
+

Interactive commands

+

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

+
+
a
+

Automatic mode. The processes are sorted automatically.

+
    +
  • If CPU iowait >60%, sort processes by IO 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 IO
+
c
+
Sort processes by CPU%
+
d
+
Show/hide disk I/O stats
+
f
+
Show/hide file system stats
+
h
+
Show/hide the help message (with the keys you can press and the limits)
+
i
+
Sort processes by IO rate (need root account on some OS)
+
l
+
Show/hide log messages
+
m
+
Sort processes by MEM%
+
n
+
Show/hide network stats
+
p
+
Sort processes by name
+
s
+
Show/hide sensors stats (only available with -e flag; pysensors library is needed; Linux-only)
+
t
+
View network IO as combination
+
u
+
View cumulative network IO
+
w
+
Delete finished warning log messages
+
x
+
Delete finished warning and critical log messages
+
1
+
Switch between global CPU and per-CPU stats
+
q
+
Quit
+
+
+
+
+

Configuration

+

No configuration file is mandatory to use Glances.

+

Furthermore a configuration file is needed for setup limits and/or monitored processes list.

+

By default, the configuration file is under:

+
+/etc/glances/glances.conf (Linux)
+
+

or:

+
+/usr/local/etc/glances/glances.conf (*BSD and OS X)
+
+

To override the default configuration, you can copy the glances.conf file to +your $XDG_CONFIG_HOME directory (e.g. Linux):

+
+mkdir -p $XDG_CONFIG_HOME/glances
+cp /etc/glances/glances.conf $XDG_CONFIG_HOME/glances/
+
+

On OS X, you should copy the configuration file to ~/Library/Application Support/glances/.

+
+
+

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"
+
+
+ +
+

CPU

+

Short view:

+images/cpu.png +

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

+

Extended view:

+images/cpu-wide.png +

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

+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|nice CPU is <50%, then status is set to "OK"
+
If user|system|nice CPU is >50%, then status is set to "CAREFUL"
+
If user|system|nice CPU is >70%, then status is set to "WARNING"
+
If user|system|nice CPU is >90%, then status is set to "CRITICAL"
+
+

Note: limits values can be overwrited in the configuration file ([cpu] section).

+
+
+

Load

+images/load.png +

On the No Sheep blog, Zachary Tirrell defines the average load [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 minute time periods."
+

Glances gets the number of CPU core to adapt the alerts. +Alerts on average load are only set on 5 and 15 min. +The first line also display the number of CPU core.

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

Note: limits values can be overwrited in the configuration file ([load] section).

+
+
+

Memory

+

Glances uses two columns: one for the RAM and another one for the Swap.

+images/mem.png +

If enough space is available, Glances displays extended informations:

+images/mem-wide.png +

With Glances, alerts are only set for on used memory and used swap.

+
+
If memory is <50%, then status is set to "OK"
+
If memory is >50%, then status is set to "CAREFUL"
+
If memory is >70%, then status is set to "WARNING"
+
If memory is >90%, then status is set to "CRITICAL"
+
+

Note: limits values can be overwrited in the configuration file ([memory] and [swap] sections).

+
+
+

Network

+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 network interface maximum speed is available.

+

For example, on a 100 Mbps ethernet interface, the warning status is set +if the bit rate is higher than 70 Mbps.

+
+
If bit rate is <50%, then status is set to "OK"
+
If bit rate is >50%, then status is set to "CAREFUL"
+
If bit rate is >70%, then status is set to "WARNING"
+
If bit rate is >90%, then status is set to "CRITICAL"
+
+
+
+

Sensors

+images/sensors.png +

Glances can displays the sensors informations trough lm-sensors (only +available on Linux) and hddtemp daemon.

+

A filter is processed in order to only display temperature.

+

You should enable this module using the following command line:

+
+$ glances -e
+
+

There is no alert on this information.

+

Note: limits values can be overwrited in the configuration file ([temperature] and [hddtemperature] section).

+
+
+

Disk I/O

+images/diskio.png +

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

+

There is no alert on this information.

+
+
+

File system

+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 disk used is <50%, then status is set to "OK"
+
If disk used is >50%, then status is set to "CAREFUL"
+
If disk used is >70%, then status is set to "WARNING"
+
If disk used is >90%, then status is set to "CRITICAL"
+
+

Note: limits values can be overwrited in the configuration file ([filesystem] section).

+
+
+

Processes list

+

Compact view:

+images/processlist.png +

Full view:

+images/processlist-wide.png +

Three views are available for processes: +* Processes summary +* Optionnal monitored processes list (new in Glances 1.7) +* Processes list

+

By default, or if you hit the a key, the processes list is automatically +sorted by CPU of memory usage.

+

Note: limits values can be overwrited in the configuration file ([process] section).

+

The number of processes in the list is adapted to the screen size.

+
+
VIRT
+
Virtual memory size
+
RES
+
Resident memory
+
CPU%
+
% of CPU used by the process
+
MEM%
+
% of MEM used by the process
+
PID
+
Process ID
+
USER
+
User ID per process
+
NI
+
Nice level of the process
+
S
+
Process status
+
TIME+
+
Cumulative CPU time used
+
IOR/s
+
Per process IO read rate (in Byte/s)
+
IOW/s
+
Per process IO write rate (in Byte/s)
+
NAME
+
Process name or command line
+
+

Process status legend:

+
+
R
+
running
+
S
+
sleeping (may be interrupted)
+
D
+
disk sleep (may not be interrupted)
+
T
+
traced/stopped
+
Z
+
zombie
+
+
+
+

monitored processes list

+

Optionnal and new in version 1.7.

+

The monitored processes list allows user, through the Glances configuration file, to group processes and quickly show if the number of runing process is not good.

+

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. Use with caution. Should return a single line string.
    • +
  • countmin: (optional) minimal number of processes. A warning will be displayed if number of process < count
    • +
  • countmax: (optional) maximum number of processes. A warning will be displayed if number of process > count
    • +
+

Up to 10 items can be defined.

+

For exemple, 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_1_description=PHP-FPM
+list_1_regex=.*php-fpm.*
+list_1_countmin=1
+list_1_countmax=20
+
+
+
+

Logs

+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 date
    2. +
  2. end date
    3. +
  3. alert name
    4. +
  4. {min/avg/max} values (or monitored processes list description)
    5. +
+
+ +
+
+

API documentation

+

Glances uses a XML-RPC server and can be used by another client software.

+

API documentation is available at https://github.com/nicolargo/glances/wiki/The-Glances-API-How-To

+
+
+

Support

+

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/
+
+
+ + diff --git a/docs/glances-doc.rst b/docs/glances-doc.rst index 53086512..35720b1c 100644 --- a/docs/glances-doc.rst +++ b/docs/glances-doc.rst @@ -388,7 +388,15 @@ Process status legend: ``Z`` zombie -The monitored processes list allows user, through the Glances configuration file, to group processes and quickly show if the number of runing process is not good. Each item is defined by: +monitored processes list +------------------------ + +Optionnal and new in version 1.7. + +The monitored processes list allows user, through the Glances configuration file, to group processes and quickly show if the number of runing process is not good. + +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. Use with caution. Should return a single line string.