Every program generates a log file when it is run. By default, this file will be named after the calling program (e.g.
gasp.py will produce a log called
gasp.log) but this can be changed with the
log=FILE option. The
basefile=X option will also set the base name of the log file, as well as the main results files (for most programs). Logs will be appended unless the
newlog=T) option is used.
The log file records information that may help subsequent interpretation of results or identify problems. Each line is tab delimited in the form:
#XXX HH:MM:SS Log Message.
#XXX is an identifier that can be used to parse out specific types of information,
HH:MM:SS is the runtime in hours, minutes and seconds, and
Log Message will be something (hopefully) informative.
All log files start with the same few lines:
#~~# #~~# #~~#
#LOG 00:00:00 Activity Log for PROGRAM X.X: DATE TIME YEAR
#DIR 00:00:00 Run from directory: RUNPATH
#ARG 00:00:00 Commandline arguments: ARGLIST
#CMD 00:00:00 Full Command List: [FULL ARGLIST]
This should contain all the information required to repeat the analysis:
PROGRAM X.X: DATE TIME YEARwill have the program name, version number and the date/time of the run.
RUNPATHis the directory from which the program was run.
ARGLISTis the list of command-line arguments given to the program.
FULL ARGLISTis the full list of command-line arguments including any arguments read in from ini files.
The last line can help identify the source of any unexpected behaviour due to default settings etc.
#~~# #~~# #~~# line is simply to act as a separator if appending an existing log file.)
If the program runs to completion successfully, it will end with another
#LOG HH:MM:SS PROGRAM V:X.X End: DATE TIME YEAR
If this line is not present then something went wrong during the run (see Error Messages, below - or it is still in progress. Other information is also recorded along with the runtime (
HH:MM:SS since the program started). For help interpreting log files, please check the relevant software manual or contact me if the information is missing. (Hopefully, the log content is mostly self-explanatory but I shall add any explanations I have to send people to the relevant manual’s appendix.)
One of the most important aspects of the log file is to register any error messages. These are marked by an
#ERR line header. Hopefully, there will not be any but if there was a problem with the run then these lines should contain the details. To catch these lines separately,
errorlog=FILE will output error messages to an additional file.