Core

provide.foundation.logger.core

TODO: Add module docstring.

Attributes

Classes

FoundationLogger

FoundationLogger(hub: Any = None)

A structlog-based logger providing a standardized logging interface.

Source code in provide/foundation/logger/core.py

def __init__(self, hub: Any = None) -> None:
    self._internal_logger = structlog.get_logger().bind(
        logger_name=f"{self.__class__.__module__}.{self.__class__.__name__}",
    )
    self._is_configured_by_setup: bool = False
    self._active_config: TelemetryConfig | None = None
    self._hub = hub  # Hub dependency for DI pattern

Functions

__setattr__

__setattr__(name: str, value: Any) -> None

Override setattr to prevent accidental modification of logger state.

Source code in provide/foundation/logger/core.py

def __setattr__(self, name: str, value: Any) -> None:
    """Override setattr to prevent accidental modification of logger state."""
    if hasattr(self, name) and name.startswith("_"):
        super().__setattr__(name, value)
    else:
        super().__setattr__(name, value)

bind

bind(**kwargs: Any) -> Any

Create a new logger with additional context bound to it.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Key-value pairs to bind to the logger	{}

Returns:

Type	Description
Any	A new logger instance with the bound context

Source code in provide/foundation/logger/core.py

def bind(self, **kwargs: Any) -> Any:
    """Create a new logger with additional context bound to it.

    Args:
        **kwargs: Key-value pairs to bind to the logger

    Returns:
        A new logger instance with the bound context

    """
    self._ensure_configured()
    # Get the actual structlog logger and bind context to it
    if hasattr(self, "_logger") and self._logger:
        return self._logger.bind(**kwargs)
    # Fallback: get fresh logger and bind
    log = self.get_logger()
    return log.bind(**kwargs)

critical

critical(event: str, *args: Any, **kwargs: Any) -> None

Log critical-level event.

Source code in provide/foundation/logger/core.py

def critical(self, event: str, *args: Any, **kwargs: Any) -> None:
    """Log critical-level event."""
    formatted_event = self._format_message_with_args(event, args)
    self._log_with_level("critical", formatted_event, **kwargs)

debug

debug(event: str, *args: Any, **kwargs: Any) -> None

Log debug-level event.

Source code in provide/foundation/logger/core.py

def debug(self, event: str, *args: Any, **kwargs: Any) -> None:
    """Log debug-level event."""
    formatted_event = self._format_message_with_args(event, args)
    self._log_with_level("debug", formatted_event, **kwargs)

error

error(event: str, *args: Any, **kwargs: Any) -> None

Log error-level event.

Source code in provide/foundation/logger/core.py

def error(self, event: str, *args: Any, **kwargs: Any) -> None:
    """Log error-level event."""
    formatted_event = self._format_message_with_args(event, args)
    self._log_with_level("error", formatted_event, **kwargs)

exception

exception(event: str, *args: Any, **kwargs: Any) -> None

Log error-level event with exception traceback.

Source code in provide/foundation/logger/core.py

def exception(self, event: str, *args: Any, **kwargs: Any) -> None:
    """Log error-level event with exception traceback."""
    formatted_event = self._format_message_with_args(event, args)
    kwargs["exc_info"] = True
    self._log_with_level("error", formatted_event, **kwargs)

info

info(event: str, *args: Any, **kwargs: Any) -> None

Log info-level event.

Source code in provide/foundation/logger/core.py

def info(self, event: str, *args: Any, **kwargs: Any) -> None:
    """Log info-level event."""
    formatted_event = self._format_message_with_args(event, args)
    self._log_with_level("info", formatted_event, **kwargs)

setup

setup(config: TelemetryConfig) -> None

Setup the logger with configuration from Hub.

Parameters:

Name	Type	Description	Default
config	TelemetryConfig	TelemetryConfig to use for setup	required

Source code in provide/foundation/logger/core.py

def setup(self, config: TelemetryConfig) -> None:
    """Setup the logger with configuration from Hub.

    Args:
        config: TelemetryConfig to use for setup

    """
    self._active_config = config
    self._is_configured_by_setup = True

    # Run the internal setup process
    try:
        from provide.foundation.logger.setup.coordinator import internal_setup

        internal_setup(config, is_explicit_call=True)
    except Exception as e:
        # Fallback to emergency setup if regular setup fails
        self._setup_emergency_fallback()
        raise e

