toil.utils.toilStatus

Tool for reporting on job status.

Module Contents

Classes

ToilStatus

Tool for reporting on job status.

Functions

main()

Reports the state of a Toil workflow.

Attributes

logger

toil.utils.toilStatus.logger

class toil.utils.toilStatus.ToilStatus(jobStoreName, specifiedJobs=None)

Tool for reporting on job status.

Parameters:

• jobStoreName (str)

• specifiedJobs (Optional[List[str]])

print_dot_chart()

Print a dot output graph representing the workflow.

Return type:

None

printJobLog()

Takes a list of jobs, finds their log files, and prints them to the terminal.

Return type:

None

printJobChildren()

Takes a list of jobs, and prints their successors.

Return type:

None

printAggregateJobStats(properties, childNumber)

Prints each job’s ID, log file, remaining tries, and other properties.

Parameters:

• properties (List[Set[str]]) – A set of string flag names for each job in self.jobsToReport.

• childNumber (List[int]) – A list of child counts for each job in self.jobsToReport.

Return type:

None

report_on_jobs()

Gathers information about jobs such as its child jobs and status.

Returns jobStats:

Dict containing some lists of jobs by category, and some lists of job properties for each job in self.jobsToReport.

Return type:

Dict[str, Any]

static getPIDStatus(jobStoreName)

Determine the status of a process with a particular local pid.

Checks to see if a process exists or not.

Returns:

A string indicating the status of the PID of the workflow as stored in the jobstore.

Return type:

str

Parameters:

jobStoreName (str)

static getStatus(jobStoreName)

Determine the status of a workflow.

If the jobstore does not exist, this returns ‘QUEUED’, assuming it has not been created yet.

Checks for the existence of files created in the toil.Leader.run(). In toil.Leader.run(), if a workflow completes with failed jobs, ‘failed.log’ is created, otherwise ‘succeeded.log’ is written. If neither of these exist, the leader is still running jobs.

Returns:

A string indicating the status of the workflow. [‘COMPLETED’, ‘RUNNING’, ‘ERROR’, ‘QUEUED’]

Return type:

str

Parameters:

jobStoreName (str)

print_bus_messages()

Goes through bus messages, returns a list of tuples which have correspondence between PID on assigned batch system and

Prints a list of the currently running jobs

Return type:

None

fetchRootJob()

Fetches the root job from the jobStore that provides context for all other jobs.

Exactly the same as the jobStore.loadRootJob() function, but with a different exit message if the root job is not found (indicating the workflow ran successfully to completion and certain stats cannot be gathered from it meaningfully such as which jobs are left to run).

Raises:

JobException – if the root job does not exist.

Return type:

toil.job.JobDescription

fetchUserJobs(jobs)

Takes a user input array of jobs, verifies that they are in the jobStore and returns the array of jobsToReport.

Parameters:

jobs (list) – A list of jobs to be verified.

Returns jobsToReport:

A list of jobs which are verified to be in the jobStore.

Return type:

List[toil.job.JobDescription]

traverseJobGraph(rootJob, jobsToReport=None, foundJobStoreIDs=None)

Find all current jobs in the jobStore and return them as an Array.

Parameters:

• rootJob (toil.job.JobDescription) – The root job of the workflow.

• jobsToReport (list) – A list of jobNodes to be added to and returned.

• foundJobStoreIDs (set) – A set of jobStoreIDs used to keep track of jobStoreIDs encountered in traversal.

Returns jobsToReport:

The list of jobs currently in the job graph.

Return type:

List[toil.job.JobDescription]

toil.utils.toilStatus.main()

Reports the state of a Toil workflow.

Return type:

None