Provided by: htcondor_8.4.2~dfsg.1-1build1_amd64 bug

Name

       condor_q Display - information about jobs in queue

Synopsis

       condor_q [-help [Universe | State]]

       condor_q[-debug] [general options] [restriction list] [output options] [analyze options]

Description

       condor_q  displays  information about jobs in the HTCondor job queue. By default, condor_q
       queries the local job queue, but this behavior may be modified by specifying  one  of  the
       general options.

       To  restrict  the  display to jobs of interest, a list of zero or more restriction options
       may be supplied. Each restriction may be one of:

          * a clusterand a processmatches jobs which belong to the specified cluster and have the
          specified process number

          * a clusterwithout a processmatches all jobs belonging to the specified cluster

          * an ownermatches all jobs owned by the specified owner

          *  a  -constraint  expressionwhich  matches all jobs that satisfy the specified ClassAd
          expression. If no restrictions are present in the list to specify  an  owner,  the  job
          matches  the  restriction  list  if it matches at least one restriction in the list. If
          ownerrestrictions are present, the job matches the  list  if  it  matches  one  of  the
          ownerrestrictions andat least one non-ownerrestriction.

       If  the  -longoption is specified, condor_qdisplays a long description of the queried jobs
       by printing the entire job ClassAd. The attributes of the job ClassAd may be displayed  by
       means  of  the -formatoption, which displays attributes with a  printf(3) format. Multiple
       -formatoptions may be specified in the option list to display several  attributes  of  the
       job.  If  neither  -longor  -formatare  specified,  condor_qdisplays a one line summary of
       information as follows:

       ID

          The cluster/process id of the condor job.

       OWNER

          The owner of the job.

       SUBMITTED

          The month, day, hour, and minute the job was submitted to the queue.

       RUN_TIME

          Wall-clock time accumulated by the job to date in days, hours, minutes, and seconds.

       ST

          Current status of the job, which varies somewhat according to the job universe and  the
          timing of updates. H = on hold, R = running, I = idle (waiting for a machine to execute
          on), C = completed, X = removed, S = suspended (execution of a running job  temporarily
          suspended  on  execute  node),  <  =  transferring  input (or queued to do so), and > =
          transferring output (or queued to do so).

       PRI

          User specified priority of the job,  displayed  as  an  integer,  with  higher  numbers
          corresponding to greater priority.

       SIZE

          The  peak  amount  of  memory  in  Mbytes  consumed by the job; note this value is only
          refreshed periodically. The actual  value  reported  is  taken  from  the  job  ClassAd
          attribute   MemoryUsage if this attribute is defined, and from job attribute  ImageSize
          otherwise.

       CMD

          The name of the executable.

       If the output option -dagis specified, the OWNER column is replaced with NODENAME for jobs
       started by the condor_dagmaninstance.

       If  the  output  option  -runis specified, the ST, PRI, SIZE, and CMD columns are replaced
       with:

       HOST(S)

          The host where the job is running.

       If the output option -globusis specified, the ST, PRI, SIZE, and CMD columns are  replaced
       with:

       STATUS

          The state that HTCondor believes the job is in. Possible values are

          PENDING

             The job is waiting for resources to become available in order to run.

          ACTIVE

             The job has received resources, and the application is executing.

          FAILED

             The  job terminated before completion because of an error, user-triggered cancel, or
             system-triggered cancel.

          DONE

             The job completed successfully.

          SUSPENDED

             The job has been suspended. Resources which were allocated for  this  job  may  have
             been released due to a scheduler-specific reason.

          UNSUBMITTED

             The  job  has  not been submitted to the scheduler yet, pending the reception of the
             GLOBUS_GRAM_PROTOCOL_JOB_SIGNAL_COMMIT_REQUEST signal from a client.

          STAGE_IN

             The job manager is staging in files, in order to run the job.

          STAGE_OUT

             The job manager is staging out files generated by the job.

          UNKNOWN

       MANAGER

          A guess at what remote batch system is running the job. It is a guess, because HTCondor
          looks  at  the Globus jobmanager contact string to attempt identification. If the value
          is fork, the job is running on the remote host without a jobmanager. Values may also be
          condor, lsf, or pbs.

       HOST

          The host to which the job was submitted.

       EXECUTABLE

          The job as specified as the executable in the submit description file.

       If the output option -goodputis specified, the ST, PRI, SIZE, and CMD columns are replaced
       with:

       GOODPUT

          The percentage of RUN_TIME for this job which has been saved in  a  checkpoint.  A  low
          GOODPUT  value  indicates  that  the job is failing to checkpoint. If a job has not yet
          attempted a checkpoint, this column contains  [?????] .

       CPU_UTIL

          The ratio of CPU_TIME to RUN_TIME for checkpointed work. A low CPU_UTIL indicates  that
          the  job is not running efficiently, perhaps because it is I/O bound or because the job
          requires more memory than available on the remote workstations.  If  the  job  has  not
          (yet) checkpointed, this column contains  [??????] .

       Mb/s

          The network usage of this job, in Megabits per second of run-time.

       If  the  output  option  -iois  specified, the ST, PRI, SIZE, and CMD columns are replaced
       with:

          READ The total number of bytes the application has read from files and sockets.

          WRITE The total number of bytes the application has written to files and sockets.

          SEEK The total number of seek operations the application has performed on files.

          XPUT The effective throughput (average bytes read and  written  per  second)  from  the
          application's point of view.

          BUFSIZE The maximum number of bytes to be buffered per file.

          BLOCKSIZE The desired block size for large data transfers.

       These  fields  are updated when a job produces a checkpoint or completes. If a job has not
       yet produced a checkpoint, this information is not available.

       If the output option -cputimeis specified, the RUN_TIME column is replaced with:

       CPU_TIME

          The remote CPU time accumulated by the  job  to  date  (which  has  been  stored  in  a
          checkpoint)  in  days,  hours,  minutes, and seconds. (If the job is currently running,
          time accumulated during the current run is notshown. If the  job  has  not  produced  a
          checkpoint, this column contains 0+00:00:00.)

       The  -analyzeor  -better-analyzeoptions  may be used to determine why certain jobs are not
       running by performing an analysis on a per machine basis for each machine in the pool. The
       reasons   may  vary  among  failed  constraints,  insufficient  priority,  resource  owner
       preferences and prevention of preemption by the   PREEMPTION_REQUIREMENTS  expression.  If
       the  analyze  option  -verboseis  specified  along with the -analyzeoption, the reason for
       failure is displayed on a per machine basis. -better-analyzediffers from  -analyzein  that
       it  will  do  matchmaking  analysis  on jobs even if they are currently running, or if the
       reason they are not running is not due to matchmaking. -better-analyzealso  produces  more
       thorough  analysis  of  complex  Requirements and shows the values of relevant job ClassAd
       attributes. When only a single machine is being analyzed via -machineor -mconstraint,  the
       values of relevant attributes of the machine ClassAd are also displayed.

