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's to track.

-larger-than CLUSTER_ID
    Track jobs for all 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.

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

-interval N
    Refresh interval in seconds. Defaults to 0.5 (half a second).

    WARNING: This affects key press detection for exiting. To exit immediately with long intervals, press CONTROL-C.

  Display Options

The following options control the output.

-groupby {batch, log, cluster}
    Specify how to group tracked jobs:

•   batch: Group by JobBatchName (default).

•   log: Group by job event log.

•   cluster: Group by 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 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: 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

$ 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

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.