| CONDOR_WATCH_Q(1) | HTCondor Manual | CONDOR_WATCH_Q(1) |
NAME¶
condor_watch_q - HTCondor Manual
Continually monitor and track the state of jobs.
SYNOPSIS¶
condor_watch_q [-help]
condor_watch_q [general options] [display options] [behavior options] [tracking options]
DESCRIPTION¶
Continually track the status of jobs over time updating the displayed output at job status change.
OPTIONS¶
General Options¶
Tracking Options¶
The following options control which jobs are tracked and how tracked jobs are discovered.
- -users USER [USER ...]
- Specify which user(s) jobs to track.
- -clusters CLUSTER_ID [CLUSTER_ID ...]
- Specify which ClusterId <href="../classad-attributes/job-classad-attributes.html#ClusterId">'s to track.
- -larger-than CLUSTER_ID
- Track jobs for all ClusterId <href="../classad-attributes/job-classad-attributes.html#ClusterId">'s greater than or equal to the specified CLUSTER_ID.
- -files FILE [FILE ...]
- Specify which job event log(s) to track jobs from.
- -batches BATCH_NAME [BATCH_NAME ...]
- Track jobs with the specified JobBatchName <href="../classad-attributes/job-classad-attributes.html#JobBatchName">.
- -collector COLLECTOR
- Specify which COLLECTOR to query to locate the SCHEDD, if needed.
- -schedd SCHEDD
- Specify which SCHEDD to discover which active jobs to track.
Behavior Options¶
- -exit GROUPER,JOB_STATUS[,EXIT_STATUS]
- Specify exit conditions:
- 1.
- GROUPER is one of all, any or none.
- 2.
- JOB_STATUS is one of active, done, idle, or held.
- 3.
- (Optional) EXIT_STATUS is a valid exit code.
Note:
- -exit-on-key-press/-no-exit-on-key-press
- Enable/disable tool exit via key press from keyboard. Enabled by default if connected to a tty.
- -interval N
- Refresh interval in seconds. Defaults to 0.5 (half a second).
Warning:
Display Options¶
The following options control the output.
- -groupby {batch, log, cluster}
- Specify how to group tracked jobs:
- batch: Group by JobBatchName <href="../classad-attributes/job-classad-attributes.html#JobBatchName"> (default).
- log: Group by job event log.
- cluster: Group by ClusterId <href="../classad-attributes/job-classad-attributes.html#ClusterId">.
- -display-exited/-no-display-exited
- Enable/disable displaying rows of jobs that have all exited the queue. Enabled by default.
- -exited-row-decay TIME[unit]
- Time since the last job in a job exited the queue before no longer than being displayed (if -no-display-exited specified). Default time is one week. Unless specified default unit is in weeks. See table 1.2 for unit specifier options.
- -decay-start-at-read/-no-decay-start-at-read
- Start all job exited row display decay timers at event read time rather than event write time. Disabled by default.
- -table/-no-table
- Enable/disable the table. Enabled by default.
- -progress/-no-progress
- Enable/disable the progress bar. Enabled by default.
- -row-progress/-no-row-progress
- Enable/disable the progress bar for each row. Enabled by default.
- -summary/-no-summary
- Enable/disable the summary line. Enabled by default.
- -summary-type {totals, percentages}
- Choose what to display on the summary line:
- totals: The number of jobs in each state (default).
- percentages: The percentage of jobs in each state of all tracked jobs.
- -updated-at/-no-updated-at
- Enable/disable the last time updated line. Enabled by default.
- -abbreviate/-no-abbreviate
- Enable/disable abbreviating path components to the shortest somewhat-unique prefix. Disabled by default.
- -color/-no-color
- Enable/disable colored output. Enabled by default if connected to a tty. Disabled on Windows if colorama <https://pypi.org/project/colorama/> is not available.
- -refresh/-no-refresh
- Enable/disable refreshing output. If refreshing is disabled, output will be appended instead. Enabled by default if connected to a tty.
GENERAL REMARKS¶
This tool monitors job event log files directly to determine the status of tracked jobs rather than querying the AP for required information.
A variety of options for output formatting are provided, including:
- colorized output
- tabular information
- progress bars
- text summaries.
Table 1.1 condor_watch_q character legend¶
| Character | Meaning |
| - | Job is idle |
| > | Job is transfering either input or output sandbox |
| = | Job is running |
| # | Job is completed |
| ! | Job is held, suspended, or removed |
Table 1.2 condor_watch_q exited row decay unit specifiers¶
| Unit | Conversion |
| s | Seconds |
| m | Minutes |
| h | Hours |
| d | Days |
| w | Weeks |
| M | Months |
| y | Years |
A minimal language for exiting when certain conditions are met by the tracked jobs is provided.
EXIT STATUS¶
0 - No jobs are found to track or stopped due to SIGINT (keyboard interrupt)
1 - Failure has occurred
Note:
EXAMPLES¶
Track all of the current users jobs:
$ condor_watch_q
Track a specific active cluster for the current user:
$ condor_watch_q -clusters 12345
Track users Jane's jobs:
# condor_watch_q -users jane
Track jobs in a specific job log file:
$ condor_watch_q -files /home/jane/events.log
Track jobs with a specified JobBatchName <href="../classad-attributes/job-classad-attributes.html#JobBatchName">
$ condor_watch_q -batches BatchOfJobsFromTuesday
Exit with 0 when all jobs are done or exit with 1 if any jobs are held:
$ condor_watch_q -exit all,done,0 -exit any,held,1
SEE ALSO¶
condor_q <href="../man-pages/condor_q.html">
AVAILABILITY¶
Linux, MacOS, Windows
Author¶
HTCondor Team
Copyright¶
1990-2026, Center for High Throughput Computing, Computer Sciences Department, University of Wisconsin-Madison, Madison, WI, US. Licensed under the Apache License, Version 2.0.
| March 16, 2026 |