Options

       -debug

          Causes  debugging  information  to  be  sent  to   stderr  ,  based on the value of the
          configuration variable  TOOL_DEBUG

       -global

          (general option) Queries all job queues in the pool.

       -submitter submitter

          (general option) List jobs of a specific submitter.

       -name name

          (general option) Query only the job queue of the named condor_schedddaemon.

       -pool centralmanagerhostname[:portnumber]

          (general option)  Use  the  centralmanagerhostnameas  the  central  manager  to  locate
          condor_schedddaemons.  The  default  is  the   COLLECTOR_HOST  ,  as  specified  in the
          configuration.

       -jobads file

          (general option) Display jobs from a list of ClassAds from a file, instead of the  real
          ClassAds  from the condor_schedddaemon. This is most useful for debugging purposes. The
          ClassAds appear as if condor_q -longis used with the header stripped out.

       -userlog file

          (general option) Display jobs, with job  information  coming  from  a  job  event  log,
          instead of from the real ClassAds from the condor_schedddaemon. This is most useful for
          automated testing of the status of jobs known to be in the given job event log, because
          it  reduces  the load on the condor_schedd. A job event log does not contain all of the
          job information, so some fields in the normal output of condor_q will be blank.

       -autocluster

          (output option) Output condor_schedddaemon auto  cluster  information.  For  each  auto
          cluster, output the unique ID of the auto cluster along with the number of jobs in that
          auto cluster. This option is intended to be  used  together  with  the  -longoption  to
          output  the  ClassAds  representing  auto  clusters.  The  ClassAds can then be used to
          identify or classify the demand for sets of machine resources, which will be useful  in
          the on-demand creation of execute nodes for glidein services.

       -cputime

          (output  option)  Instead  of wall-clock allocation time (RUN_TIME), display remote CPU
          time accumulated by the job to date in days, hours, minutes, and seconds. If the job is
          currently running, time accumulated during the current run is notshown.

       -currentrun

          (output option) Normally, RUN_TIME contains all the time accumulated during the current
          run plus all previous runs. If this option is specified,  RUN_TIME  only  displays  the
          time accumulated so far on this current run.

       -dag <DAG-ID>

          (output  option)  Display  DAG  node  jobs under their DAGMan instance. Child nodes are
          listed using indentation to show the structure of the DAG. When the  optional  DAG-IDis
          specified, display all jobs in the DAG.

       -expert

          (output option) Display shorter error messages.

       -globus

          (output  option)  Get information only about jobs submitted to grid resources described
          as gt2or gt5.

       -goodput

          (output option) Display job goodput statistics.

       -help [Universe | State]

          (output option) Print usage info, and additionally print job universes or job states.

       -hold

          (output option) Get information about jobs in the hold state. Also  displays  the  time
          the  job  was  placed  into the hold state and the reason why the job was placed in the
          hold state.

       -limit Number

          (output option) Limit the number of items output to Number.

       -io

          (output option) Display job input/output summaries.

       -long

          (output option) Display entire job ClassAds in long format.

       -run

          (output option) Get information about running jobs.

       -stream-results

          (output option) Display results as jobs are fetched from  the  job  queue  rather  than
          storing  results  in  memory  until  all jobs have been fetched. This can reduce memory
          consumption when fetching large numbers of  jobs,  but  if  condor_q  is  paused  while
          displaying results, this could result in a timeout in communication with condor_schedd.

       -totals

          (output option) Display only the totals.

       -version

          (output option) Print the HTCondor version and exit.

       -wide

          (output  option)  If  this  option  is specified, and the command portion of the output
          would cause the output to extend beyond 80 columns, display beyond the 80 columns.

       -xml

          (output option) Display entire job ClassAds in XML format.  The  XML  format  is  fully
          defined  in  the  reference manual, obtained from the ClassAds web page, with a link at
          http://research.cs.wisc.edu/htcondor/research.html.

       -attributes Attr1[,Attr2 ... ]

          (output option) Explicitly list the attributes, by name  in  a  comma  separated  list,
          which  should  be  displayed when using the -xmlor -longoptions. Limiting the number of
          attributes increases the efficiency of the query.

       -format fmt attr

          (output option) Display attribute or expression  attrin  format  fmt.  To  display  the
          attribute  or  expression the format must contain a single  printf(3) -style conversion
          specifier. Attributes must be from the job ClassAd. Expressions are ClassAd expressions
          and  may  refer  to attributes in the job ClassAd. If the attribute is not present in a
          given ClassAd and cannot be parsed as an expression, then the  format  option  will  be
          silently  skipped.  %r  prints the unevaluated, or raw values. The conversion specifier
          must match the type of the attribute or expression. %s is suitable for strings such  as
          Owner  , %d for integers such as  ClusterId , and %f for floating point numbers such as
          RemoteWallClockTime . %v identifies the type of the  attribute,  and  then  prints  the
          value  in  an  appropriate  format.  %V  identifies the type of the attribute, and then
          prints the value in an appropriate format as it would appear in the -longformat. As  an
          example, strings used with %V will have quote marks. An incorrect format will result in
          undefined behavior. Do not use more than one conversion specifier in  a  given  format.
          More  than  one  conversion  specifier  will  result  in  undefined behavior. To output
          multiple attributes repeat the -formatoption once  for  each  desired  attribute.  Like
          printf(3) style formats, one may include other text that will be reproduced directly. A
          format without any conversion specifiers may be specified, but an  attribute  is  still
          required. Include n to specify a line break.

       -autoformat[:tn,lVh] attr1 [attr2 ...]or -af[:tn,lVh] attr1 [attr2 ...]

          (output  option)  Display  attribute(s)  or  expression(s)  formatted  in a default way
          according to attribute types. This option takes an arbitrary number of attribute  names
          as  arguments,  and  prints  out  their  values,  with a space between each value and a
          newline character after the last value. It is like  the  -formatoption  without  format
          strings.  This  output option does notwork in conjunction with any of the options -run,
          -currentrun, -hold, -globus, -goodput, or -io.

          It is assumed that no attribute names begin with a dash character,  so  that  the  next
          word that begins with dash is the start of the next option. The autoformatoption may be
          followed by  a  colon  character  and  formatting  qualifiers  to  deviate  the  output
          formatting from the default:

          rprint unevaluated, or raw values,

          tadd a tab character before each field instead of the default space character,

          nadd a newline character after each field,

          ,add a comma character after each field,

          llabel each field,

          Vuse %V rather than %v for formatting,

          hprint headings before the first line of output.

          The newline and comma characters may notbe used together.

       -analyze[:<qual>]

          (analyze  option)  Perform  a  matchmaking  analysis  on why the requested jobs are not
          running. First a simple analysis determines if the job is not running due to not  being
          in  a runnable state. If the job is in a runnable state, then this option is equivalent
          to -better-analyze. <qual>is a comma separated list containing one or more of

          priorityto consider user priority during the analysis

          summaryto show a one line summary for each job or machine

          reverseto analyze machines, rather than jobs

       -better-analyze[:<qual>]

          (analyze option) Perform a more detailed matchmaking analysis  to  determine  how  many
          resources  are available to run the requested jobs. This option is never meaningful for
          Scheduler universe jobs and only meaningful for grid universe jobs  doing  matchmaking.
          <qual>is a comma separated list containing one or more of

          priorityto consider user priority during the analysis

          summaryto show a one line summary for each job or machine

          reverseto analyze machines, rather than jobs

       -machine name

          (analyze  option)  When  doing matchmaking analysis, analyze only machine ClassAds that
          have slot or machine names that match the given name.

       -mconstraint expression

          (analyze option) When doing matchmaking analysis, match  only  machine  ClassAds  which
          match the ClassAd expression constraint.

       -slotads file

          (analyze  option)  When  doing  matchmaking analysis, use the machine ClassAds from the
          file instead of the ones from the  condor_collectordaemon.  This  is  most  useful  for
          debugging purposes. The ClassAds appear as if condor_status-longis used.

       -userprios file

          (analyze  option)  When  doing matchmaking analysis with priority, read user priorities
          from the file rather than the ones  from  the  condor_negotiatordaemon.  This  is  most
          useful  for  debugging  purposes  or  to  speed  up  analysis  in  situations where the
          condor_negotiatordaemon is slow to respond to condor_userpriorequests. The file  should
          be in the format produced by condor_userprio-long.

       -nouserprios

          (analyze option) Do not consider user priority during the analysis.

       -reverse

          (analyze option) Analyze machine requirements against jobs.

       -verbose

          (analyze  option)  When doing analysis, show progress and include the names of specific
          machines in the output.

