% $Id$

% Earth System Modeling Framework
% Copyright (c) 2002-2023, University Corporation for Atmospheric Research, 
% Massachusetts Institute of Technology, Geophysical Fluid Dynamics 
% Laboratory, University of Michigan, National Centers for Environmental 
% Prediction, Los Alamos National Laboratory, Argonne National Laboratory, 
% NASA Goddard Space Flight Center.
% Licensed under the University of Illinois-NCSA License.


%\subsection{Description}
\label{sec:Log}

The Log class consists of a variety of methods for writing error, warning, and
informational messages to files.  A default Log is created at ESMF
initialization.  Other Logs can be created later in the code by the user.  Most
Log methods take a Log as an optional argument and apply to the default Log
when another Log is not specified.  A set of standard return codes and
associated messages are provided for error handling.  

Log provides capabilities to store message entries in a buffer, which is 
flushed to a file, either when the buffer is full, or when the user calls an 
{\tt ESMF\_LogFlush()} method.  Currently, the default is for the Log to flush
after every ten entries.  This can easily be changed by using the 
{\tt ESMF\_LogSet()} method and setting the {\tt maxElements} property to 
another value.  The {\tt ESMF\_LogFlush()} method is automatically called when 
the program exits by any means (program completion, halt on error, or when the
Log is closed).

The user has the capability to abort the program on conditions such as
an error or on a warning by using the {\tt ESMF\_LogSet()} method with
the {\tt logmsgAbort} argument.  For example if the  {\tt logmsgAbort} array
is set to {\tt (ESMF\_LOGMSG\_ERROR,ESMF\_LOGMSG\_WARNING)}, the program will 
stop on any and all warning or errors.  When the {\tt logmsgAbort} argument
is set to  {\tt ESMF\_LOGMSG\_ERROR}, the program will only abort on
errors.  Lastly, the user can choose to never abort by using
{\tt ESMF\_LOGMSG\_NONE}; this is the default.

Log will automatically put the PET number into the Log.  Also, the user can 
either specify {\tt ESMF\_LOGKIND\_SINGLE} which writes all the entries to a single 
Log or {\tt ESMF\_LOGKIND\_MULTI} which writes entries to multiple Logs according to 
the PET number.  To distinguish Logs from each other when using 
{\tt ESMF\_LOGKIND\_MULTI}, the PET number (in the format {\tt PETx.}) will be 
prepended to the file name where x is the PET number.

Opening multiple log files and writing log messages from all the processors
may affect the application performance while running on a large number of
processors.  For that reason, {\tt ESMF\_LOGKIND\_NONE} is provided to
switch off the Log capability.  All the Log methods have no effect
in the {\tt ESMF\_LOGKIND\_NONE} mode.

\begin{sloppypar}
A tracing capability may be enabled by setting the {\tt trace} flag by
using the {\tt ESMF\_LogSet()} method.  When tracing is enabled, calls to
methods such as {\tt ESMF\_LogFoundError}, {\tt ESMF\_LogFoundAllocError},
and {\tt ESMF\_LogFoundDeallocError} are logged in the default log file.
This can result in voluminous output.  It is typically used only around areas
of code which are being debugged.
\end{sloppypar}
   
Other options that are planned for Log are to adjust the verbosity of output, and to optionally write to {\tt stdout} instead of file(s).




