pip_services3_components.log package

Submodules

Module contents

pip_services3_components.log.__init__

Logger implementations. There exist many different loggers, but all of them are implemented differently in various languages. We needed portable classes, that would allow to quickly transfer code from one language to another. We can wrap existing loggers into/around our ILogger class.

copyright

Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.

license

MIT, see LICENSE for more details.

class pip_services3_components.log.CachedLogger

Bases: pip_services3_components.log.Logger.Logger, pip_services3_commons.config.IReconfigurable.IReconfigurable

Abstract logger that caches captured log messages in memory and periodically dumps them. Child classes implement saving cached messages to their specified destinations.

### Configuration parameters ###

  • level: maximum log level to capture

  • source: source (context) name

  • options:

    • interval: interval in milliseconds to save log messages (default: 10 seconds)

    • max_cache_size: maximum number of messages stored in this cache (default: 100)

### References ###

  • *:context-info:*:*:1.0 (optional) ContextInfo to detect the context id and specify counters source

clear()

Clears (removes) all cached log messages.

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

dump()

Dumps (writes) the currently cached log messages.

class pip_services3_components.log.CompositeLogger(references: pip_services3_commons.refer.IReferences.IReferences = None)

Bases: pip_services3_components.log.Logger.Logger, pip_services3_commons.refer.IReferenceable.IReferenceable

Aggregates all loggers from component references under a single component.

It allows to log messages and conveniently send them to multiple destinations.

### References ###

  • *:logger:*:*:1.0 (optional) ILogger components to pass log messages

Example:

class MyComponent(IConfigurable, IReferenceable):
    __logger = CompositeLogger()

    def configure(self, config):
        self.__logger.configure(config)

    def set_references(self, references):
        self.__logger.set_references(references)

    def my_method(self, correlation_id):
        self.__logger.debug(correlation_id, "Called method mycomponent.mymethod")
set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

class pip_services3_components.log.ConsoleLogger

Bases: pip_services3_components.log.Logger.Logger

Logger that writes log messages to console.

Errors are written to standard err stream and all other messages to standard out stream.

### Configuration parameters ###

  • level: maximum log level to capture

  • source: source (context) name

### References ###

  • *:context-info:*:*:1.0 (optional) ContextInfo to detect the context id and specify counters source

Example:

logger = ConsoleLogger()
logger.set_level(LogLevel.debug)

logger.error("123", ex, "Error occured: %s", ex.message)
logger.debug("123", "Everything is OK.")
class pip_services3_components.log.DefaultLoggerFactory

Bases: pip_services3_components.build.Factory.Factory

Creates ILogger components by their descriptors.

See Factory, NullLogger, ConsoleLogger, CompositeLogger

CompositeLoggerDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
ConsoleLoggerDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
NullLoggerDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
class pip_services3_components.log.ILogger

Bases: abc.ABC

Interface for logger components that capture execution log messages.

