Job Monitoring & Rerun System
Relevant source files
The following files were used as context for generating this wiki page:
The Job Monitoring & Rerun System is a centralized framework within the DXKB platform responsible for tracking, managing, and re-executing bioinformatics service tasks. It provides users with real-time visibility into the status of submitted jobs, access to execution logs (standard output and error), and a mechanism to re-populate service forms with parameters from previous executions.
The system interacts with the AppService backend to fetch filtered task lists, summaries, and detailed job metadata. It supports various lifecycle actions such as killing active tasks, navigating to output workspaces, and initiating a "rerun" workflow that bridges historical job data with modern service interfaces.
System Architecture & Data Flow
The monitoring system is built on a polling architecture that adjusts its frequency based on the presence of active jobs. It utilizes React Query for data synchronization and a centralized state management approach for filtering and selection.
Core Components
- JobsBrowser: The primary container for the job management UI, handling sorting, filtering, and high-level actions.
- JobDetailsPanel: A sidebar component that displays specific metadata and provides expandable sections for
stdoutandstderr. - Rerun Utility: A set of helper functions that parse historical job parameters and redirect users to the appropriate service pages.
Job Monitoring Flow
The following diagram illustrates the lifecycle of job data from the backend to the user interface.
Job Status Lifecycle
Jobs transition through multiple states, categorized into "Active" and "Terminal" statuses. The system uses an active polling interval (typically 10 seconds) when active jobs are detected to ensure the UI remains current.
Status Definitions
| Status | Category | Description |
|---|---|---|
pending | Active | Job is accepted but not yet assigned to a worker. |
queued | Active | Job is in the execution queue. |
running | Active | Job is currently being processed. |
in-progress | Active | Alias for running; used by specific service backends. |
completed | Terminal | Job finished successfully. |
failed | Terminal | Job terminated due to application error. |
error | Terminal | Job failed due to system or infrastructure error. |
cancelled | Terminal | Job was manually terminated by the user. |
Sources: src/lib/jobs/constants.ts:11-28, src/lib/jobs/constants.ts:41-46
Detailed Job Inspection
The JobDetailsPanel provides a technical breakdown of a specific execution. It utilizes the useJobOutput hook to fetch logs only when a section is expanded, optimizing network bandwidth.
Execution Metadata
The system displays the following fields derived from the JobListItem type:
- Service & Application: Human-readable labels mapped from internal IDs (e.g.,
GenomeAssembly2to "Genome Assembly"). - Timestamps: Detailed tracking of submission, start, and completion times, formatted to the user's local timezone.
- Output Path: A direct link to the workspace directory containing results.
Log Management
Log outputs are retrieved via the AppService.fetchJobOutput endpoint. The implementation converts a job's technical ID and output type (stdout or stderr) into a secure request using OAuth headers.
Rerun System Logic
The rerun system allows users to recreate the state of a service form based on a previous job's parameters. This is handled by the rerunJob utility and the useRerunForm hook.
Parameter Transformation
When a user clicks "Rerun", the system:
- Extracts the
parametersobject from the existing job. - Maps the
appID to a specific UI route (e.g.,Variation->/services/variation-analysis). - Stores the parameters in
sessionStoragewith a unique UUID key. - Redirects the user to the service page with a
rerun_keyquery parameter.
Library Reconstruction
Service forms often require complex library structures (paired-end, single-read, or SRA). The rerun-utility.ts contains specialized logic to rebuild these from the flat JSON structures stored in job history.
| Function | Purpose |
|---|---|
buildPairedLibraries | Reconstructs read1 and read2 pairs into Library objects. |
buildSingleLibraries | Maps single files and their associated platforms (Illumina, Nanopore, etc.). |
buildSraLibraries | Extracts SRR accessions from srr_ids or srr_libs. |
normalizeToArray | Ensures backend responses (which may be single objects or arrays) are consistently iterable. |
Sources: [src/lib/rerun-utility.ts:130-150] (implied), src/lib/tests/rerun-utility.test.ts:58-130, src/app/services/(genomics)/genome-assembly/page.tsx:112-125
Formatting & Utilities
To maintain consistency across the UI, a set of formatting utilities is used to transform raw backend data into human-readable strings.
- Service Mapping: The
formatServiceNamefunction uses theserviceNamesconstant to map technical identifiers likeHomologyto "BLAST" orMetaCATSto "Meta-CATS". - Elapsed Time:
formatElapsedSecondsconverts raw seconds into a shorthand duration string (e.g.,65->1m5s). - Timestamps:
formatUnixTimestampconverts Unix epoch integers into formatted locale strings (e.g.,MM/DD/YY, H:MM AM/PM).
Sources: src/lib/jobs/formatting.ts:10-45, src/lib/jobs/constants.ts:59-88
Summary
The Job Monitoring & Rerun System provides a robust interface for managing the lifecycle of bioinformatics tasks. By combining real-time status polling, conditional log loading, and a sophisticated rerun mechanism that reconstructs complex input libraries, the system ensures that users can efficiently track their research progress and reproduce past results with minimal manual effort.