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.
-
class
certbot.log.
ColoredStreamHandler
(stream=None)[source]¶ 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 islogging.WARNING
.Variables: - colored (bool) – True if output should be colored
- red_level (bool) – The level at which to output
-
class
certbot.log.
MemoryHandler
(target=None)[source]¶ 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.
-
class
certbot.log.
TempHandler
[source]¶ 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
-
certbot.log.
exit_with_log_path
(log_path)[source]¶ 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
-
certbot.log.
post_arg_parse_except_hook
(exc_type, exc_value, trace, debug, log_path)[source]¶ 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.
post_arg_parse_setup
(config)[source]¶ 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.
pre_arg_parse_except_hook
(memory_handler, *args, **kwargs)[source]¶ 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.
pre_arg_parse_setup
()[source]¶ 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 beforepost_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 andsys.excepthook
to properly log/display fatal exceptions.
-
certbot.log.
setup_log_file_handler
(config, logfile, fmt)[source]¶ 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