debug(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a high-level debug information for troubleshooting.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

error(correlation_id: Optional[str], error: Exception, message: str, *args: Any, **kwargs: Any)

Logs recoverable application error.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

fatal(correlation_id: Optional[str], error: Exception, message: str, *args: Any, **kwargs: Any)

Logs fatal (unrecoverable) message that caused the process to crash.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

get_level() → <module ‘pip_services3_components.log.LogLevel’ from ‘/pip_services3_components/log/LogLevel.py’>

Gets the maximum log level. Messages with higher log level are filtered out.

Returns

the maximum log level.

info(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs an important information message

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

log(level: <module 'pip_services3_components.log.LogLevel' from '/pip_services3_components/log/LogLevel.py'>, correlation_id: Optional[str], error: Optional[Exception], message: Optional[str], *args: Any, **kwargs: Any)

Logs a message at specified log level.

Parameters

  • level – a log level.

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

set_level(level: <module 'pip_services3_components.log.LogLevel' from '/pip_services3_components/log/LogLevel.py'>)

Set the maximum log level.

Parameters

level – a new maximum log level.

trace(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a low-level debug information for troubleshooting.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

warn(correlation_id: Optional[str], message: Exception, *args: Any, **kwargs: Any)

Logs a warning that may or may not have a negative impact.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

class pip_services3_components.log.LogLevel

Bases: object

Standard log levels.

Logs at debug and trace levels are usually captured only locally for troubleshooting and never sent to consolidated log services.

Debug = 5

Logs everything up to high-level debugging information

Error = 2

Logs all errors - fatal or recoverable

Fatal = 1

Logs only fatal errors that cause microservice to fail

Info = 4

Logs errors and important information messages

Nothing = 0

Nothing to be logged

Trace = 6

Logs everything down to fine-granular debugging messages

Warn = 3

Logs errors and warnings

class pip_services3_components.log.LogLevelConverter

Bases: object

Helper class to convert log level values.

static to_integer(level: pip_services3_components.log.LogLevel.LogLevel) → int

Converts log level to a number.

Parameters

level – a log level to convert.

Returns

log level number value.

static to_log_level(value: Any, default_value: pip_services3_components.log.LogLevel.LogLevel = 4) → pip_services3_components.log.LogLevel.LogLevel

Converts numbers and strings to standard log level values.

Parameters

  • value – a value to be converted

  • default_value – a default value if conversion is not possible

Returns

converted log level

static to_string(level: pip_services3_components.log.LogLevel.LogLevel) → str

Converts log level to a string.

Parameters

level – a log level to convert

Returns

log level name string.

class pip_services3_components.log.LogMessage(level: <module 'pip_services3_components.log.LogLevel' from '/pip_services3_components/log/LogLevel.py'> = None, source: str = None, correlation_id: Optional[str] = None, error: pip_services3_commons.errors.ErrorDescription.ErrorDescription = None, message: str = None)

Bases: object

Data object to store captured log messages. This object is used by CachedLogger.

class pip_services3_components.log.Logger

Bases: pip_services3_components.log.ILogger.ILogger, pip_services3_commons.config.IReconfigurable.IReconfigurable, pip_services3_commons.refer.IReferenceable.IReferenceable, abc.ABC

Abstract logger that captures and formats log messages. Child classes take the captured messages and write them to their specific destinations.

### Configuration parameters ###

Parameters to pass to the configure() method for component configuration:

  • level: maximum log level to capture

  • source: source (context) name

### References ###

  • *:context-info:*:*:1.0 (optional) ContextInfo to detect the context id and specify counters source

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

debug(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a high-level debug information for troubleshooting.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

error(correlation_id: Optional[str], error: Exception, message: str, *args: Any, **kwargs: Any)

Logs recoverable application error.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

fatal(correlation_id: Optional[str], error: Exception, message: str, *args: Any, **kwargs: Any)

Logs fatal (unrecoverable) message that caused the process to crash.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

get_level() → pip_services3_components.log.LogLevel.LogLevel

Gets the maximum log level. Messages with higher log level are filtered out.

Returns

the maximum log level.

get_source() → str

Gets the source (context) name.

Returns

the source (context) name.

info(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs an important information message

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

log(level: pip_services3_components.log.LogLevel.LogLevel, correlation_id: Optional[str], error: Optional[Exception], message: Optional[str], *args: Any, **kwargs: Any)

Logs a message at specified log level.

Parameters

  • level – a log level.

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

set_level(level: pip_services3_components.log.LogLevel.LogLevel)

Set the maximum log level.

Parameters

level – a new maximum log level.

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

set_source(value: str)

Sets the source (context) name.

Parameters

value – a new source (context) name.

trace(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a low-level debug information for troubleshooting.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

warn(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a warning that may or may not have a negative impact.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

class pip_services3_components.log.NullLogger

Bases: pip_services3_components.log.ILogger.ILogger

Dummy implementation of logger that doesn’t do anything. It can be used in testing or in situations when logger is required but shall be disabled.

debug(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a high-level debug information for troubleshooting.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

error(correlation_id: Optional[str], error: Exception, message: str, *args: Any, **kwargs: Any)

Logs recoverable application error.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

fatal(correlation_id: Optional[str], error: Exception, message: str, *args: Any, **kwargs: Any)

Logs fatal (unrecoverable) message that caused the process to crash.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

get_level() → pip_services3_components.log.LogLevel.LogLevel

Gets the maximum log level. Messages with higher log level are filtered out.

Returns

the maximum log level.

info(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs an important information message

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

log(level: pip_services3_components.log.LogLevel.LogLevel, correlation_id: Optional[str], error: Optional[Exception], message: Optional[str], *args: Any, **kwargs: Any)

Logs a message at specified log level.

Parameters

  • level – a log level.

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • error – an error object associated with this message.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

set_level(level: pip_services3_components.log.LogLevel.LogLevel)

Set the maximum log level.

Parameters

level – a new maximum log level.

trace(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a low-level debug information for troubleshooting.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.

warn(correlation_id: Optional[str], message: str, *args: Any, **kwargs: Any)

Logs a warning that may or may not have a negative impact.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • message – a human-readable message to log.

  • args – arguments to parameterize the message.

  • kwargs – arguments to parameterize the message.