opsicommon.logging package

Submodules

opsicommon.logging.constants module

This file is part of opsi - https://www.opsi.org

opsicommon.logging.logging module

logging

class opsicommon.logging.logging.ContextFilter(filter_dict=None)

Bases: Filter

class ContextFilter

This class implements a filter which modifies allows to store context for a single thread/task.

Parameters:

filter_dict (Optional[dict[str, Any]]) –

filter(record)

Adds context to a LogRecord.

This method is called by Logger._log and modifies LogRecords. It adds the context stored for the current thread/task to the namespace. If the records context conforms to the filter, it is passed on.

Parameters:

record (LogRecord) – LogRecord to add context to and to filter.

Returns:

True, if the record conforms to the filter rules.

Return type:

bool

get_context()

Returns context of current thread/task.

This method requests the thread/task identifier, looks up the context stored for it and returns it.

Returns:

Context for currently active thread/task.

Return type:

Dict

set_filter(filter_dict=None)

Sets a new filter dictionary.

This method expectes a filter dictionary. Records are only allowed to pass if their context has a matching key-value entry. None means, every record can pass.

Parameters:

filter_dict (Dict) – Value that must be present in record context in order to accept the LogRecord.

Return type:

None

class opsicommon.logging.logging.ContextSecretFormatter(orig_formatter)

Bases: Formatter

class ContextSecretFormatter

This class fulfills two formatting tasks: 1. It alters the LogRecord to also include a string representation of

a context dictionary, which can be logged by specifying a log format which includes %(contextstring)s

  1. It can replace secret strings specified to a SecretFilter by a

    replacement string, thus censor passwords etc.

Parameters:

orig_formatter (Formatter) –

disable_filter()

Disable the Secret Filter

This method sets secret_filter_enabled to False such that on evaluating LogRecords, the List if secrets is disregarded on formatting.

Return type:

None

enable_filter()

Enable the Secret Filter

This method sets secret_filter_enabled to True such that on evaluating LogRecords, the List if secrets is consulted on formatting.

Return type:

None

format(record)

Formats a LogRecord.

This method takes a LogRecord and formats it to produce an output string. If context is specified in the LogRecord it is used to produce a contextstring which is included in the log string if %(contextstring)s is specified in the format.

Parameters:

record (logging.LogRecord) – LogRecord to format.

Return type:

str

Returns:

The formatted log string.

Rytpe:

str

logger_name_in_context_string = False
class opsicommon.logging.logging.OPSILogger(name, level=0)

Bases: Logger

Parameters:

  • name (str) –

  • level (int | str) –

comment(msg, *args, **kwargs)

Logging with level ESSENTIAL.

This method calls a log with level ESSENTIAL.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

confidential(msg, *args, **kwargs)

Logging with level SECRET.

This method calls a log with level SECRET.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

debug2(msg, *args, **kwargs)

Logging with level TRACE.

This method calls a log with level TRACE.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

devel(msg, *args, **kwargs)

Logging with level ESSENTIAL.

This method calls a log with level ESSENTIAL.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

essential(msg, *args, **kwargs)

Logging with level ESSENTIAL.

This method calls a log with level ESSENTIAL.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

findCaller(stack_info=False, stacklevel=1)

Find the stack frame of the caller so that we can note the source file name, line number and function name.

Parameters:

  • stack_info (bool) –

  • stacklevel (int) –

Return type:

tuple[str, int, str, None]

notice(msg, *args, **kwargs)

Logging with level NOTICE.

This method calls a log with level NOTICE.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

secret(msg, *args, **kwargs)

Logging with level SECRET.

This method calls a log with level SECRET.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

trace(msg, *args, **kwargs)

Logging with level TRACE.

This method calls a log with level TRACE.

Parameters:

  • msg (Any) – Message to log (may contain %-style placeholders).

  • *args –

    Arguments to fill %-style placeholders with.

  • **kwargs –

    Additional keyword-arguments.

  • args (Any) –

  • kwargs (Any) –

Return type:

None

class opsicommon.logging.logging.ObservableHandler

Bases: Handler

attachObserver(observer)
Parameters:

observer (Any) –

Return type:

None

attach_observer(observer)
Parameters:

observer (Any) –

Return type:

None

detachObserver(observer)
Parameters:

observer (Any) –

Return type:

None

detach_observer(observer)
Parameters:

observer (Any) –

Return type:

None

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.

