Logging¶
The program log is one of the outputs of Imprint. It is generated by the engine and plugins. The log provides traceability into the workings of Imprint, including plugins. As an important part of the user interaction on many levels, a separate document to describe the logging facility is merited.
Configuration¶
Logging is configured through the IPC File. The following keywords are used to configure the logging output:
All keywords are optional. The default is to log WARNING
and worse to
stdout
. If log_stderr is set to
True
, messages with level ERROR
and worse will be sent to
stderr
instead. In general, when both
stdout_level and stderr_level are
True
, stdout
will receive only the messages with
levels greater than or equal to stdout_level, but
strictly less than stderr_level.
If log_file is set to a non-empty string, all messages
will be logged to it regardless of what is written to stdout
and
stderr
.
The logging format can be controlled by log_format, which
is the same type of string that can be passed in to format argument of
logging.basicConfig
or the fmt argument of
logging.Formatter
. The template is a %
-interpolated format
string that refers to the attributes of a logging.LogRecord
by name.
Image Logging¶
If the keyword log_images is truthy, any images that get inserted into the document are also dumped individually to a file. The name of the images is based on the name of the log file (via log_images), or the name of the document if file logging is disabled. The figure, table or string ID is appended after an underscore, and the appropriate extension is added at the end.
Image logging is implemented individually for tags that generate content. It is
currently supported for the following tags: <figure>,
<latex>, <string> and ocassionally for
<table>. The strings create small .txt
files containing
the snippets they generate. Custom tags are expected to respect image logging in
a way that makes sense.
Under normal circumstances, the tag descriptor is responsible for logging images. However, in certain cases, the logging can be done by the content handler. Among the built-in tags, this is true for tables, since the variety of input data makes it pointless to generalize the type of logging required (as it is for Figures and Strings).
Logging From Tags¶
The XML Tag API allows users to process custom tags by implementing a
TagDescriptor
. Tags should use the
engine core’s logging facility, provided by
the log
method of the
EngineState
. The reason for using the provided
log
method instead of the local logger is that it will attach information
about the parser’s position in the XML file to every record.
Logging From Plugins¶
Unlike tag descriptors,
plugin handlers are left to their own devices when it
comes to logging. All of the XML location information will be available from
the surrounding log records provided by the tag, so no real advantage is to be
gained from providing location information. On the other hand, plugins can
access the convenience methods provided by Python’s
logging framework, such as
debug
and exception
.
The standard procedure for the Builtin Plugins is to get a “private” modue-level logger, and use that throughout:
_logger = logging.getLogger(__name__)
Levels¶
In addition to the normal logging levels provided by the Python
logging
framework, Imprint sets up the following additional levels:
TRACE
- Used to report on the normal activity of a tag processor or plugin that may
be irrelevant for any but the most fine-grained debugging. The priority
defaults to 5, which is lower than
logging.DEBUG
but higher thanlogging.NOTSET
. XTRACE
- Similar to
TRACE
, but includes the current exception information by default. The priority defaults to 2, which is below that ofTRACE
.
All levels are registered with the logging
framework as if they were
built-in. The appropriate methods are registered with the currently configured
default logger class.