Stem Docs

Logging

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]

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

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