Logging

Logging module for Peak SDK.

class peak.tools.logging.LogHandler(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of log handlers to be used in logging.

Each enum member corresponds to a specific handler defined in the logging module. This enum provides a convenient way to specify handlers when configuring loggers.

CONSOLE

Represents a console handler, intended for displaying logs in the console.

FILE

Represents a file handler, intended for writing logs to a file.

class peak.tools.logging.LogLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of log levels to be used in logging.

Each enum member corresponds to a specific log level defined in the logging module. The enum provides a convenient way to specify log levels when configuring loggers.

DEBUG

Debug log level. Intended for detailed debugging information.

INFO

Info log level. Used for general information about program execution.

WARN

Warning log level. Indicates potential issues or unexpected behavior.

WARNING

Warning log level. Indicates potential issues or unexpected behavior.

ERROR

Error log level. Indicates errors that do not prevent program execution.

EXCEPTION

Error log level. Indicates errors that do not prevent program execution.

CRITICAL

Critical log level. Indicates severe errors that might lead to program failure.

FATAL

Critical log level. Indicates severe errors that might lead to program failure.

class peak.tools.logging.PeakLogger(logger)

Wrapper class for logging with various log levels.

Parameters:

logger (Any) –

bind(context=None, **kwargs)

Bind contextual information to the logger, enriching log messages.

This method allows attaching context data to the logger, such as additional information or system details, to provide more context in log messages.

Parameters:

  • context (Union[dict[str, Any], None]) – A dictionary or None for contextual information.

  • **kwargs – Additional key-value pairs to enhance context.

Return type:

None

clone_with_context(context=None, **kwargs)

Return a frozen copy of this logger with the specified context added.

Parameters:

  • context (dict[str, Any] | None) –

  • kwargs (Any) –

Return type:

PeakLogger

set_log_level(level)

Set the log level of this logger.

This only affects THIS logger, not other loggers in the application.

Parameters:

level (LogLevel) – Log level to set.

Return type:

None

unbind(keys)

Unbind specified keys from the logger’s context.

Parameters:

keys (list[str]) – List of keys to unbind.

Return type:

None

peak.tools.logging.default_processors_factory(disable_masking)

Return the default processors for PeakLogger.

Parameters:

disable_masking (Optional[bool], optional) – Whether to disable masking of sensitive data. Defaults to False.

Returns:

List of processors to be used by the logger.

Return type:

list[structlog.types.Processor | Any]

peak.tools.logging.get_logger(name=None, level=None, custom_processors_factory=None, disable_masking=None, handlers=None, file_name=None, **kwargs)

Return an isolated logger instance that does NOT mutate global state.

This function creates a logger isolated from other loggers in your application. It will NOT affect third-party libraries like boto3, urllib3, etc.

The logger is configured with its own handlers attached to a named stdlib logger (not the root logger) and uses structlog.wrap_logger() for isolated structlog configuration.

When setup_loging() has been called, this function respects the global configuration for defaults. Per-logger parameters override global settings.

Parameters:

  • name (Optional[str], optional) – Name of the logger. Defaults to “peak” if not provided. Using a name ensures the logger is isolated from the root logger.

  • level (LogLevel) – Log level for this specific logger. Defaults to global config, then LogLevel.INFO or value from LOG_LEVEL/DEBUG environment variables.

  • custom_processors_factory (Optional[Callable[..., List[structlog.types.Processor | Any]]], optional) – A factory function that returns a list of custom processors. Defaults to None. This disables the default processors provided with the default implementation.

  • disable_masking (Optional[bool], optional) – Whether to disable masking of sensitive data. Defaults to global config value, then False. Only applicable when using the default processors.

  • handlers (Optional[List[LogHandler]], optional) – List of log handlers (CONSOLE, FILE). Defaults to CONSOLE. Pass an empty list [] to add no handlers (useful for library usage where you want the application to control output).

  • file_name (Optional[str], optional) – Filename for FILE handler. Required if FILE handler is used.

  • **kwargs – Additional keyword arguments passed to custom_processors_factory. kwargs must be hashable else TypeError will be raised.

Returns:

An isolated logger instance.

Return type:

PeakLogger

Raises:

ValueError – If the file_name is not provided for FILE handler or if multiple renderers are found in the processor`(s) list returned by the `custom_processors_factory.

Example

>>> from peak.tools.logging import get_logger, LogLevel
>>>
>>> # Create an isolated logger - won't affect boto3 or other libraries
>>> logger = get_logger("my_app", level=LogLevel.DEBUG)
>>> logger.info("Hello, world!")
>>>
>>> # Create another logger with different settings
>>> db_logger = get_logger("my_app.database", level=LogLevel.WARNING)
peak.tools.logging.peak_contexts_processor(_, __, event_dict)

Add the standard attribute to the event_dict.

Parameters:

  • _ (str) –

  • __ (str) –

  • event_dict (MutableMapping[str, Any]) –

Return type:

MutableMapping[str, Any]

peak.tools.logging.pii_masking_processor(_, __, event_dict)

Masks sensitive PII data present in event_dict.

Parameters:

  • _ (str) –

  • __ (str) –

  • event_dict (MutableMapping[str, Any]) –

Return type:

MutableMapping[str, Any]

peak.tools.logging.setup_logging(*, default_level=LogLevel.INFO, disable_masking=False)

Configure global defaults for all Peak loggers.

This function sets a global configuration that affects all subsequently created loggers via get_logger(). Call this once at application startup.

Parameters:

  • default_level (LogLevel) – Default log level for new loggers. Defaults to INFO.

  • disable_masking (bool) – Disable PII masking in logs globally. Defaults to False.

Return type:

None

Example

Application with hierarchy (recommended for module-level loggers):

>>> # module.py - module-level logger created at import time
>>> from peak.tools.logging import get_logger
>>> module_logger = get_logger("myapp.module")
>>>
>>> # main.py - configure logging after imports
>>> from peak.tools.logging import setup_logging, LogLevel
>>> setup_logging(default_level=LogLevel.DEBUG)
>>>
>>> # module_logger now inherits DEBUG level from root
>>> module_logger.debug("This will be visible!")  # Works!

Application with logger levels:

>>> from peak.tools.logging import setup_logging, get_logger, LogLevel
>>> setup_logging(default_level=LogLevel.INFO)
>>> logger = get_logger("myapp", level=LogLevel.DEBUG)  # Explicit level overrides global