# Stem Docs

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