trace

trace(
    event: str,
    *args: Any,
    _foundation_logger_name: str | None = None,
    **kwargs: Any
) -> None

Log trace-level event for detailed debugging.

Source code in provide/foundation/logger/core.py

def trace(
    self,
    event: str,
    *args: Any,
    _foundation_logger_name: str | None = None,
    **kwargs: Any,
) -> None:
    """Log trace-level event for detailed debugging."""
    formatted_event = self._format_message_with_args(event, args)
    if _foundation_logger_name is not None:
        kwargs["_foundation_logger_name"] = _foundation_logger_name
    self._log_with_level(TRACE_LEVEL_NAME.lower(), formatted_event, **kwargs)

try_unbind

try_unbind(*keys: str) -> Any

Create a new logger with specified keys removed from context. Does not raise an error if keys don't exist.

Parameters:

Name	Type	Description	Default
*keys	str	Context keys to remove	()

Returns:

Type	Description
Any	A new logger instance without the specified keys

Source code in provide/foundation/logger/core.py

def try_unbind(self, *keys: str) -> Any:
    """Create a new logger with specified keys removed from context.
    Does not raise an error if keys don't exist.

    Args:
        *keys: Context keys to remove

    Returns:
        A new logger instance without the specified keys

    """
    self._ensure_configured()
    # Get the actual structlog logger and try_unbind context from it
    if hasattr(self, "_logger") and self._logger:
        return self._logger.try_unbind(*keys)
    # Fallback: get fresh logger and try_unbind
    log = self.get_logger()
    return log.try_unbind(*keys)

unbind

unbind(*keys: str) -> Any

Create a new logger with specified keys removed from context.

Parameters:

Name	Type	Description	Default
*keys	str	Context keys to remove	()

Returns:

Type	Description
Any	A new logger instance without the specified keys

Source code in provide/foundation/logger/core.py

def unbind(self, *keys: str) -> Any:
    """Create a new logger with specified keys removed from context.

    Args:
        *keys: Context keys to remove

    Returns:
        A new logger instance without the specified keys

    """
    self._ensure_configured()
    # Get the actual structlog logger and unbind context from it
    if hasattr(self, "_logger") and self._logger:
        return self._logger.unbind(*keys)
    # Fallback: get fresh logger and unbind
    log = self.get_logger()
    return log.unbind(*keys)

warning

warning(event: str, *args: Any, **kwargs: Any) -> None

Log warning-level event.

Source code in provide/foundation/logger/core.py

def warning(self, event: str, *args: Any, **kwargs: Any) -> None:
    """Log warning-level event."""
    formatted_event = self._format_message_with_args(event, args)
    self._log_with_level("warning", formatted_event, **kwargs)

GlobalLoggerProxy

Proxy object that forwards all attribute access to Hub-based logger.

Functions

__setattr__

__setattr__(name: str, value: Any) -> None

Allow tests to set internal state on the underlying logger.

Source code in provide/foundation/logger/core.py

def __setattr__(self, name: str, value: Any) -> None:
    """Allow tests to set internal state on the underlying logger."""
    if name.startswith("_"):
        # For internal attributes, set them on the actual logger instance
        logger = get_global_logger()
        setattr(logger, name, value)
    else:
        super().__setattr__(name, value)

Functions

get_global_logger

get_global_logger() -> FoundationLogger

Get the global FoundationLogger instance through Hub.

This function acts as the Composition Root for the global logger instance, maintained for backward compatibility.

Note: For building testable and maintainable applications, the recommended approach is to inject a logger instance via a Container. This global accessor should be avoided in new application code.

Returns:

Type	Description
FoundationLogger	FoundationLogger instance from Hub

Source code in provide/foundation/logger/core.py

def get_global_logger() -> FoundationLogger:
    """Get the global FoundationLogger instance through Hub.

    This function acts as the Composition Root for the global logger instance,
    maintained for backward compatibility.

    **Note:** For building testable and maintainable applications, the recommended
    approach is to inject a logger instance via a `Container`. This global
    accessor should be avoided in new application code.

    Returns:
        FoundationLogger instance from Hub

    """
    from provide.foundation.hub.manager import get_hub

    hub = get_hub()
    logger_instance = hub._component_registry.get("foundation.logger.instance", "singleton")

    if logger_instance:
        return logger_instance

    # Emergency fallback - create standalone logger
    return FoundationLogger()