Next: condor_qedit
Up: 11. Command Reference Manual
Previous: condor_procd
Contents
Index
Subsections
condor_q
Display information about jobs in queue
condor_q
[-help [Universe | State]]
condor_q
[-debug]
[general options]
[restriction list]
[output options]
[analyze options]
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 cluster and a process matches jobs which
belong to the specified cluster and have the specified process number
- a cluster without a process matches all jobs belonging
to the specified cluster
- an owner matches all jobs owned by the specified owner
- a -constraint expression which 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
owner restrictions are present, the job matches the list if it matches
one of the owner restrictions and at least one non-owner
restriction.
If the -long option is specified, condor_q displays 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
-format option, which displays attributes with a printf(3)
format.
Multiple -format options may be specified in the option list to display
several attributes of the job.
If neither -long or -format are specified, condor_q displays 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,
< = 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 -dag is specified, the OWNER column is replaced
with NODENAME for jobs started by the condor_dagman instance.
If the output option -run is specified, the ST, PRI, SIZE, and CMD
columns are replaced with:
- HOST(S)
- The host where the job is running.
If the output option -globus is 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 -goodput is 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 -io is 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 -cputime is 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 not shown. If the job has not produced a checkpoint,
this column contains 0+00:00:00.)
The -analyze or -better-analyze options 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 -verbose is specified
along with the -analyze option, the reason for failure is displayed on a
per machine basis.
-better-analyze differs from -analyze in 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-analyze also 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 -machine or
-mconstraint,
the values of relevant attributes of the machine ClassAd are also displayed.
- -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_schedd daemon.
- -pool centralmanagerhostname[:portnumber]
- (general option) Use the centralmanagerhostname as
the central manager to locate condor_schedd daemons.
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_schedd daemon.
This is most useful for debugging purposes.
The ClassAds appear as if
condor_q -long is 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_schedd daemon.
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_schedd daemon 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 -long option
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 not shown.
- -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-ID is 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 gt2
or 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 -xml or -long options.
Limiting the number of attributes increases the efficiency of the query.
- -format fmt attr
- (output option) Display attribute or
expression attr in 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 -long format.
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 -format option 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 -format option without format strings.
This output option does not work 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 autoformat option may be followed by a colon character
and formatting qualifiers to deviate the output formatting from
the default:
r print unevaluated, or raw values,
t add a tab character before each field instead of
the default space character,
n add a newline character after each field,
, add a comma character after each field,
l label each field,
V use %V rather than %v for formatting,
h print headings before the first line of output.
The newline and comma characters may not be 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
priority to consider user priority during the analysis
summary to show a one line summary for each job or machine
reverse to 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
priority to consider user priority during the analysis
summary to show a one line summary for each job or machine
reverse to 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_collector daemon.
This is most useful for debugging purposes.
The ClassAds appear as if condor_status -long is used.
- -userprios file
- (analyze option)
When doing matchmaking analysis with
priority, read user priorities from the file rather than the ones from
the condor_negotiator daemon.
This is most useful for debugging purposes or to
speed up analysis in situations where the condor_negotiator daemon is
slow to respond to condor_userprio requests. 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.
The default output from condor_q is 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_q
is strongly encouraged to use the -format option (described
above, examples given below).
Although -analyze provides 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 -io are 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 expression that option contains
JobStatus != 3 if the user wishes to avoid this condition.
The -format option provides a way to specify both the job attributes
and formatting of those attributes.
There must be only one conversion specification per -format option.
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_q and (second
set of output) using the -globus option:
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
condor_q will exit with a status value of 0 (zero) upon success,
and it will exit with the value 1 (one) upon failure.
Center for High Throughput Computing, University of Wisconsin-Madison
Copyright © 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.
Next: condor_qedit
Up: 11. Command Reference Manual
Previous: condor_procd
Contents
Index