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

            -help
                Display the help message and exit.

            -debug
                Causes debugging information to be sent to stderr.

  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:
                            JOB_STATUS active status represents all jobs the AP (idle, running, and held)

            -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.

  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">.

            -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

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:
        Any valid exit status can be returned when a condition set by -exit is met.

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.