| 1 | package NBI::Manifest; | ||||||||||||||||||||||||||||||||||||||
| 2 | #ABSTRACT: Provenance record for a single nbilaunch job run | ||||||||||||||||||||||||||||||||||||||
| 3 | # | ||||||||||||||||||||||||||||||||||||||
| 4 | # NBI::Manifest - Reads and writes JSON provenance records for nbilaunch. | ||||||||||||||||||||||||||||||||||||||
| 5 | # | ||||||||||||||||||||||||||||||||||||||
| 6 | # DESCRIPTION: | ||||||||||||||||||||||||||||||||||||||
| 7 | # Serialises every input, parameter, output, and Slurm resource used by a | ||||||||||||||||||||||||||||||||||||||
| 8 | # single launcher invocation to a JSON file that lives alongside the results. | ||||||||||||||||||||||||||||||||||||||
| 9 | # Written in two phases: | ||||||||||||||||||||||||||||||||||||||
| 10 | # 1. At submission (by nbilaunch): status "submitted", no job ID yet. | ||||||||||||||||||||||||||||||||||||||
| 11 | # 2. At job end (by injected shell): status "success" or "failure", | ||||||||||||||||||||||||||||||||||||||
| 12 | # exit code, completion time, and checksums are patched in. | ||||||||||||||||||||||||||||||||||||||
| 13 | # | ||||||||||||||||||||||||||||||||||||||
| 14 | # The on-disk format uses JSON::PP with canonical key ordering so that | ||||||||||||||||||||||||||||||||||||||
| 15 | # diffs between runs are clean. | ||||||||||||||||||||||||||||||||||||||
| 16 | # | ||||||||||||||||||||||||||||||||||||||
| 17 | # RELATIONSHIPS: | ||||||||||||||||||||||||||||||||||||||
| 18 | # - Created by NBI::Launcher->build() and written by bin/nbilaunch. | ||||||||||||||||||||||||||||||||||||||
| 19 | # - The injected shell function _nbi_manifest_update patches the file | ||||||||||||||||||||||||||||||||||||||
| 20 | # in-place using a perl one-liner (no jq dependency). | ||||||||||||||||||||||||||||||||||||||
| 21 | # - Complex launchers can chain jobs via NBI::Manifest->load() to read | ||||||||||||||||||||||||||||||||||||||
| 22 | # a previous run's output paths. | ||||||||||||||||||||||||||||||||||||||
| 23 | # | ||||||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||||||
| 25 | 2 | ▶ | use 5.012; | ||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||
| 26 | 2 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||
| 27 | 2 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||
| 28 | 2 | ▶ | use Carp qw(confess); | ||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||
| 29 | 2 | ▶ | use JSON::PP; | ||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||
| 30 | 2 | ▶ | use POSIX qw(strftime); | ||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||||||||||||||
| 32 | 2 | $NBI::Manifest::VERSION = $NBI::Slurm::VERSION; | |||||||||||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||||||||||||
| 34 | # Fields serialised to JSON (in this order, for readability). | ||||||||||||||||||||||||||||||||||||||
| 35 | # The internal _path field is excluded. | ||||||||||||||||||||||||||||||||||||||
| 36 | 2 | my @JSON_FIELDS = qw( | |||||||||||||||||||||||||||||||||||||
| 37 | tool tool_version launcher_version nbi_slurm_version | ||||||||||||||||||||||||||||||||||||||
| 38 | submitted_at completed_at | ||||||||||||||||||||||||||||||||||||||
| 39 | slurm_job_id slurm_queue slurm_cpus slurm_mem_gb | ||||||||||||||||||||||||||||||||||||||
| 40 | host user status exit_code sample | ||||||||||||||||||||||||||||||||||||||
| 41 | inputs params outputs | ||||||||||||||||||||||||||||||||||||||
| 42 | outdir scratch checksums script | ||||||||||||||||||||||||||||||||||||||
| 43 | ); | ||||||||||||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||||||||||||
| 45 | 5 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=23 SCAR=33.6
Pod
documented
| |||||||||||||||||||||||||||||||||||||||
| 46 | 5 | my ($class, %args) = @_; | |||||||||||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||||||||||||
| 48 | 5 | my $self = bless {}, $class; | |||||||||||||||||||||||||||||||||||||
| 49 | |||||||||||||||||||||||||||||||||||||||
| 50 | # Required fields | ||||||||||||||||||||||||||||||||||||||
| 51 | 5 | for my $f (qw(tool sample outdir)) { | |||||||||||||||||||||||||||||||||||||
| 52 | confess "ERROR NBI::Manifest: missing required field '$f'\n" | ||||||||||||||||||||||||||||||||||||||
| 53 | 14 | ▶ | unless defined $args{$f}; | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 54 | } | ||||||||||||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||||||||||||
| 56 | # Populate all known fields with defaults where sensible | ||||||||||||||||||||||||||||||||||||||
| 57 | 3 | $self->{tool} = $args{tool}; | |||||||||||||||||||||||||||||||||||||
| 58 | 3 | ▶ | $self->{tool_version} = $args{tool_version} // 'unknown'; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"tool_version"} // "unknown"
MC/DC100%1/1
$args{"tool_version"} // "unknown"
$args{"tool_version"}
Truth table100%2/2
A
A= $args{"tool_version"}
| |||||||||||||||||||||||||||||||||||||||
| 59 | 3 | ▶ | $self->{launcher_version} = $args{launcher_version} // '0.1.0'; | ||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$args{"launcher_version"} // "0.1.0"
MC/DC0%0/1
$args{"launcher_version"} // "0.1.0"
$args{"launcher_version"}
Truth table50%1/2
A
A= $args{"launcher_version"}
| |||||||||||||||||||||||||||||||||||||||
| 60 | 3 | ▶ | $self->{nbi_slurm_version} = $args{nbi_slurm_version} // ($NBI::Slurm::VERSION // 'unknown'); | ||||||||||||||||||||||||||||||||||||
|
Condition50%2/4
$args{"nbi_slurm_version"} // ($NBI::Slurm::VERSION // "unknown")
$NBI::Slurm::VERSION // "unknown"
MC/DC0%0/1
$args{"nbi_slurm_version"} // ($NBI::Slurm::VERSION // "unknown")
$args{"nbi_slurm_version"}
Truth table50%1/2
A
A= $args{"nbi_slurm_version"}
| |||||||||||||||||||||||||||||||||||||||
| 61 | $self->{submitted_at} = $args{submitted_at} | ||||||||||||||||||||||||||||||||||||||
| 62 | 3 | ▶ | // strftime("%Y-%m-%dT%H:%M:%SZ", gmtime()); | ||||||||||||||||||||||||||||||||||||
|
Condition33%1/3
$args{"submitted_at"} // strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
MC/DC0%0/2
$args{"submitted_at"} // strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
$args{"submitted_at"}
strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
Truth table33%1/3
A // B
A= $args{"submitted_at"}B= strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
| |||||||||||||||||||||||||||||||||||||||
| 63 | 3 | $self->{completed_at} = $args{completed_at}; # undef until job ends | |||||||||||||||||||||||||||||||||||||
| 64 | 3 | $self->{slurm_job_id} = $args{slurm_job_id}; # undef until submitted | |||||||||||||||||||||||||||||||||||||
| 65 | 3 | ▶ | $self->{slurm_queue} = $args{slurm_queue} // 'unknown'; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"slurm_queue"} // "unknown"
MC/DC100%1/1
$args{"slurm_queue"} // "unknown"
$args{"slurm_queue"}
Truth table100%2/2
A
A= $args{"slurm_queue"}
| |||||||||||||||||||||||||||||||||||||||
| 66 | 3 | ▶ | $self->{slurm_cpus} = $args{slurm_cpus} // 1; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"slurm_cpus"} // 1
MC/DC100%1/1
$args{"slurm_cpus"} // 1
$args{"slurm_cpus"}
Truth table100%2/2
A
A= $args{"slurm_cpus"}
| |||||||||||||||||||||||||||||||||||||||
| 67 | 3 | ▶ | $self->{slurm_mem_gb} = $args{slurm_mem_gb} // 0; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"slurm_mem_gb"} // 0
MC/DC100%1/1
$args{"slurm_mem_gb"} // 0
$args{"slurm_mem_gb"}
Truth table100%2/2
A
A= $args{"slurm_mem_gb"}
| |||||||||||||||||||||||||||||||||||||||
| 68 | $self->{host} = $args{host} | ||||||||||||||||||||||||||||||||||||||
| 69 | // $ENV{HOSTNAME} | ||||||||||||||||||||||||||||||||||||||
| 70 | 0 | ▶ | // do { chomp(my $h = `hostname 2>/dev/null`); $h } // 'unknown'; | ||||||||||||||||||||||||||||||||||||
|
Condition37%3/8
(($args{"host"} // $ENV{"HOSTNAME"}) // do {
chomp(my $h = `hostname 2>/dev/null`);
$h
}) // "unknown"
($args{"host"} // $ENV{"HOSTNAME"}) // do {
chomp(my $h = `hostname 2>/dev/null`);
$h
}
$args{"host"} // $ENV{"HOSTNAME"}
MC/DC0%0/3
(($args{"host"} // $ENV{"HOSTNAME"}) // do {
chomp(my $h = `hostname 2>/dev/null`);
$h
}) // "unknown"
$args{"host"}
$ENV{"HOSTNAME"}
do {
chomp(my $h = `hostname 2>/dev/null`);
$h
}
Truth table25%1/4
A // B // C
A= $args{"host"}B= $ENV{"HOSTNAME"}C= do {
chomp(my $h = `hostname 2>/dev/null`);
$h
}
| |||||||||||||||||||||||||||||||||||||||
| 71 | 3 | ▶ | $self->{user} = $args{user} // $ENV{USER} // 'unknown'; | ||||||||||||||||||||||||||||||||||||
|
Condition40%2/5
($args{"user"} // $ENV{"USER"}) // "unknown"
$args{"user"} // $ENV{"USER"}
MC/DC0%0/2
($args{"user"} // $ENV{"USER"}) // "unknown"
$args{"user"}
$ENV{"USER"}
Truth table33%1/3
A // B
A= $args{"user"}B= $ENV{"USER"}
| |||||||||||||||||||||||||||||||||||||||
| 72 | 3 | ▶ | $self->{status} = $args{status} // 'submitted'; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"status"} // "submitted"
MC/DC100%1/1
$args{"status"} // "submitted"
$args{"status"}
Truth table100%2/2
A
A= $args{"status"}
| |||||||||||||||||||||||||||||||||||||||
| 73 | 3 | $self->{exit_code} = $args{exit_code}; # undef until job ends | |||||||||||||||||||||||||||||||||||||
| 74 | 3 | $self->{sample} = $args{sample}; | |||||||||||||||||||||||||||||||||||||
| 75 | 3 | ▶ | $self->{inputs} = $args{inputs} // {}; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"inputs"} // {}
MC/DC100%1/1
$args{"inputs"} // {}
$args{"inputs"}
Truth table100%2/2
A
A= $args{"inputs"}
| |||||||||||||||||||||||||||||||||||||||
| 76 | 3 | ▶ | $self->{params} = $args{params} // {}; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"params"} // {}
MC/DC100%1/1
$args{"params"} // {}
$args{"params"}
Truth table100%2/2
A
A= $args{"params"}
| |||||||||||||||||||||||||||||||||||||||
| 77 | 3 | ▶ | $self->{outputs} = $args{outputs} // {}; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"outputs"} // {}
MC/DC100%1/1
$args{"outputs"} // {}
$args{"outputs"}
Truth table100%2/2
A
A= $args{"outputs"}
| |||||||||||||||||||||||||||||||||||||||
| 78 | 3 | $self->{outdir} = $args{outdir}; | |||||||||||||||||||||||||||||||||||||
| 79 | 3 | ▶ | $self->{scratch} = $args{scratch} // ''; | ||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$args{"scratch"} // ""
MC/DC0%0/1
$args{"scratch"} // ""
$args{"scratch"}
Truth table50%1/2
A
A= $args{"scratch"}
| |||||||||||||||||||||||||||||||||||||||
| 80 | 3 | ▶ | $self->{checksums} = $args{checksums} // {}; | ||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$args{"checksums"} // {}
MC/DC0%0/1
$args{"checksums"} // {}
$args{"checksums"}
Truth table50%1/2
A
A= $args{"checksums"}
| |||||||||||||||||||||||||||||||||||||||
| 81 | 3 | ▶ | $self->{script} = $args{script} // ''; | ||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args{"script"} // ""
MC/DC100%1/1
$args{"script"} // ""
$args{"script"}
Truth table100%2/2
A
A= $args{"script"}
| |||||||||||||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||||||||||||
| 83 | # Internal: path where this manifest lives on disk (not serialised) | ||||||||||||||||||||||||||||||||||||||
| 84 | 3 | $self->{_path} = $args{_path}; | |||||||||||||||||||||||||||||||||||||
| 85 | |||||||||||||||||||||||||||||||||||||||
| 86 | 3 | return $self; | |||||||||||||||||||||||||||||||||||||
| 87 | } | ||||||||||||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||||||||||||
| 89 | # ── write($path) ────────────────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||
| 90 | # Serialise to JSON and write to $path. Records _path for future update() calls. | ||||||||||||||||||||||||||||||||||||||
| 91 | 3 | ▶ | sub write { | ||||||||||||||||||||||||||||||||||||
|
Subroutine
write: called CC=4 SCAR=14.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||
| 92 | 3 | my ($self, $path) = @_; | |||||||||||||||||||||||||||||||||||||
| 93 | 3 | ▶ | confess "ERROR NBI::Manifest::write: path required\n" unless defined $path; | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 94 | |||||||||||||||||||||||||||||||||||||||
| 95 | # Build the hash to serialise (JSON_FIELDS order, excluding _path) | ||||||||||||||||||||||||||||||||||||||
| 96 | 3 | my %data; | |||||||||||||||||||||||||||||||||||||
| 97 | 3 | for my $f (@JSON_FIELDS) { | |||||||||||||||||||||||||||||||||||||
| 98 | 66 | $data{$f} = $self->{$f}; | |||||||||||||||||||||||||||||||||||||
| 99 | } | ||||||||||||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||||||||||||
| 101 | 3 | my $json = JSON::PP->new->utf8->pretty->canonical->encode(\%data); | |||||||||||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||||||||||||
| 103 | 3 | ▶ | open(my $fh, '>', $path) | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 104 | or confess "ERROR NBI::Manifest::write: cannot open '$path': $!\n"; | ||||||||||||||||||||||||||||||||||||||
| 105 | 3 | print $fh $json; | |||||||||||||||||||||||||||||||||||||
| 106 | 3 | close $fh; | |||||||||||||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||||||||||||
| 108 | 3 | $self->{_path} = $path; | |||||||||||||||||||||||||||||||||||||
| 109 | 3 | return $self; | |||||||||||||||||||||||||||||||||||||
| 110 | } | ||||||||||||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||||||||||||
| 112 | # ── load($path) ─────────────────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||
| 113 | # Parse an existing manifest JSON file and return a blessed object. | ||||||||||||||||||||||||||||||||||||||
| 114 | 3 | ▶ | sub load { | ||||||||||||||||||||||||||||||||||||
|
Subroutine
load: called CC=4 SCAR=14.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||
| 115 | 3 | my ($class, $path) = @_; | |||||||||||||||||||||||||||||||||||||
| 116 | 3 | ▶ | confess "ERROR NBI::Manifest::load: path required\n" unless defined $path; | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 117 | 3 | ▶ | confess "ERROR NBI::Manifest::load: '$path' not found\n" unless -f $path; | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 118 | |||||||||||||||||||||||||||||||||||||||
| 119 | 3 | ▶ | open(my $fh, '<', $path) | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 120 | or confess "ERROR NBI::Manifest::load: cannot open '$path': $!\n"; | ||||||||||||||||||||||||||||||||||||||
| 121 | 3 | my $raw = do { local $/; <$fh> }; | |||||||||||||||||||||||||||||||||||||
| 122 | 3 | close $fh; | |||||||||||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||||||||||||
| 124 | 3 | my $data = JSON::PP->new->utf8->decode($raw); | |||||||||||||||||||||||||||||||||||||
| 125 | 3 | my $self = bless $data, $class; | |||||||||||||||||||||||||||||||||||||
| 126 | 3 | $self->{_path} = $path; | |||||||||||||||||||||||||||||||||||||
| 127 | 3 | return $self; | |||||||||||||||||||||||||||||||||||||
| 128 | } | ||||||||||||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||||||||||||
| 130 | # ── output($name) ───────────────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||
| 131 | # Returns the absolute path of a named output file. | ||||||||||||||||||||||||||||||||||||||
| 132 | # Useful for chaining launchers: read a previous manifest to get output paths. | ||||||||||||||||||||||||||||||||||||||
| 133 | 2 | ▶ | sub output { | ||||||||||||||||||||||||||||||||||||
|
Subroutine
output: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||
| 134 | 2 | my ($self, $name) = @_; | |||||||||||||||||||||||||||||||||||||
| 135 | 2 | ▶ | confess "ERROR NBI::Manifest::output: name required\n" unless defined $name; | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 136 | 2 | ▶ | my $filename = $self->{outputs}{$name} | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 137 | or confess "ERROR NBI::Manifest::output: no output named '$name'\n"; | ||||||||||||||||||||||||||||||||||||||
| 138 | 1 | return "$self->{outdir}/$filename"; | |||||||||||||||||||||||||||||||||||||
| 139 | } | ||||||||||||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||||||||||||
| 141 | # ── update(%changes) ────────────────────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||
| 142 | # Merge %changes into the object and rewrite to the stored _path. | ||||||||||||||||||||||||||||||||||||||
| 143 | # Used by nbilaunch after submission to record the Slurm job ID. | ||||||||||||||||||||||||||||||||||||||
| 144 | 3 | ▶ | sub update { | ||||||||||||||||||||||||||||||||||||
|
Subroutine
update: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||
| 145 | 3 | my ($self, %changes) = @_; | |||||||||||||||||||||||||||||||||||||
| 146 | confess "ERROR NBI::Manifest::update: no path known - call write() first\n" | ||||||||||||||||||||||||||||||||||||||
| 147 | 3 | ▶ | unless defined $self->{_path}; | ||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||||||||||||
| 149 | 2 | for my $k (keys %changes) { | |||||||||||||||||||||||||||||||||||||
| 150 | 5 | $self->{$k} = $changes{$k}; | |||||||||||||||||||||||||||||||||||||
| 151 | } | ||||||||||||||||||||||||||||||||||||||
| 152 | 2 | $self->write($self->{_path}); | |||||||||||||||||||||||||||||||||||||
| 153 | 2 | return $self; | |||||||||||||||||||||||||||||||||||||
| 154 | } | ||||||||||||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||||||||||||
| 156 | 2 | 1; | |||||||||||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||||||||||||
| 158 | __END__ | ||||||||||||||||||||||||||||||||||||||