Logging
prism.LogLevel
The severity of a log message.
Syntax
class LogLevel(IntEnum)
Remarks
The members correspond to the PrismLogLevel values. Each is named after
its value without the PRISM_LOG_LEVEL_ prefix and has the same value:
LogLevel.WARN is PRISM_LOG_LEVEL_WARN.
Members are ordered from least to most severe. A message is delivered when
its level is at least the threshold set by set_level. NONE is
above every severity, so as a threshold it delivers nothing. It MUST NOT be
the level of a message.
prism.install_logging
Forwards Prism’s log messages to the logging module.
Syntax
def install_logging(logger_name: str = 'prism') -> None
Parameters
logger_name
The prefix of the receiving loggers’ names.
Remarks
This function wraps prism_set_log_handler. A message from the source
source goes to the logger named logger_name.source. TRACE maps to
a level named TRACE with the value 5; the other levels map to the
corresponding logging levels.
The handler replaces the one in effect, including the handler installed for
PRISM_LOG; uninstall restores it. If forwarding is already
installed, the function does nothing. Messages are delivered only once the
threshold has been lowered with set_level.
Messages are delivered on Prism’s logging thread. Handlers of the receiving loggers run on that thread, MUST NOT call the functions of this module, and SHOULD return quickly; messages arriving while the thread is busy MAY be dropped.
The first call registers an atexit function that delivers pending
messages and stops the logging thread when the interpreter exits.
Example
Deliver informational messages and above:
import logging
import prism
logging.basicConfig(level=logging.INFO)
prism.install_logging()
prism.set_log_level(prism.LogLevel.INFO)
prism.uninstall_logging
Stops forwarding log messages and restores the previous handler.
Syntax
def uninstall_logging() -> None
Remarks
A message already being delivered MAY still reach logging. The
function does nothing if forwarding is not installed.
prism.set_log_level
Sets the least severe level of message delivered.
Syntax
def set_log_level(level: LogLevel) -> LogLevel
Parameters
level
The new threshold.
Return Value
The previous threshold.
Remarks
This function wraps prism_set_log_level. The initial threshold is
LogLevel.NONE. Messages below the threshold are discarded where they are
produced. The threshold is independent of the handler. The function MAY be
called from any thread at any time.
prism.write_log
Writes a message to Prism’s log.
Syntax
def write_log(level: LogLevel, source: str, message: str) -> None
Parameters
level
The level of the message. It MUST NOT be LogLevel.NONE.
source
The component the message comes from.
message
The text of the message.
Exceptions
If source or message is empty or contains
a NUL character.
Remarks
This function wraps prism_log. The message is subject to the same
threshold and handler as Prism’s own messages. A message below the threshold
is discarded; otherwise it is queued, and the function returns without
waiting for delivery. If the queue is full, the message is dropped, and the
number of dropped messages is later reported as a warning from the source
"prism".
The function MAY be called from any thread, but MUST NOT be called by a handler of a logger that receives Prism’s messages.
prism.flush_log
Waits until queued log messages have been delivered.
Syntax
def flush_log() -> None
Remarks
This function wraps prism_log_flush. It returns once every message queued
before the call has been passed to the handler, or immediately if no handler
is installed. Dropped messages are not recovered.
The function MUST NOT be called by a handler of a logger that receives Prism’s messages.