General Remarks

       The default output from condor_qis formatted to be human readable, not script readable. In
       an  effort  to  make  the  output fit within 80 characters, values in some fields might be
       truncated. Furthermore, the HTCondor Project can (and does) change the formatting of  this
       default  output as we see fit. Therefore, any script that is attempting to parse data from
       condor_qis strongly encouraged to use the -formatoption (described above,  examples  given
       below).

       Although  -analyzeprovides  a  very good first approximation, the analyzer cannot diagnose
       all possible situations,  because  the  analysis  is  based  on  instantaneous  and  local
       information.  Therefore,  there  are  some  situations such as when several submitters are
       contending for resources, or if the  pool  is  rapidly  changing  state  which  cannot  be
       accurately diagnosed.

       Options  -goodput, -cputime, and -ioare most useful for standard universe jobs, since they
       rely on values computed when a job produces a checkpoint.

       It is possible to to hold jobs that are in the X state.  To  avoid  this  it  is  best  to
       construct  a -constraint expressionthat option contains  JobStatus != 3 if the user wishes
       to avoid this condition.

Examples

       The -formatoption provides a way to specify both the  job  attributes  and  formatting  of
       those attributes. There must be only one conversion specification per -formatoption. As an
       example, to list only Jane Doe's jobs in the queue, choosing to print and format only  the
       owner of the job, the command line arguments for the job, and the process ID of the job:

       %condor_q   -submitter jdoe -format "%s" Owner -format " %s " Args -format "ProcId = %d\n"
       ProcId
       jdoe 16386 2800 ProcId = 0
       jdoe 16386 3000 ProcId = 1
       jdoe 16386 3200 ProcId = 2
       jdoe 16386 3400 ProcId = 3
       jdoe 16386 3600 ProcId = 4
       jdoe 16386 4200 ProcId = 7

       To display only the JobID's of Jane Doe's jobs you can use the following.

       %condor_q  -submitter jdoe -format "%d." ClusterId -format "%d\n" ProcId
       27.0
       27.1
       27.2
       27.3
       27.4
       27.7

       An example that shows the difference (first set of output) between not using an option  to
       condor_qand (second set of output) using the -globusoption:

       ID      OWNER            SUBMITTED     RUN_TIME ST PRI SIZE CMD
       100.0   smith          12/11 13:20   0+00:00:02 R  0   0.0  sleep 10

       1 jobs; 0 idle, 1 running, 0 held

       ID      OWNER          STATUS  MANAGER  HOST                EXECUTABLE
       100.0   smith         ACTIVE fork     grid.example.com       /bin/sleep

       An example that shows the analysis in summary format:

       $ condor_q  -analyze:summary

       -- Submitter: submit-1.chtc.wisc.edu : <192.168.100.43:9618?sock=11794_95bb_3> :
       submit-1.chtc.wisc.edu
       Analyzing matches for 5979 slots
                  Autocluster  Matches    Machine     Running  Serving
       JobId     Members/Idle  Reqmnts  Rejects Job  Users Job Other User Avail Owner
       ---------- ------------ -------- ------------ ---------- ---------- ----- -----
       25764522.0  7/0             5910        820   7/10       5046        34   smith
       25764682.0  9/0             2172        603   9/9        1531        29   smith
       25765082.0  18/0            2172        603   18/9       1531        29   smith
       25765900.0  1/0             2172        603   1/9        1531        29   smith

       An example that shows summary information by machine:

       $ condor_q  -ana:sum,rev

       --    Submitter:    s-1.chtc.wisc.edu    :    <192.168.100.43:9618?sock=11794_95bb_3>    :
       s-1.chtc.wisc.edu
       Analyzing matches for 2885 jobs
                                      Slot  Slot's Req    Job's Req     Both
       Name                            Type  Matches Job  Matches Slot    Match %
       ------------------------        ---- ------------  ------------ ----------
       slot1@INFO.wisc.edu             Stat         2729  0                  0.00
       slot2@INFO.wisc.edu             Stat         2729  0                  0.00
       slot1@aci-001.chtc.wisc.edu     Part            0  2793               0.00
       slot1_1@a-001.chtc.wisc.edu     Dyn          2644  2792              91.37
       slot1_2@a-001.chtc.wisc.edu     Dyn          2623  2601              85.10
       slot1_3@a-001.chtc.wisc.edu     Dyn          2644  2632              85.82
       slot1_4@a-001.chtc.wisc.edu     Dyn          2644  2792              91.37
       slot1@a-002.chtc.wisc.edu       Part            0  2633               0.00
       slot1_10@a-002.chtc.wisc.edu    Den          2623  2601              85.10

Exit Status

       condor_qwill exit with a status value of 0 (zero) upon success, and it will exit with  the
       value 1 (one) upon failure.

Author

       Center for High Throughput Computing, University of Wisconsin-Madison

Copyright

       Copyright   (C)   1990-2015  Center  for  High  Throughput  Computing,  Computer  Sciences
       Department, University of Wisconsin-Madison, Madison, WI. All  Rights  Reserved.  Licensed
       under the Apache License, Version 2.0.

                                          February 2016                               condor_q(1)