Core

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

provide.foundation.logger.core

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
    # Effective numeric level for fast short-circuit checks.
    # 0 (NOTSET) means "not yet configured — let everything through".
    self._effective_level: int = 0

Functions

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

    """
    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)

is_debug_enabled

is_debug_enabled() -> bool

Check if debug-level logging is enabled.

Use this to guard expensive argument construction::

if logger.is_debug_enabled():
    logger.debug("result", payload=model.model_dump_json())

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

def is_debug_enabled(self) -> bool:
    """Check if debug-level logging is enabled.

    Use this to guard expensive argument construction::

        if logger.is_debug_enabled():
            logger.debug("result", payload=model.model_dump_json())
    """
    return self._effective_level <= _DEBUG_LEVEL

is_trace_enabled

is_trace_enabled() -> bool

Check if trace-level logging is enabled.

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

def is_trace_enabled(self) -> bool:
    """Check if trace-level logging is enabled."""
    return self._effective_level <= _TRACE_LEVEL

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

    # Cache the effective numeric level for fast short-circuit checks
    self._effective_level = _LEVEL_TO_NUMERIC.get(
        getattr(getattr(config, "logging", None), "default_level", "INFO"),
        _stdlib_logging.INFO,
    )

    # 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

    """
    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

    """
    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)

is_debug_enabled

is_debug_enabled() -> bool

Check if debug-level logging is enabled.

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

def is_debug_enabled(self) -> bool:
    """Check if debug-level logging is enabled."""
    return get_global_logger().is_debug_enabled()

is_trace_enabled

is_trace_enabled() -> bool

Check if trace-level logging is enabled.

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

def is_trace_enabled(self) -> bool:
    """Check if trace-level logging is enabled."""
    return get_global_logger().is_trace_enabled()

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: FoundationLogger | None = hub._component_registry.get(
        "foundation.logger.instance", "singleton"
    )

    if logger_instance:
        return logger_instance

    # Emergency fallback - create standalone logger
    return FoundationLogger()

is_debug_enabled

is_debug_enabled() -> bool

Standalone check if debug-level logging is enabled.

Use to guard expensive argument construction::

from provide.foundation.logger import is_debug_enabled
if is_debug_enabled():
    logger.debug("result", payload=model.model_dump_json())

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

def is_debug_enabled() -> bool:
    """Standalone check if debug-level logging is enabled.

    Use to guard expensive argument construction::

        from provide.foundation.logger import is_debug_enabled
        if is_debug_enabled():
            logger.debug("result", payload=model.model_dump_json())
    """
    return get_global_logger().is_debug_enabled()

is_trace_enabled

is_trace_enabled() -> bool

Standalone check if trace-level logging is enabled.

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

def is_trace_enabled() -> bool:
    """Standalone check if trace-level logging is enabled."""
    return get_global_logger().is_trace_enabled()