Skip to content

Nextflow Command and Log Files

Directory Structure

logs/
├── create_sv_output_*.log    # Structured JSON audit log from modules/utils/create_sv_output.py
├── nextflow.log              # A log file generated by nextflow
├── report.html               # A visual HTML report of the workflow execution, including task durations, resource usage, and statuses
├── timeline.html             # A timeline visualization showing when each pipeline process started and finished
├── trace.tsv                 # Per-process execution trace with task ID, name, status, exit code, and timing
├── process_manifest.txt      # Summary manifest listing which processes succeeded/failed with exit codes
└── 00/
    └── a80c5c6b6654950042a976836ff441
        ├── .command.begin    # Timestamp file marking the start of a process
        ├── .command.err      # Captures standard error output from the process
        ├── .command.log      # Logs process execution messages from Nextflow
        ├── .command.out      # Captures standard output from the process
        ├── .command.run      # Execution metadata (exit status, runtime, resources)
        └── .command.sh       # The shell script containing the exact commands executed

Description

The logs/ folder contains detailed logs and command scripts for each Nextflow process.

File Descriptions

.command.begin

Marks the start time of a process.

.command.err

Captures standard error messages generated by the process.

.command.log

General execution logs from Nextflow for the process.

.command.out

Captures standard output of the process.

.command.run

Metadata about process execution including:

  • Exit code
  • Runtime duration
  • Resource usage

.command.sh

The shell script that Nextflow runs; contains the exact commands for the process.

nextflow.log

A log file generated by Nextflow summarizing all execution steps

create_sv_output_*.log

A structured JSON log written by modules/utils/create_sv_output.py. It records:

  • every skipped record handled by load_records()
  • every modified record handled by load_records()
  • per-source summaries with counts of skipped and modified rows

report.html

A visual HTML report of the workflow execution, including task durations, resource usage, and statuses (see nextflow documentation)

timeline.html

A timeline visualization showing when each pipeline process started and finished (see nextflow documentation)

trace.tsv

A tab-separated file generated by Nextflow containing per-process execution data. Each row represents one process execution with the following columns:

  • task_id — Unique task identifier
  • name — Process name (e.g. sniffles, minimap2)
  • status — Execution status (COMPLETED, FAILED, CACHED, ABORTED)
  • exit — Process exit code (0 = success)
  • start — Timestamp when the process started
  • complete — Timestamp when the process finished
  • duration — Wall-clock duration
  • realtime — Actual CPU time

process_manifest.txt

A human-readable manifest generated at pipeline completion (both on success and failure). It includes:

  • Pipeline metadata — overall status (SUCCESS/FAILED), duration, and error message (if any)
  • Full trace data — copied from trace.tsv for a self-contained record
  • Summary counts — number of completed, failed, cached, and aborted processes
  • Failed process listing — names and exit codes of all processes that failed

This file is the primary artifact for verifying which analysis steps ran and which did not — essential for ensuring results are complete before regulatory reporting.

Error Handling Strategy

The pipeline uses errorStrategy = 'terminate' globally (nextflow.config). If any process fails, the pipeline stops immediately — no downstream tasks are started. This prevents partial results from being mistaken for complete results.

Log Copying Behavior

Process logs (.command.* files) are copied from the Nextflow work/ directory to data/outputs/logs/ regardless of whether the pipeline succeeds or fails. This ensures failure diagnostics are always available even after the work directory is cleaned up.

Usage

These log files are useful for:

  • Debugging - Identify what went wrong when a process fails
  • Reproducibility - See exact commands that were executed
  • Performance monitoring - Check resource usage and execution times
  • Troubleshooting - Review error messages and output

Accessing Logs

During execution, logs reside in the Nextflow work/ directory under each process-specific subdirectory. At pipeline completion (success or failure), all .command.* files are automatically copied to data/outputs/logs/. After a successful run with --clean_work true, the work/ directory is removed, but all logs are preserved in the output directory.

To quickly check which processes failed, inspect data/outputs/logs/process_manifest.txt.

See Also