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.
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