Parameters:

record (LogRecord) –

Return type:

None

class opsicommon.logging.logging.RichConsoleHandler(console)

Bases: Handler

Parameters:

console (Console) –

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.

Parameters:

record (LogRecord) –

Return type:

None

class opsicommon.logging.logging.SecretFilter(min_length=6)

Bases: object

class SecretFilter

This class implements functionality of maintaining a collection of secrets which can be used by the ContextSecretFormatter.

Parameters:

min_length (int) –

add_secrets(*secrets)

Inserts new secret strings.

This method expects any number of secret strings and adds them to the list.

Parameters:

  • *secrets –

    Any number of strings (as individual arguments) to add.

  • secrets (str) –

Return type:

None

clear_secrets()

Delete all secret strings.

This method clears the list of secret strings.

Return type:

None

remove_secrets(*secrets)

Removes secret strings.

This method expects any number of secret strings and removes them from the list.

Parameters:

  • *secrets –

    Any number of strings (as individual arguments) to remove.

  • secrets (str) –

Return type:

None

set_min_length(min_length)

Sets minimal secret length.

This method assigns a new value to the minimal secret length. Any new secret string can only be added, if it has more characters.

Parameters:

min_length (int) – Minimal length of a secret string.

Return type:

None

class opsicommon.logging.logging.Singleton

Bases: type

opsicommon.logging.logging.add_context_filter_to_logger(_logger)
Parameters:

_logger (Logger) –

Return type:

None

opsicommon.logging.logging.add_context_filter_to_loggers()
Return type:

None

opsicommon.logging.logging.get_all_handlers(handler_type=None, handler_name=None)

Gets list of all handlers.

This method iterates over all registered loggers. All handlers (optional: of a certain type) are collected and returned as list.

Parameters:

  • handler_type (class) – If not None, return only handlers of specified type.

  • handler_name (Optional[str]) –

Returns:

List containing all handlers (of specified type) of all loggers.

Return type:

List

opsicommon.logging.logging.get_all_loggers()

Gets list of all loggers.

This method requests all Logger instances registered at logging.Logger.manager.loggerDict and returns them as a list.

not
returns:

List containing all loggers (including root)

rtype:

List

Return type:

list[Logger | RootLogger]

opsicommon.logging.logging.get_logger(name=None)
Parameters:

name (Optional[str]) –

Return type:

OPSILogger

opsicommon.logging.logging.handle_log_exception(exc, record=None, stderr=True, temp_file=False, log=False)

Handles an exception in logging process.

This method prints an Exception message and traceback to stderr.

Parameters:

  • exc (Exception) – Exception to be logged.

  • record (logging.LogRecord.) – Log record where the exception occured.

  • stderr (bool) – If true, the Exception is printed to srderr. (default: True)

  • temp_file (bool) – If true, the Exception is written to a temp file. (default: False)

  • log (bool) – If true, the Exception is output by the logger. (default: False)

Return type:

None

opsicommon.logging.logging.init_logging(*, stderr_level=None, stderr_format=None, log_file=None, file_level=None, file_format=None)
Parameters:

  • stderr_level (Optional[int]) –

  • stderr_format (Optional[str]) –

  • log_file (Optional[str]) –

  • file_level (Optional[int]) –

  • file_format (Optional[str]) –

Return type:

None

opsicommon.logging.logging.init_warnings_capture(traceback_log_level=40)
Parameters:

traceback_log_level (int) –

Return type:

None

opsicommon.logging.logging.log_context(new_context)

Contextmanager to set a context.

This contextmanager sets context to the given one on entering and resets to the previous dictionary when leaving.

Example: with log_context({“instance”: “context-name”}): … :type new_context: dict[str, Any] :param new_context: new context to set for the section. :type new_context: dict

Return type:

Generator[None, None, None]

opsicommon.logging.logging.logging_config(*, stderr_level=None, stderr_format=None, log_file=None, file_level=None, file_format=None, file_rotate_max_bytes=0, file_rotate_backup_count=0, remove_handlers=False, stderr_file=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, logger_levels=None)

Initialize logging.

