"certbot.log"
*************

Logging utilities for Certbot.

The best way to use this module is through "pre_arg_parse_setup" and
"post_arg_parse_setup". "pre_arg_parse_setup" configures a minimal
terminal logger and ensures a detailed log is written to a secure
temporary file if Certbot exits before "post_arg_parse_setup" is
called. "post_arg_parse_setup" relies on the parsed command line
arguments and does the full logging setup with terminal and rotating
file handling as configured by the user. Any logged messages before
"post_arg_parse_setup" is called are sent to the rotating file
handler. Special care is taken by both methods to ensure all errors
are logged and properly flushed before program exit.

certbot.log.pre_arg_parse_setup()

   Setup logging before command line arguments are parsed.

   Terminal logging is setup using
   "certbot.constants.QUIET_LOGGING_LEVEL" so Certbot is as quiet as
   possible. File logging is setup so that logging messages are
   buffered in memory. If Certbot exits before "post_arg_parse_setup"
   is called, these buffered messages are written to a temporary file.
   If Certbot doesn’t exit, "post_arg_parse_setup" writes the messages
   to the normal log files.

   This function also sets "logging.shutdown" to be called on program
   exit which automatically flushes logging handlers and
   "sys.excepthook" to properly log/display fatal exceptions.

certbot.log.post_arg_parse_setup(config)

   Setup logging after command line arguments are parsed.

   This function assumes "pre_arg_parse_setup" was called earlier and
   the root logging configuration has not been modified. A rotating
   file logging handler is created and the buffered log messages are
   sent to that handler. Terminal logging output is set to the level
   requested by the user.

   Parameters:
      **config** (*certbot.interface.IConfig*) – Configuration object

certbot.log.setup_log_file_handler(config, logfile, fmt)

   Setup file debug logging.

   Parameters:
      * **config** (*certbot.interface.IConfig*) – Configuration
        object

      * **logfile** (*str*) – basename for the log file

      * **fmt** (*str*) – logging format string

   Returns:
      file handler and absolute path to the log file

   Return type:
      tuple

class certbot.log.ColoredStreamHandler(stream=None)

   Bases: "logging.StreamHandler"

   Sends colored logging output to a stream.

   If the specified stream is not a tty, the class works like the
   standard "logging.StreamHandler". Default red_level is
   "logging.WARNING".

   Variables:
      * **colored** (*bool*) – True if output should be colored

      * **red_level** (*bool*) – The level at which to output

   format(record)

      Formats the string representation of record.

      Parameters:
         **record** (*logging.LogRecord*) – Record to be formatted

      Returns:
         Formatted, string representation of record

      Return type:
         str

class certbot.log.MemoryHandler(target=None, capacity=10000)

   Bases: "logging.handlers.MemoryHandler"

   Buffers logging messages in memory until the buffer is flushed.

   This differs from "logging.handlers.MemoryHandler" in that flushing
   only happens when flush(force=True) is called.

   close()

      Close the memory handler, but don’t set the target to None.

   flush(force=False)

      Flush the buffer if force=True.

      If force=False, this call is a noop.

      Parameters:
         **force** (*bool*) – True if the buffer should be flushed.

   shouldFlush(record)

      Should the buffer be automatically flushed?

      Parameters:
         **record** (*logging.LogRecord*) – log record to be
         considered

      Returns:
         False because the buffer should never be auto-flushed

      Return type:
         bool

class certbot.log.TempHandler

   Bases: "logging.StreamHandler"

   Safely logs messages to a temporary file.

   The file is created with permissions 600. If no log records are
   sent to this handler, the temporary file is deleted when the
   handler is closed.

   Variables:
      **path** (*str*) – file system path to the temporary log file

   emit(record)

      Log the specified logging record.

      Parameters:
         **record** (*logging.LogRecord*) – Record to be formatted

   close()

      Close the handler and the temporary log file.

      The temporary log file is deleted if it wasn’t used.

certbot.log.pre_arg_parse_except_hook(memory_handler, *args, **kwargs)

   A simple wrapper around post_arg_parse_except_hook.

   The additional functionality provided by this wrapper is the memory
   handler will be flushed before Certbot exits. This allows us to
   write logging messages to a temporary file if we crashed before
   logging was fully configured.

   Since sys.excepthook isn’t called on SystemExit exceptions, the
   memory handler will not be flushed in this case which prevents us
   from creating temporary log files when argparse exits because a
   command line argument was invalid or -h, –help, or –version was
   provided on the command line.

   Parameters:
      * **memory_handler** (*MemoryHandler*) – memory handler to
        flush

      * **args** (*tuple*) – args for post_arg_parse_except_hook

      * **kwargs** (*dict*) – kwargs for post_arg_parse_except_hook

certbot.log.post_arg_parse_except_hook(exc_type, exc_value, trace, debug, log_path)

   Logs fatal exceptions and reports them to the user.

   If debug is True, the full exception and traceback is shown to the
   user, otherwise, it is suppressed. sys.exit is always called with a
   nonzero status.

   Parameters:
      * **exc_type** (*type*) – type of the raised exception

      * **exc_value** (*BaseException*) – raised exception

      * **trace** (*traceback*) – traceback of where the exception
        was raised

      * **debug** (*bool*) – True if the traceback should be shown
        to the user

      * **log_path** (*str*) – path to file or directory containing
        the log

certbot.log.exit_with_log_path(log_path)

   Print a message about the log location and exit.

   The message is printed to stderr and the program will exit with a
   nonzero status.

   Parameters:
      **log_path** (*str*) – path to file or directory containing the
      log
