absl.logging package

Submodules

• absl.logging.converter module
  • absl_to_cpp()
  • absl_to_standard()
  • get_initial_for_level()
  • standard_to_absl()
  • standard_to_cpp()
  • string_to_standard()

Module contents

Abseil Python logging module implemented on top of standard logging.

Simple usage:

from absl import logging

logging.info('Interesting Stuff')
logging.info('Interesting Stuff with Arguments: %d', 42)

logging.set_verbosity(logging.INFO)
logging.log(logging.DEBUG, 'This will *not* be printed')
logging.set_verbosity(logging.DEBUG)
logging.log(logging.DEBUG, 'This will be printed')

logging.warning('Worrying Stuff')
logging.error('Alarming Stuff')
logging.fatal('AAAAHHHHH!!!!')  # Process exits.

Usage note: Do not pre-format the strings in your program code. Instead, let the logging module perform argument interpolation. This saves cycles because strings that don’t need to be printed are never formatted. Note that this module does not attempt to interpolate arguments when no arguments are given. In other words:

logging.info('Interesting Stuff: %s')

does not raise an exception because logging.info() has only one argument, the message string.

“Lazy” evaluation for debugging

If you do something like this:

logging.debug('Thing: %s', thing.ExpensiveOp())

then the ExpensiveOp will be evaluated even if nothing is printed to the log. To avoid this, use the level_debug() function:

if logging.level_debug():
  logging.debug('Thing: %s', thing.ExpensiveOp())

Per file level logging is supported by logging.vlog() and logging.vlog_is_on(). For example:

if logging.vlog_is_on(2):
  logging.vlog(2, very_expensive_debug_message())

Notes on Unicode

The log output is encoded as UTF-8. Don’t pass data in other encodings in bytes() instances – instead pass unicode string instances when you need to (for both the format string and arguments).

Note on critical and fatal: Standard logging module defines fatal as an alias to critical, but it’s not documented, and it does NOT actually terminate the program. This module only defines fatal but not critical, and it DOES terminate the program.

The differences in behavior are historical and unfortunate.

class absl.logging.ABSLHandler(python_logging_formatter)

Bases: Handler

Abseil Python logging module’s log handler.

activate_python_handler()

Uses the Python logging handler as the current logging handler.

close()

Tidy up any resources used by the handler.

This version removes the handler from an internal map of handlers, _handlers, which is used for handler lookup by name. Subclasses should ensure that this gets called from overridden close() methods.

emit(record)

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.

flush()

Ensure all logging output has been flushed.

This version does nothing and is intended to be implemented by subclasses.

format(record)

Format the specified record.

If a formatter is set, use it. Otherwise, use the default formatter for the module.

handle(record)

Conditionally emit the specified logging record.

Emission depends on filters which may have been added to the handler. Wrap the actual emission of the record with acquisition/release of the I/O thread lock. Returns whether the filter passed the record for emission.

property python_handler

setFormatter(fmt)

Set the formatter for this handler.

start_logging_to_file(program_name=None, log_dir=None)

use_absl_log_file(program_name=None, log_dir=None)

class absl.logging.ABSLLogger(name, level=0)

Bases: Logger

A logger that will create LogRecords while skipping some stack frames.

This class maintains an internal list of filenames and method names for use when determining who called the currently executing stack frame. Any method names from specific source files are skipped when walking backwards through the stack.

Client code should use the register_frame_to_skip method to let the ABSLLogger know which method from which file should be excluded from the walk backwards through the stack.

critical(msg, *args, **kwargs)

Logs msg % args with severity CRITICAL.

debug(msg, *args, **kwargs)

Logs msg % args with severity DEBUG.

error(msg, *args, **kwargs)

Logs msg % args with severity ERROR.

fatal(msg, *args, **kwargs)

Logs msg % args with severity FATAL.

findCaller(stack_info=False, stacklevel=1)

Finds the frame of the calling method on the stack.

This method skips any frames registered with the ABSLLogger and any methods from this file, and whatever method is currently being used to generate the prefix for the log line. Then it returns the file name, line number, and method name of the calling method. An optional fourth item may be returned, callers who only need things from the first three are advised to always slice or index the result rather than using direct unpacking assignment.

Parameters:

stack_info – bool, when True, include the stack trace as a fourth item returned. On Python 3 there are always four items returned - the fourth will be None when this is False. On Python 2 the stdlib base class API only returns three items. We do the same when this new parameter is unspecified or False for compatibility.

Returns:

(filename, lineno, methodname[, sinfo]) of the calling method.

handle(record)

Calls handlers without checking Logger.disabled.

Non-root loggers are set to disabled after setup with logging.config() if it’s not explicitly specified. Historically, absl logging will not be disabled by that. To maintaining this behavior, this function skips checking the Logger.disabled bit.

