Metadata-Version: 1.0
Name: gstatus
Version: 0.65
Summary: Show the current health of the components in a glusterfs Trusted Storage Pool
Home-page: https://github.com/pcuzner/gstatus
Author: Paul Cuzner
Author-email: pcuzner@redhat.com
License: GPLv3
Description: GSTATUS
                                       =======
        
        Overview
        ========
        A gluster trusted pool (aka cluster), consists of several key components; 
        nodes, volumes and bricks. In glusterfs 3.4/3.5, there isn't a single command
        that can provide an overview of the cluster's health. This means that admins
        currently assess the cluster health by looking at several commands to piece
        together a picture of the cluster's state.
        
        This isn't ideal - so 'gstatus' is an attempt to provide an easy to use,
        highlevel view of a cluster's health through a single command. The tool gathers
        information by issuing gluster commands, to build an object model covering
        Nodes, Volumes and Bricks. With this data in place, checks are performed across
        this meta data and errors reported back to the user. In later releases, this
        data could be analysed in different ways to add further checks, incorporating
        deployment best practices, freespace triggers etc.
        
        Pre-Requisites
        ==============
        + glusterfs 3.4 or above
          The tool issues commands to gluster using the --xml parameter. Scraping the
          output is another possibility, but by using the xml option, the program 
          should be more stable and more easily extendable
          
        + volume types
          the initial release of gstatus supports distributed and 
          distributed-replicated volumes ONLY
        
        
        Dependencies
        ============
        - python 2.6 or above
        - gluster CLI
        - gluster version 3.4 or above
        
        
        Installation
        ============
        Installing the tool can be done in two ways, through python-seuptools or simply
        by running the main script (gstatus.py) directly.
        
        * Using python-setuptools
        1. To install using this method extract the archive file
           - tar xvzf gstatus.tar.gz
        2. cd to the gstatus directory
        3. run the setup.py program
           - python setup.py install
        4. invoke the script
           gstatus <options>
        
        This will install a hook for gstatus in /usr/bin so running the script doesn't
        need the .py extension.
        
        * running from the archive
        1. Extract the archive file
           - tar xvzf gstatus.tar.gz
        2. cd to the gstatus directory
        3. invoke the script using
           ./gstatus.py <options>
        
        Upgrade Notes
        =============
        1. If you're upgrading via rpm, first remove the existing version and then install
        the new one
        
        
        Volume States
        =============
        A gluster volume is made from individual filesystems (gluster bricks) across 
        multiple nodes. From an end/user of application perspective, this complexity
        is abstracted but the status of individual bricks does have a bearing on the
        data availability of the volume. For example, even without replication the
        loss of a single brick in the volume will not cause the volume itself to be
        unavilable, but instead manifest as inaccessible files in the filesystem.
         
        To help understand the impact a brick or node outage can have on data access,
        gstatus introduces some additional volume status descriptions.
        
        UP
        Volume is started and available, all bricks are up
        
        UP(Degraded)
        This state is specific to replicated volumes, where at least one brick is down
        within a replica set. Data is still 100% available due to the alternate
        replica(s),  but the resilience of the volume to further failures within the
        same replica set flags this volume as 'degraded'. 
        
        UP(Partial)
        Effectively this means that allthough some bricks in the volume are online, 
        there are others that are down to a point where areas of the filesystem will be
        missing. For a distrubuted volume, this state is seen if ANY brick is down, 
        whereas for a replicated volume a complete replica set needs to be down before
        the volume state transitions to PARTIAL. 
        
        DOWN
        Bricks are down, or the volume has not yet been started 
        
        
        Running the tool
        ================
        
        Running gstatus with a -h flag shows the following options;
        
        [root@gfs-ec1 gstatus]# ./gstatus.py -h
        Usage: gstatus.py [options]
        
        Options:
          --version             show program's version number and exit
          -h, --help            show this help message and exit
          -s, --state           show highlevel health of the cluster
          -v, --volume          volume info (default is ALL, or supply a volume name)
          -b, --backlog         Look deeper at self heal state
          -a, --all             show all cluster information (-s with -v)
          -u UNITS, --units=UNITS
                                display capacity units in DECimal or BINary format (GB
                                vs GiB)
          -l, --layout          show brick layout when used with -v, or -a
          -o OUTPUT_MODE, --output-mode=OUTPUT_MODE
                                produce output in different formats - json, keyvalue
                                or console(default)
          -D, --debug           turn on debug mode
          -w, --without-progress
                                turn off progress updates to user during data
                                gathering
          -t TIMEOUT, --timeout=TIMEOUT
                                gluster command timeout value (secs)
        
        
        
        * Understanding the output
        
        - Simply invoking gstatus without any options, will give a 3 line summary of
          the cluster. This will tell you overall health, capacity and gluster version.
          If there are issues detected in the cluster, the UNHEALTHY state will be 
          suffixed by a number in brackets - the number denotes the number of errors
          detected within the cluster.
        
        - Using -a will show high level cluster elements, as well as volume information
          You'll notice  that there are a number of what appear to be fractions listed
          against items like Nodes, Bricks etc.
        
          These fractions actually show you the current 'up' state against the 
          potential up state. So a 'Node' field that shows 2/4, actually means the
          cluster has 4 nodes, but only 2 are in an up state.
        
          e.g.
        [root@rhs1-1 gstatus-tests]# gstatus
           
              Status: HEALTHY           Capacity: 32.00 GiB(raw bricks)
           Glusterfs: 3.4.0.59rhs                 10.00 GiB(raw used)
          OverCommit: Yes                         48.00 GiB(usable from volumes)
        
        [root@rhs1-1 gstatus-tests]# gstatus -a
         
              Status: HEALTHY           Capacity: 32.00 GiB(raw bricks)
           Glusterfs: 3.4.0.59rhs                 10.00 GiB(raw used)
          OverCommit: Yes                         48.00 GiB(usable from volumes)
        
           Nodes    :  5/ 5		Volumes:  2 Up
           Self Heal:  5/ 4		          0 Up(Degraded)
           Bricks   :  8/ 8		          0 Up(Partial)
           Clients  :     5               0 Down
        
        <snip>
        
        - Capacity information is derived from the brick information taken from a 
          'vol status detail' command. The accuracy of this number therefore depends
          on the nodes/bricks being all up - elements missing from the configuration
          will simply be missing from the calculation.
        
        - A 'flag' called 'OverCommit' is provided that indicates whether a brick is
          used by multiple volumes. Although technically valid, this exposes the 
          user to capacity conflicts across different volumes when quota's are not used.
        
        - running the tool with the -l flag (with -a, or -v) will show a line diagram
          depicting the brick layout within the volume. This feature was is inspired 
          by work of Fred van Zwieten and Niels De Vos in the 'lsgvt' project.
        
        TIP: To keep the tool responsive, gstatus will not perform a vol heal <vol> info
        command - since this can take time. However, if you suspect self heal is active
        you can use the -b setting to check for a backlog of file heal operations.
        
        
        The examples directory included in the archive contains a number of scenarios
        that show the behaviour of the script under different error conditions.
        
         
        Tested on
        =========
        - 4 node vm cluster, running Red Hat Storage 2.1 (RHEL 6.4, glusterfs 3.4)
        - 4 node vm cluster, based on RHEL 6.5 with upstream glusterfs 3.5 beta 3
        - 6 node vm cluster, based on CentOS 7.1, glusterfs 3.7 beta2
        
        
        Known Issues
        ============
        
        1) Normally every node will be capacity nodes. However, when nodes are added to
           the cluster for quorum purposes, the Self Heal field shows more nodes with Self 
           Heal active than needed. This is due to the arbitration nodes also running the 
           self head daemon.
Platform: UNKNOWN
