Logging¶

Functions to aid library logging. The default logging Runlevel is usually NOTICE and above.

Stem users are more than welcome to listen for stem events, but these functions are not being vended to our users. They may change in the future, use them at your own risk.

Module Overview:

get_logger - provides the stem's Logger instance
logging_level - converts a runlevel to its logging number
escape - escapes special characters in a message in preparation for logging

log - logs a message at the given runlevel
log_once - logs a message, deduplicating if it has already been logged
trace - logs a message at the TRACE runlevel
debug - logs a message at the DEBUG runlevel
info - logs a message at the INFO runlevel
notice - logs a message at the NOTICE runlevel
warn - logs a message at the WARN runlevel
error - logs a message at the ERROR runlevel

LogBuffer - Buffers logged events so they can be iterated over.
  |- is_empty - checks if there's events in our buffer
  +- __iter__ - iterates over and removes the buffered events

log_to_stdout - reports further logged events to stdout

stem.util.log.Runlevel(enum)¶

Enumeration for logging runlevels.

Runlevel	Description
ERROR	critical issue occurred, the user needs to be notified
WARN	non-critical issue occurred that the user should be aware of
NOTICE	information that is helpful to the user
INFO	high level library activity
DEBUG	low level library activity
TRACE	request/reply logging

stem.util.log.get_logger()[source]¶

Provides the stem logger.

Returns:	logging.Logger for stem

stem.util.log.logging_level(runlevel)[source]¶

Translates a runlevel into the value expected by the logging module.

Parameters:	runlevel (stem.util.log.Runlevel) -- runlevel to be returned, no logging if None

stem.util.log.is_tracing()[source]¶

Checks if we're logging at the trace runlevel.

New in version 1.6.0.

Returns:	True if we're logging at the trace runlevel and False otherwise

stem.util.log.escape(message)[source]¶

Escapes specific sequences for logging (newlines, tabs, carriage returns). If the input is bytes then this converts it to unicode under python 3.x.

Parameters:	message (str) -- string to be escaped
Returns:	str that is escaped

stem.util.log.log(runlevel, message)[source]¶

Logs a message at the given runlevel.

Parameters:	runlevel (stem.util.log.Runlevel) -- runlevel to log the message at, logging is skipped if None message (str) -- message to be logged

stem.util.log.log_once(message_id, runlevel, message)[source]¶

Logs a message at the given runlevel. If a message with this ID has already been logged then this is a no-op.

Parameters:	message_id (str) -- unique message identifier to deduplicate on runlevel (stem.util.log.Runlevel) -- runlevel to log the message at, logging is skipped if None message (str) -- message to be logged
Returns:	True if we log the message, False otherwise

stem.util.log.trace(message)[source]¶

stem.util.log.debug(message)[source]¶

stem.util.log.info(message)[source]¶

stem.util.log.notice(message)[source]¶

stem.util.log.warn(message)[source]¶

stem.util.log.error(message)[source]¶

class stem.util.log.LogBuffer(runlevel, yield_records=False)[source]¶

Bases: logging.Handler

Basic log handler that listens for stem events and stores them so they can be read later. Log entries are cleared as they are read.

Changed in version 1.4.0: Added the yield_records argument.

Deprecated since version 1.8.0: This will be dropped in Stem 2.x. Use python's logging.BufferingHandler instead.

is_empty()[source]¶

emit(record)[source]¶

stem.util.log.log_to_stdout(runlevel)[source]¶

Logs further events to stdout.

Parameters:	runlevel (stem.util.log.Runlevel) -- minimum runlevel a message needs to be to be logged