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 than logging.NOTSET.
XTRACE
Similar to TRACE, but includes the current exception information by default. The priority defaults to 2, which is below that of TRACE.

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.