From b86800b5e8bb5e1071e0dcc5c25c6f7952867dad Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Aug 2026 22:32:55 +0000 Subject: [PATCH] Document mqlog in the README Add an mqlog section covering the no-argument default (most recent finished job, with the fallback warning when it has no log file), looking up a specific job ID, -f/--failed for the most recent job that exited non-zero, -e/--stderr and -o/--stdout for a single stream, and the pager behaviour. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Wjx1QNqCHEChB3H6bj93F7 --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index b368e9d..1be7502 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,50 @@ cl5n013 | 1 threads | 356 GB ``` +# mqlog +`mqlog` prints the stdout and stderr of a finished PBS job, so you don't have to hunt down the `.OU`/`.ER` files yourself. With no arguments it shows the most recently finished job belonging to you, working out the log paths from `qstat` (including the per-job `.OU` / `.ER` files that `mqsub --segregated-log-files` writes into a directory). If the newest finished job left no log behind, it walks back through your finished jobs until it finds one that did and prints a warning saying which job it is actually showing: +``` +mqlog +``` +``` +WARNING: Most recent finished job 9524871.aqua has no log file. Showing log from 9524870.aqua. + +===== STDOUT: /work/microbiome/user/logs/9524870.aqua.OU ===== +Processing sample 12 of 12 +===== STDERR: /work/microbiome/user/logs/9524870.aqua.ER ===== +``` + +To look at a specific job rather than the most recent one, pass its job ID. A bare number is fine — `.aqua` is appended automatically — so these are equivalent: +``` +mqlog 9524870 +mqlog 9524870.aqua +``` + +`-f` (`--failed`) skips over jobs that succeeded and shows the most recent job that exited non-zero, which is usually the one you want after a batch of `mqsub`s. It reports which job it picked, and cannot be combined with an explicit job ID: +``` +mqlog -f +``` +``` +Showing logs from failed job 9524863.aqua. + +===== STDOUT: /work/microbiome/user/logs/9524863.aqua.OU ===== +... +``` + +By default both streams are printed with `===== STDOUT: ... =====` headers separating them. Use `-e` (`--stderr`) to print only stderr, or `-o` (`--stdout`) for only stdout; with a single stream the headers are omitted so the output is clean to pipe or grep. These two options are mutually exclusive, and combine with a job ID or with `-f`: +``` +mqlog -e # stderr of the most recent finished job +mqlog -e 9524870 # stderr of a particular job +mqlog -e -f # stderr of the most recent failed job +``` + +Output is paged through `less -RF` when writing to a terminal, meaning short logs are printed inline and left on screen while longer ones open in the pager. Set `$PAGER` to use a different pager (or to the empty string for none), pass `--no-pager` to disable it for one invocation, or simply pipe the output — paging is skipped automatically when stdout is not a terminal: +``` +mqlog --no-pager +mqlog -e 9524870 | grep -i error +``` + + # mqwait If you are running a batch of jobs, you may wish to be notified once the entire batch has finished processing, as opposed to per-job notifications generated by mqsub. There are three ways to run mqwait: