COMMAND NAME: gpstate

Shows the status of a running Apache Cloudberry system.


*****************************************************
SYNOPSIS
*****************************************************

gpstate [-d <coordinator_data_directory>] [-B <parallel_processes>] 
        [-s | -b | -Q | -e] [-m | -c] [-p] [-i] [-f] 
        [-v | -q] [-l <log_directory>]


gpstate -? | -h | --help

*****************************************************
DESCRIPTION
*****************************************************

The gpstate utility displays information about a running 
Apache Cloudberry instance. There is additional information 
you may want to know about a Apache Cloudberry system, since 
it is comprised of multiple PostgreSQL database instances (segments) 
spanning multiple machines. The gpstate utility provides 
additional status information for a Apache Cloudberry system, 
such as:
* Which segments are down.
* Coordinator and segment configuration information (hosts, 
  data directories, etc.).
* The ports used by the system.
* A mapping of primary segments to their corresponding 
  mirror segments.

*****************************************************
OPTIONS
*****************************************************

-b (brief status)

  Optional. Display a brief summary of the state of the 
  Apache Cloudberry system. This is the default option.


-B <parallel_processes>

  The number of segments to check in parallel. If not specified, 
  the utility will start up to 60 parallel processes depending on 
  how many segment instances it needs to check.


-c (show primary to mirror mappings)

  Optional. Display mapping of primary segments to their 
  corresponding mirror segments.


-d <coordinator_data_directory>

  Optional. The coordinator data directory. If not specified, the 
  value set for $COORDINATOR_DATA_DIRECTORY will be used.


-e (show segments with mirror status issues)

  Show details on primary/mirror segment pairs that have 
  potential issues such as 1) the active segment is running in 
  change tracking mode, meaning a segment is down 2) the active 
  segment is in resynchronization mode, meaning it is catching 
  up changes to the mirror 3) a segment is not in its preferred role, 
  for example a segment that was a primary at system initialization 
  time is now acting as a mirror, meaning you may have one or more 
  segment hosts with unbalanced processing load.


-f (show standby coordinator details)

  Display details of the standby coordinator host if configured.


-i (show Apache Cloudberry version)
  
  Display the Apache Cloudberry software version information 
  for each instance.


-l <logfile_directory>

  The directory to write the log file. Defaults to ~/gpAdminLogs.


-m (list mirrors)
 
  Optional. List the mirror segment instances in the system, 
  their current role, and synchronization status.


-p (show ports)

  List the port numbers used throughout the Apache Cloudberry 
  system.


-x (expand)

  Optional. Display details of any current gpexpand.


-q (no screen output)

  Optional. Run in quiet mode. Except for warning messages, command 
  output is not displayed on the screen. However, this information 
  is still written to the log file.


-Q (quick status)

  Optional. Checks segment status in the system catalog on 
  the coordinator host. Does not poll the segments for status.


-s (detailed status)

  Optional. Displays detailed status information for the 
  Apache Cloudberry system.


-v (verbose output)

  Optional. Displays error messages and outputs detailed status 
  and progress information.


-? | -h | --help (help)

  Displays the online help.


*****************************************************
OUTPUT DEFINITIONS FOR DETAIL VIEW
*****************************************************
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
COORDINATOR OUTPUT DATA
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

* Coordinator host - host name of the coordinator

* Coordinator postgres process ID - PID of the coordinator postgres database 
                               listener process

* Coordinator data directory - file system location of the coordinator data directory

* Coordinator port - port of the coordinator database listener process

* Coordinator current role - dispatch = regular operating mode 
                        utility = maintenance mode 

* Cloudberry array configuration type - Standard = one NIC per host 
                                       Multi-Home = multiple NICs per host

* Cloudberry initsystem version - version of Apache Cloudberry when 
                                 system was first initialized

* Cloudberry current version - current version of Apache Cloudberry

* Postgres version - version of PostgreSQL that Apache Cloudberry 
                     is based on

* Cloudberry mirroring status - physical mirroring, SAN or none

* Coordinator standby - host name of the standby coordinator

* Standby coordinator state - status of the standby coordinator: active or passive

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
SEGMENT OUTPUT DATA
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

* Hostname - system-configured host name

* Address - network address host name (NIC name)

* Datadir - file system location of segment data directory

* Port - port number of segment postgres database listener process

* Current Role - current role of a segment: Mirror or Primary 

* Preferred Role - role at system initialization time: Mirror or Primary

* Mirror Status - status of a primary/mirror segment pair:
                Synchronized = data is up to date on both 
                Resynchronizing = data is currently being copied from one to the other
                Change Tracking = segment down and active segment is logging changes

* WAL sent location - last write-ahead log location sent

* WAL flush location - last write-ahead log location flushed to disk on the replica

* WAL replay location - last write-ahead log location replayed on the replica

* Change tracking data size - when in Change Tracking mode, the size of the change 
                            log file (may grow and shrink as compression is applied)

* Estimated total data to synchronize - when in Resynchronization mode, the estimated 
                                      size of data left to synchronize

* Data synchronized - when in Resynchronization mode, the estimated size of data 
                    that has already been synchronized

* Active PID - active process ID of a segment

* Coordinator reports status as - segment status as reported in the system catalog:
                           Up or Down

* Database status - status of Apache Cloudberry to incoming requests:
                Up, Down, or Suspended. A Suspended state means database 
                activity is temporarily paused while a segment transitions from 
                one state to another.

*****************************************************
EXAMPLES
*****************************************************

Show detailed status information of a Apache Cloudberry system:

   gpstate -s


Do a quick check for down segments in the coordinator host system catalog:

   gpstate -Q


Show information about mirror segment instances:

   gpstate -m


Show information about the standby coordinator configuration:

   gpstate -f


Show details of any current gpexpand:

   gpstate -x


Display the Cloudberry software version information:

   gpstate -i


*****************************************************
SEE ALSO
*****************************************************

gpstart, gplogfilter, gprecoverseg