This logger can still be disabled by adding a filter that filters out everything.

Parameters:

record – logging.LogRecord, the record to handle.

info(msg, *args, **kwargs)

Logs msg % args with severity INFO.

log(level, msg, *args, **kwargs)

Logs a message at a cetain level substituting in the supplied arguments.

This method behaves differently in python and c++ modes.

Parameters:

• level – int, the standard logging level at which to log the message.

• msg – str, the text of the message to log.

• *args – The arguments to substitute in the message.

• **kwargs – The keyword arguments to substitute in the message.

classmethod register_frame_to_skip(file_name, function_name, line_number=None)

Registers a function name to skip when walking the stack.

The ABSLLogger sometimes skips method calls on the stack to make the log messages meaningful in their appropriate context. This method registers a function from a particular file as one which should be skipped.

Parameters:

• file_name – str, the name of the file that contains the function.

• function_name – str, the name of the function to skip.

• line_number – int, if provided, only the function with this starting line number will be skipped. Otherwise, all functions with the same name in the file will be skipped.

warn(msg, *args, **kwargs)

Logs msg % args with severity WARN.

warning(msg, *args, **kwargs)

Logs msg % args with severity WARNING.

class absl.logging.PythonFormatter(fmt=None, datefmt=None, style='%', validate=True)

Bases: Formatter

Formatter class used by PythonHandler.

format(record)

Appends the message from the record to the results of the prefix.

Parameters:

record – logging.LogRecord, the record to be formatted.

Returns:

The formatted string representing the record.

class absl.logging.PythonHandler(stream=None, formatter=None)

Bases: StreamHandler

The handler class used by Abseil Python logging implementation.

close()

Closes the stream to which we are writing.

emit(record)

Prints a record out to some streams.

1. If FLAGS.logtostderr is set, it will print to sys.stderr ONLY.

2. If FLAGS.alsologtostderr is set, it will print to sys.stderr.

3. If FLAGS.logtostderr is not set, it will log to the stream

   associated with the current thread.

Parameters:

record – logging.LogRecord, the record to emit.

flush()

Flushes all log files.

start_logging_to_file(program_name=None, log_dir=None)

Starts logging messages to files instead of standard error.

use_absl_log_file(program_name=None, log_dir=None)

Conditionally logs to files, based on –logtostderr.

absl.logging.debug(msg, *args, **kwargs)

Logs a debug message.

absl.logging.error(msg, *args, **kwargs)

Logs an error message.

absl.logging.exception(msg, *args, **kwargs)

Logs an exception, with traceback and message.

absl.logging.fatal(msg: Any, *args: Any, **kwargs: Any) → NoReturn

Logs a fatal message.

absl.logging.find_log_dir(log_dir=None)

Returns the most suitable directory to put log files into.

Parameters:

log_dir – str|None, if specified, the logfile(s) will be created in that directory. Otherwise if the –log_dir command-line flag is provided, the logfile will be created in that directory. Otherwise the logfile will be created in a standard location.

Raises:

• FileNotFoundError – raised in Python 3 when it cannot find a log directory.

• OSError – raised in Python 2 when it cannot find a log directory.

absl.logging.find_log_dir_and_names(program_name=None, log_dir=None)

Computes the directory and filename prefix for log file.

Parameters:

• program_name – str|None, the filename part of the path to the program that is running without its extension. e.g: if your program is called usr/bin/foobar.py this method should probably be called with program_name='foobar However, this is just a convention, you can pass in any string you want, and it will be used as part of the log filename. If you don’t pass in anything, the default behavior is as described in the example. In python standard logging mode, the program_name will be prepended with py_ if it is the program_name argument is omitted.

• log_dir – str|None, the desired log directory.

Returns:

(log_dir, file_prefix, symlink_prefix)

Raises:

• FileNotFoundError – raised in Python 3 when it cannot find a log directory.

• OSError – raised in Python 2 when it cannot find a log directory.

absl.logging.flush()

Flushes all log files.

absl.logging.get_absl_handler()

Returns the absl handler instance.

absl.logging.get_absl_log_prefix(record)

Returns the absl log prefix for the log record.

Parameters:

record – logging.LogRecord, the record to get prefix for.

absl.logging.get_absl_logger()

Returns the absl logger instance.

absl.logging.get_log_file_name(level=0)

Returns the name of the log file.

For Python logging, only one file is used and level is ignored. And it returns empty string if it logs to stderr/stdout or the log stream has no name attribute.

Parameters:

level – int, the absl.logging level.

Raises:

ValueError – Raised when level has an invalid value.

absl.logging.get_verbosity()

Returns the logging verbosity.

absl.logging.info(msg, *args, **kwargs)

Logs an info message.