This method initializes the logger according to given parameters. Log levels and format for stderr and file output can be set individually. :type stderr_level: Optional[int] :param stderr_level: Loglevel to set for the stderr logging stream. :type stderr_level: int :type stderr_format: Optional[str] :param stderr_format: Format to set for the stderr logging stream. :type stderr_format: str :type stderr_file: IO | Console :param stderr_file: File handle for stderr stream. :type stderr_file: IO :type log_file: Optional[str] :param log_file: Name of the file to write logging stream to. :type log_file: str :type file_level: Optional[int] :param file_level: Loglevel to set for the file logging stream. :type file_level: int :type file_format: Optional[str] :param file_format: Format to set for the file logging stream. :type file_format: str :type file_rotate_max_bytes: int :param file_rotate_max_bytes: Rotate log file if size exceeds file_rotate_max_bytes :type file_rotate_max_bytes: int :type file_rotate_backup_count: int :param file_rotate_backup_count: Keep this number of backups when rotating :type file_rotate_backup_count: int :type remove_handlers: bool :param remove_handlers: Remove all current handlers :type remove_handlers: bool

Parameters:

logger_levels (Optional[dict]) –

Return type:

None

opsicommon.logging.logging.logrecord_init(self, name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

New Constructor for LogRecord.

This overloads the LogRecord constructor to also include the OpsiLogLevel. The reason is to have backwards compatibility.

Parameters:

  • name (str) – Name of the logger to feed.

  • level (int) – Log level of the message.

  • pathname (str) – Path of the running module.

  • lineno (int) – Line number of the call.

  • msg (str) – Message to log (may contain %-style placeholders).

  • args (Any) – Arguments to fill %-style placeholders with.

  • exc_info (Any) – Traceback information in case of exceptions.

  • func (Optional[str]) – Name of the calling function.

  • sinfo (Any) – Call stack information.

  • **kwargs –

    Additional keyword-arguments.

  • self (LogRecord) –

  • kwargs (Any) –

Return type:

None

opsicommon.logging.logging.print_logger_info()

Debug output logger status.

This method prints all loggers with their respective handlers and formatters to stderr.

Return type:

None

opsicommon.logging.logging.remove_all_handlers(handler_type=None, handler_name=None)

Removes all handlers (of a certain type).

This method iterates over all loggers. All assigned handlers (of a given type or all) are removed.

Parameters:

  • handler_type (class) – Type of handlers that should be removed.

  • handler_name (Optional[str]) –

Return type:

None

opsicommon.logging.logging.set_context(new_context)

Sets a context.

This method sets context to the given one and returns a reset-token.

Parameters:

new_context (dict) – new context to set.

Returns:

reset-token for the context (stores previous value).

Return type:

contextvars.Token

opsicommon.logging.logging.set_filter(filter_dict)

Sets a new filter dictionary.

This method expectes a filter dictionary. Records are only allowed to pass if their context contains this specific dictionary. None means, every record can pass.

Parameters:

filter_dict (Dict) – Dictionary that must be present in record context in order to accept the LogRecord.

Return type:

None

opsicommon.logging.logging.set_filter_from_string(filter_string)

Parses string and sets filter dictionary.

This method expects a string (e.g. from user input). It is parsed to create a dictionary which is set as filter dictionary. The parsing rules are:

  • Entries are separated by ‘;’.

  • One entry consists of exactly two strings separated by ‘=’.

  • The first one is interpreted as key, the second as value(s).

  • Values of the same key are separated by ‘,’.

Parameters:

filter_string (str) – String to parse for a filter statement.

Return type:

None

opsicommon.logging.logging.set_format(*, file_format='[%(opsilevel)d] [%(asctime)s.%(msecs)03d] [%(contextstring)-15s] %(message)s   (%(filename)s:%(lineno)d)', stderr_format='%(log_color)s[%(opsilevel)d] [%(asctime)s.%(msecs)03d]%(reset)s [%(contextstring)-15s] %(message)s   (%(filename)s:%(lineno)d)', datefmt='%Y-%m-%d %H:%M:%S', log_colors=None)

Assigns ContextSecretFormatter to all Handlers.

This method takes optional arguments for format, dateformat and log colors and creates ContextSecretFormatters considering those. Every Handler is assigned such a ContextSecretFormatter.

Parameters:

  • file_format (str) – Format to set for the file logging stream.

  • stderr_format (str) – Format to set for the stderr logging stream.

  • datefmt (str) – Date format for logging. If omitted, a default dateformat is used.

  • log_colors (Dict) – Dictionary of colors for different log levels. If omitted, a default Color dictionary is used.

Return type:

None

Module contents

This file is part of opsi - https://www.opsi.org