Oxs Log File Review: logreview

The OOMMF applications Oxsii and Boxsi record status and error messages from job runs into log files (default oommf/oxsii.errors and oommf/boxsi.errors, respectively). These are plain text files, but they can grow rather long and messages from multiple Oxsii or Boxsi instances running simultaneously can interweave making the log difficult to interpret. The logreview application can make the logs easier to understand by extracting subsets of log records based on various criteria. (See too the command line tool lastjob, which also accesses the default log files.)

Launching
The logreview command line is:

tclsh oommf.tcl logreview [standard options] <oxsii|boxsi|-file logfile> \
  [-after timestamp] [-before timestamp] [-collate] [-firstrun] \
  [-glob globstr] [-grep regexpr] [-info] [-lastrun] [-machine name] \
  [-pid pid] [-runselect first last] [-user username]

where

oxsii|boxsi|-file logfile

Specifies the input log file. If oxsii (resp. boxsi) is selected then the default Oxsii (Boxsi) log file oxsii.errors (boxsi.errors) in the OOMMF root directory is read. Otherwise use -file to select the file. (Use “-” to read from stdin.)

-after timestamp

Select only log entries on or after timestamp, where timestamp is in a format recognized by the Tcl command clock scan in “Free Form Scan” mode.

-before timestamp

Select only log entries on or before timestamp, where timestamp is in a format recognized by the Tcl command clock scan in “Free Form Scan” mode.

-collate

Reorder log entries to group individual job run log records together. Job run log entries typically begin with a Start: record and finish with an End record, but if multiple instances of Oxsii or Boxsi are running simultaneously then log messages from the different instances can become intertwined. The -collate option retains the ordering of the first record in each job.

-firstrun

Prints all records for the first run in the log. Shorthand for -runselect 0 0.

-glob globstr

Restrict to log entries matching the glob-style pattern globstr, as used by the Tcl string match command. This is a full entry, multi-line match, so globstr will typically start and end with the asterisk `*' wildcard character.

-grep regexpr

Restrict to log entries matching the regular-expression pattern regexpr, as used by the Tcl regexp command. If the `^' (string start) and `$' (string end) anchors are not specified, then a match to any part of the log entry is accepted. Use the newline character `\n' to tie a pattern to the start of a line inside a log entry.

-info

Print informational details about the log selection instead of the normal result. If -collate is specified then this output will include the number of job runs.

-lastrun

Prints all records for the last run in the log. Shorthand for -runselect end end.

-machine name

Restrict to log entries recorded from the specified machine.

-pid pid

Restrict to log entries from processes with system process id pid. The pid parameter may be a quoted list of multiple PIDs to select entries from multiple processes. (For active OOMMF applications, the OOMMF command line program pidinfo can be used to map OOMMF IDs to system PIDs.) Operating systems recycle PIDs, and they are assigned separately on each machine, so it may be necessary to use the -after, -before, and -machine options to separate duplicate PID assignments.

-runselect first last

Prints all records for jobs indexed first through last, inclusive, where first and last are 0-based indices as interpreted by the Tcl lindex command. In particular, end may be used to denote the last run. This option implies -collate. It is applied before -glob and -grep but after the other filtering options.

-user username

Restrict to log entries from user username.

The result is printed to stdout. If -info is not requested, then the output will be a collection of records in the usual Oxsii/Boxsi plain text log format. Be aware that Start: records can be trimmed off by -after requests, and End records can be trimmed by -before requests, or missing altogether if a job aborts due to an error.

Examples
The following prints all Oxsii Start: and End records from yesterday afternoon, collated by job:

   tclsh oommf.tcl logreview oxsii -collate -grep "\nStart:|\nEnd" \
      -after "12:00 yesterday" -before "17:00 yesterday"

The next example uses the -info and -collate options together to get a count of jobs that ran during some time window:

   tclsh oommf.tcl logreview boxsi -info -collate \
      -after "10 days ago" -before "3 days ago"

To see the records for the last three runs in the Boxsi log:

   tclsh oommf.tcl logreview boxsi -runselect end-2 end

Over time the default log files can become quite large. To trim records preceding some date, one can do

   tclsh oommf.tcl logreview oxsii -after 1-Apr-2023 > trimmedlog.txt

and then move the trimmedlog.txt file to oommf/oxsii.errors.

OOMMF Documentation Team
September 27, 2024