condor_watch_q - Man Page

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.

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

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