absl.logging.level_debug()

Returns True if debug logging is turned on.

absl.logging.level_error()

Returns True if error logging is turned on.

absl.logging.level_info()

Returns True if info logging is turned on.

absl.logging.level_warn()

Returns True if warning logging is turned on.

absl.logging.level_warning()

Returns True if warning logging is turned on.

absl.logging.log(level, msg, *args, **kwargs)

Logs msg % args at absl logging level level.

If no args are given just print msg, ignoring any interpolation specifiers.

Parameters:

• level – int, the absl logging level at which to log the message (logging.DEBUG|INFO|WARNING|ERROR|FATAL). While some C++ verbose logging level constants are also supported, callers should prefer explicit logging.vlog() calls for such purpose.

• msg – str, the message to be logged.

• *args – The args to be substituted into the msg.

• **kwargs – May contain exc_info to add exception traceback to message.

absl.logging.log_every_n(level, msg, n, *args)

Logs msg % args at level ‘level’ once per ‘n’ times.

Logs the 1st call, (N+1)st call, (2N+1)st call, etc. Not threadsafe.

Parameters:

• level – int, the absl logging level at which to log.

• msg – str, the message to be logged.

• n – int, the number of times this should be called before it is logged.

• *args – The args to be substituted into the msg.

absl.logging.log_every_n_seconds(level, msg, n_seconds, *args)

Logs msg % args at level level iff n_seconds elapsed since last call.

Logs the first call, logs subsequent calls if ‘n’ seconds have elapsed since the last logging call from the same call site (file + line). Not thread-safe.

Parameters:

• level – int, the absl logging level at which to log.

• msg – str, the message to be logged.

• n_seconds – float or int, seconds which should elapse before logging again.

• *args – The args to be substituted into the msg.

absl.logging.log_first_n(level, msg, n, *args)

Logs msg % args at level level only first n times.

Not threadsafe.

Parameters:

• level – int, the absl logging level at which to log.

• msg – str, the message to be logged.

• n – int, the maximal number of times the message is logged.

• *args – The args to be substituted into the msg.

absl.logging.log_if(level, msg, condition, *args)

Logs msg % args at level level only if condition is fulfilled.

absl.logging.set_stderrthreshold(s)

Sets the stderr threshold to the value passed in.

Parameters:

s – str|int, valid strings values are case-insensitive ‘debug’, ‘info’, ‘warning’, ‘error’, and ‘fatal’; valid integer values are logging.DEBUG|INFO|WARNING|ERROR|FATAL.

Raises:

ValueError – Raised when s is an invalid value.

absl.logging.set_verbosity(v)

Sets the logging verbosity.

Causes all messages of level <= v to be logged, and all messages of level > v to be silently discarded.

Parameters:

v – int|str, the verbosity level as an integer or string. Legal string values are those that can be coerced to an integer as well as case-insensitive ‘debug’, ‘info’, ‘warning’, ‘error’, and ‘fatal’.

absl.logging.skip_log_prefix(func)

Skips reporting the prefix of a given function or name by ABSLLogger.

This is a convenience wrapper function / decorator for register_frame_to_skip().

If a callable function is provided, only that function will be skipped. If a function name is provided, all functions with the same name in the file that this is called in will be skipped.

This can be used as a decorator of the intended function to be skipped.

Parameters:

func – Callable function or its name as a string.

Returns:

func (the input, unchanged).

Raises:

• ValueError – The input is callable but does not have a function code object.

• TypeError – The input is neither callable nor a string.

absl.logging.use_absl_handler()

Uses the ABSL logging handler for logging.

This method is called in app.run() so the absl handler is used in absl apps.

absl.logging.use_python_logging(quiet=False)

Uses the python implementation of the logging code.

Parameters:

quiet – No logging message about switching logging type.

absl.logging.vlog(level, msg, *args, **kwargs)

Log msg % args at C++ vlog level level.

Parameters:

• level – int, the C++ verbose logging level at which to log the message, e.g. 1, 2, 3, 4… While absl level constants are also supported, callers should prefer logging.log|debug|info|… calls for such purpose.

• msg – str, the message to be logged.

• *args – The args to be substituted into the msg.

• **kwargs – May contain exc_info to add exception traceback to message.

absl.logging.vlog_is_on(level)

Checks if vlog is enabled for the given level in caller’s source file.

Parameters:

level – int, the C++ verbose logging level at which to log the message, e.g. 1, 2, 3, 4… While absl level constants are also supported, callers should prefer level_debug|level_info|… calls for checking those.

Returns:

True if logging is turned on for that level.

absl.logging.warn(msg, *args, **kwargs)

Deprecated, use ‘warning’ instead.

absl.logging.warning(msg, *args, **kwargs)

Logs a warning message.