QPING(1)                   Grid Engine User Commands                  QPING(1)



[1mNAME[0m
       qping - check application status of Grid Engine daemons.


[1mSYNTAX[0m
       [1mqping [-help] [-noalias] [-ssl|-tcp] [ [ [-i <interval>] [-info] [-f] ][0m
       [1m| [ [-dump_tag tag [param] ] [-dump] [-nonewline]  ]  ]  <host>  <port>[0m
       [1m<name> <id>[0m


[1mDESCRIPTION[0m
       [4mQping[24m  is  used to validate the runtime status of a Grid Engine service
       daemon. The current Grid Engine implementation allows one to query  the
       GE_QMASTER daemon and any running GE_EXECD daemon. The qping command is
       used to send a SIM (Status Information Message) to the destination dae-
       mon.  The communication layer of the specified daemon will respond with
       a SIRM (Status Information  Response  Message)  which  contains  status
       information about the consulted daemon.

       The  qping  -dump  and  -dump_tag  options allowing an administrator to
       observe the communication protocol data flow of a Grid  Engine  service
       daemon.  The  qping -dump instruction must be started with root account
       and on the same host where the observed daemon is running.


[1mOPTIONS[0m
   [1m-f[0m
       Show full status information on each ping interval.

       [4mFirst[24m [4moutput[24m [4mLine:[24m The first output line shows the date and time of the
       request.

       [4mSIRM[24m  [4mversion:[24m  Internal version number of the SIRM (Status Information
       Response Message)

       [4mSIRM[24m [4mmessage[24m [4mid:[24m Current message id for this connection

       [4mstart[24m [4mtime:[24m Start time of daemon. The format is as follows:

       MM/DD/YYYY HH:MM:SS (seconds since 01.01.1970)

       [4mrun[24m [4mtime[24m [4m[s]:[24m Run time in seconds since start time

       [4mmessages[24m [4min[24m [4mread[24m [4mbuffer:[24m Nr.  of  buffered  messages  in  communication
       buffer.  The  messages  are buffered for the application (daemon). When
       this number grows too large the daemon is not able to handle  all  mes-
       sages sent to it.

       [4mmessages[24m [4min[24m [4mwrite[24m [4mbuffer:[24m Nr. of buffered messages in the communication
       write buffer. The messages are sent from the  application  (daemon)  to
       the  connected clients, but the communication layer wasn't able to send
       the messages yet. If this number grows  too  large,  the  communication
       layer isn't able to send them as fast as the application (daemon) wants
       the messages to be sent.

       [4mnr.[24m [4mof[24m [4mconnected[24m [4mclients:[24m  This  is  the  number  of  actual  connected
       clients to this daemon. This also implies the current qping connection.

       [4mstatus:[24m The status value of the  daemon.  This  value  depends  on  the
       application  which reply to the qping request.  If the application does
       not provide any information the status is 99999.  Here are the possible
       status information values for the Grid Engine daemons:

          qmaster:

             [4m0[24m There is no unusual timing situation.

             [4m1[24m  One or more threads has reached warning timeout. This may hap-
             pen when at least one thread does not increment  his  time  stamp
             for  a  not usual long time. A possible reason for this is a high
             workload for this thread.

             [4m2[24m One or more threads has reached error timeout. This may  happen
             when  at  least one thread has not incremented his time stamp for
             longer than 10 minutes.

             [4m3[24m The time measurement is not initialized.

          execd:

             [4m0[24m There is no unusual timing situation.

             [4m1[24m Dispatcher has reached warning timeout. This  may  happen  when
             the  dispatcher  does  not increment his time stamp for a unusual
             long time. A possible reason for this is a high workload.

             [4m2[24m Dispatcher has reached error timeout. This may happen when  the
             dispatcher  has not incremented his time stamp for longer than 10
             minutes.

             [4m3[24m The time measurement is not initialized.


       [4minfo:[24m Status message of the daemon. This value depends on the  applica-
       tion  which  reply  to  the qping request.  If the application does not
       provide any information the info message is "not available".  Here  are
       the possible status information values for the Grid Engine daemons:


          qmaster:

             The  info  message contains information about the qmaster threads
             followed by a thread state and time information. Each  time  when
             one  of  the  known threads pass through their main loop the time
             information is updated. Since the qmaster has two message threads
             every message thread updates the time. This means the timeout for
             the message thread (MT) can only occur when no message thread  is
             active anymore:

                THREAD_NAME: THREAD_STATE (THREAD_TIME)

                THREAD_NAME:
                   MAIN: Main thread
                   signaler: Signal thread
                   event_master: Event master thread
                   timer: Timer thread
                   worker: Worker thread
                   listener: Listener thread
                   scheduler: Scheduler thread
                   jvm: Java thread

                   The thread names above will be followed by a 3 digit number.

                THREAD_STATE:
                   R: Running
                   W: Warning
                   E: Error

                THREAD_TIME:
                   Time since last timestamp updating.

             After  the  dispatcher information follows an additional informa-
             tion string which describes the complete application status.

          execd:

             The info message contains information  for  the  execd  job  dis-
             patcher:
                dispatcher: STATE (TIME)

             STATE:
                R: Running
                W: Warning
                E: Error

             TIME:
                Time since last timestamp updating.

          After  the  thread  information  follows  an  additional information
          string which describes the application status.

    [4mMonitor:[24m If available, displays statistics on a thread. The data for  each
    thread is displayed in one line. The format of this line can be changed at
    any time. Only the master implements the monitoring.


   [1m-help[0m
       Prints a list of all options.


   [1m-i interval[0m
       Set qping interval time.

       The default interval time is one second. Qping will send a SIM  (Status
       Information Message) on each interval time.


   [1m-info[0m
       Show  full  status  information (see [1m-f [22mfor more information) and exit.
       The exit value 0 indicates no error. On errors qping returns with 1.


   [1m-noalias[0m
       Ignore host_aliases file, which  is  located  at  [4m<ge_root>/<cell>/com-[0m
       [4mmon/host_aliases.[24m   If  this  option is used it is not necessary to set
       any Grid Engine environment variable.


   [1m-ssl[0m
       This option can be used to specify an SSL (Secure Socket Layer) config-
       uration.  The  qping  will use the configuration to connect to services
       running SSL. If the SGE settings file is not sourced, you have  to  use
       the  -noalias  option  to  bypass the need for the SGE_ROOT environment
       variable.  The following environment variables are used to specify your
       certificates:
         SSL_CA_CERT_FILE - CA certificate file
         SSL_CERT_FILE    - certificates file
         SSL_KEY_FILE     - key file
         SSL_RAND_FILE    - rand file


   [1m-tcp[0m
       This option is used to select TCP/IP as the protocol used to connect to
       other services.


   [1m-nonewline[0m
       Dump output will not have a linebreak within a message and binary  mes-
       sages are not unpacked.


   [1m-dump[0m
       This option allows an administrator to observe the communication proto-
       col data flow of a Grid Engine service daemon. The qping -dump instruc-
       tion  must  be  started as root and on the same host where the observed
       daemon is running.

       The  output  is   written   to   stdout.   The   environment   variable
       "SGE_QPING_OUTPUT_FORMAT"  can  be  set  to hide columns, set a default
       column width or to set a hostname output format. The value of the envi-
       ronment  variable can be set to any combination of the following speci-
       fiers separated by a space character:
              "h:X"   -> hide column X
              "s:X"   -> show column X
              "w:X:Y" -> set width of column X to Y
              "hn:X"  -> set hostname output parameter X.
                         X values are "long" or "short"

       Start qping -help to see which columns are available.



   [1m-dump_tag tag [param][0m
       This option has the same the same meaning as  -dump,  but  can  provide
       more  information by specifying the debug level and message types qping
       should print:
          -dump_tag ALL <debug level>
             This option shows all possible debug messages (APP+MSG)  for  the
             debug  levels,  ERROR, WARNING, INFO, DEBUG and DPRINTF. The con-
             tacted service must support this kind of debugging.  This  option
             is not currently implemented.
          -dump_tag APP <debug level>
             This  option  shows only application debug messages for the debug
             levels, ERROR, WARNING, INFO, DEBUG and  DPRINTF.  The  contacted
             service  must support this kind of debugging.  This option is not
             currently implemented.
          -dump_tag MSG
             This option has the same behavior as the -dump option.


   [1mhost[0m
       Host where daemon is running.


   [1mport[0m
       Port which daemon has bound (used ge_qmaster/ge_execd port number).


   [1mname[0m
       Name of communication endpoint ("qmaster" or "execd"). A  communication
       endpoint  is  a  triplet  of  hostname/endpoint  name/endpoint id (e.g.
       hostA/qmaster/1 or subhost/qstat/4).


   [1mid[0m
       Id of communication endpoint ("1" for daemons)



[1mEXAMPLES[0m
       >qping master_host 31116 qmaster
       08/24/2004 16:41:15 endpoint master_host/qmaster/1 at port 31116 is up since 365761 seconds
       08/24/2004 16:41:16 endpoint master_host/qmaster/1 at port 31116 is up since 365762 seconds
       08/24/2004 16:41:17 endpoint master_host/qmaster/1 at port 31116 is up since 365763 seconds

       > qping -info master_host 31116 qmaster 1
       08/24/2004 16:42:47:
       SIRM version:             0.1
       SIRM message id:          1
       start time:               08/20/2004 11:05:14 (1092992714)
       run time [s]:             365853
       messages in read buffer:  0
       messages in write buffer: 0
       nr. of connected clients: 4
       status:                   0
       info:                     ok

       > qping -info execd_host 31117 execd 1
       08/24/2004 16:43:45:
       SIRM version:             0.1
       SIRM message id:          1
       start time:               08/20/2004 11:06:13 (1092992773)
       run time [s]:             365852
       messages in read buffer:  0
       messages in write buffer: 0
       nr. of connected clients: 2
       status:                   0
       info:                     ok



[1mENVIRONMENTAL VARIABLES[0m
       [1mGE_ROOT        [22mSpecifies the location of the Grid Engine standard  con-
                      figuration files.

       [1mGE_CELL        [22mIf set, specifies the default Grid Engine cell.

[1mSEE ALSO[0m
       [4mge_intro[24m(1), [4mGE_H_ALIASES[24m(5), [4mge_qmaster[24m(8), [4mge_execd[24m(8).

[1mCOPYRIGHT[0m
       See [4mge_intro[24m(1) for a full statement of rights and permissions.



GE 6.2u2                 $Date: 2008/04/30 09:11:03 $                 QPING(1)
