interfaces

azure_bootstrap.services.interfaces

Service interfaces for Azure bootstrap library.

This module contains interface definitions for bootstrap services.

Modules:

Name	Description
application_bootstrap_interface	Interface for application bootstrap orchestrator.
bootstrap_logger_interface	Interface for bootstrap logging configuration.
telemetry_manager_interface	Interface for telemetry management.

Classes:

Name	Description
ApplicationBootstrapInterface	Interface for application bootstrap orchestrator.
BootstrapLoggerInterface	Interface for bootstrap logging manager.
TelemetryManagerInterface	Interface for telemetry manager.

ApplicationBootstrapInterface

Bases: ABC

Interface for application bootstrap orchestrator.

Defines the contract for handling the complete application startup sequence with proper logging flow.

Methods:

Name	Description
initialize	Execute the complete bootstrap sequence with proper logging flow.
get_config_repository	Get the configured repository after bootstrap.
is_bootstrap_completed	Check if bootstrap process has completed successfully.

initialize abstractmethod

initialize() -> EnhancedConfigRepositoryInterface

Execute the complete bootstrap sequence with proper logging flow.

This method orchestrates the entire application startup process following the correct sequence to avoid circular dependencies while ensuring working logging throughout.

Returns:

Type	Description
EnhancedConfigRepositoryInterface	Configured enhanced configuration repository with all configs loaded

Raises:

Type	Description
RuntimeError	If bootstrap fails in an unrecoverable way

Source code in azure_bootstrap/services/interfaces/application_bootstrap_interface.py

@abstractmethod
def initialize(self) -> "EnhancedConfigRepositoryInterface":
    """
    Execute the complete bootstrap sequence with proper logging flow.

    This method orchestrates the entire application startup process following
    the correct sequence to avoid circular dependencies while ensuring working
    logging throughout.

    Returns:
        Configured enhanced configuration repository with all configs loaded

    Raises:
        RuntimeError: If bootstrap fails in an unrecoverable way
    """
    pass

get_config_repository abstractmethod

get_config_repository() -> Optional[EnhancedConfigRepositoryInterface]

Get the configured repository after bootstrap.

Returns:

Type	Description
Optional[EnhancedConfigRepositoryInterface]	The enhanced configuration repository if bootstrap is complete, None otherwise

Source code in azure_bootstrap/services/interfaces/application_bootstrap_interface.py

@abstractmethod
def get_config_repository(self) -> Optional["EnhancedConfigRepositoryInterface"]:
    """
    Get the configured repository after bootstrap.

    Returns:
        The enhanced configuration repository if bootstrap is complete, None otherwise
    """
    pass

is_bootstrap_completed abstractmethod

is_bootstrap_completed() -> bool

Check if bootstrap process has completed successfully.

Returns:

Type	Description
bool	True if bootstrap completed successfully, False otherwise

Source code in azure_bootstrap/services/interfaces/application_bootstrap_interface.py

@abstractmethod
def is_bootstrap_completed(self) -> bool:
    """
    Check if bootstrap process has completed successfully.

    Returns:
        True if bootstrap completed successfully, False otherwise
    """
    pass

BootstrapLoggerInterface

Bases: ABC

Interface for bootstrap logging manager.

Defines the contract for providing safe logging before full configuration is loaded and App Insights is configured.

Methods:

Name	Description
configure_bootstrap_logging	Configure basic logging that works before full configuration is loaded.
is_bootstrap_configured	Check if bootstrap logging is configured.
create_logger	Create a logger with bootstrap configuration if not already done.

configure_bootstrap_logging abstractmethod classmethod

configure_bootstrap_logging(level: str = 'INFO') -> None

Configure basic logging that works before full configuration is loaded.

This provides immediate, safe logging during application bootstrap. Later, telemetry_manager.configure() will enhance it with App Insights.

Parameters:

Name	Type	Description	Default
level	str	Logging level (DEBUG, INFO, WARNING, ERROR)	'INFO'

Source code in azure_bootstrap/services/interfaces/bootstrap_logger_interface.py

@classmethod
@abstractmethod
def configure_bootstrap_logging(cls, level: str = "INFO") -> None:
    """
    Configure basic logging that works before full configuration is loaded.

    This provides immediate, safe logging during application bootstrap.
    Later, telemetry_manager.configure() will enhance it with App Insights.

    Args:
        level: Logging level (DEBUG, INFO, WARNING, ERROR)
    """
    pass

is_bootstrap_configured abstractmethod classmethod

is_bootstrap_configured() -> bool

Check if bootstrap logging is configured.

Returns:

Type	Description
bool	True if bootstrap logging is configured, False otherwise

Source code in azure_bootstrap/services/interfaces/bootstrap_logger_interface.py

@classmethod
@abstractmethod
def is_bootstrap_configured(cls) -> bool:
    """
    Check if bootstrap logging is configured.

    Returns:
        True if bootstrap logging is configured, False otherwise
    """
    pass

create_logger abstractmethod classmethod

create_logger(name: str) -> Logger

Create a logger with bootstrap configuration if not already done.

Parameters:

Name	Type	Description	Default
name	str	Logger name (typically name)	required

Returns:

Type	Description
Logger	Configured logger ready for use

Source code in azure_bootstrap/services/interfaces/bootstrap_logger_interface.py

@classmethod
@abstractmethod
def create_logger(cls, name: str) -> logging.Logger:
    """
    Create a logger with bootstrap configuration if not already done.

    Args:
        name: Logger name (typically __name__)

    Returns:
        Configured logger ready for use
    """
    pass

TelemetryManagerInterface

Bases: ABC

Interface for telemetry manager.

Defines the contract for managing Application Insights telemetry and structured logging throughout the application.

Methods:

Name	Description
configure	Configure Application Insights telemetry with support for bootstrap flow reconfiguration.
try_upgrade_from_config	Attempt to upgrade from basic logging to App Insights after config is loaded.
get_tracer	Get the configured tracer.
create_span	Create a new trace span.
log_email_processing_start	Log email processing start with structured data.
log_email_processing_success	Log successful email processing.
log_email_processing_error	Log email processing error.
log_queue_message_received	Log queue message processing.
log_storage_operation	Log storage operations.

configure abstractmethod

configure(connection_string: str | None = None, allow_reconfigure: bool = False) -> bool

Configure Application Insights telemetry with support for bootstrap flow reconfiguration.

Parameters:

Name	Type	Description	Default
connection_string	str | None	App Insights connection string	None
allow_reconfigure	bool	If True, allows reconfiguration even if already configured	False

Returns:

Type	Description
bool	True if configuration succeeded, False otherwise

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def configure(
    self, connection_string: str | None = None, allow_reconfigure: bool = False
) -> bool:
    """
    Configure Application Insights telemetry with support for bootstrap flow reconfiguration.

    Args:
        connection_string: App Insights connection string
        allow_reconfigure: If True, allows reconfiguration even if already configured

    Returns:
        True if configuration succeeded, False otherwise
    """
    pass

try_upgrade_from_config abstractmethod

try_upgrade_from_config(config_repository: EnhancedConfigRepositoryInterface) -> bool

Attempt to upgrade from basic logging to App Insights after config is loaded.

This method is called after configuration loading to check if an App Insights connection string is now available from App Config/Key Vault that wasn't available during initial bootstrap.

Parameters:

Name	Type	Description	Default
config_repository	EnhancedConfigRepositoryInterface	Enhanced config repository to check for connection string	required

Returns:

Type	Description
bool	True if upgrade was attempted (success or failure), False if no upgrade needed

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def try_upgrade_from_config(
    self, config_repository: "EnhancedConfigRepositoryInterface"
) -> bool:
    """
    Attempt to upgrade from basic logging to App Insights after config is loaded.

    This method is called after configuration loading to check if an App Insights
    connection string is now available from App Config/Key Vault that wasn't
    available during initial bootstrap.

    Args:
        config_repository: Enhanced config repository to check for connection string

    Returns:
        True if upgrade was attempted (success or failure), False if no upgrade needed
    """
    pass

get_tracer abstractmethod

get_tracer() -> Any

Get the configured tracer.

Returns:

Type	Description
Any	The OpenTelemetry tracer instance if configured, None otherwise

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def get_tracer(self) -> Any:
    """
    Get the configured tracer.

    Returns:
        The OpenTelemetry tracer instance if configured, None otherwise
    """
    pass

create_span abstractmethod

create_span(name: str, attributes: dict[str, Any] | None = None) -> Any

Create a new trace span.

Parameters:

Name	Type	Description	Default
name	str	Name of the span	required
attributes	dict[str, Any] | None	Optional attributes to attach to the span	None

Returns:

Type	Description
Any	Span instance if telemetry is configured, None otherwise

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def create_span(self, name: str, attributes: dict[str, Any] | None = None) -> Any:
    """
    Create a new trace span.

    Args:
        name: Name of the span
        attributes: Optional attributes to attach to the span

    Returns:
        Span instance if telemetry is configured, None otherwise
    """
    pass

log_email_processing_start abstractmethod

log_email_processing_start(message_id: str | None = None, user_email: str | None = None) -> None

Log email processing start with structured data.

Parameters:

Name	Type	Description	Default
message_id	str | None	Email message ID	None
user_email	str | None	User email address	None

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def log_email_processing_start(
    self, message_id: str | None = None, user_email: str | None = None
) -> None:
    """
    Log email processing start with structured data.

    Args:
        message_id: Email message ID
        user_email: User email address
    """
    pass

log_email_processing_success abstractmethod

log_email_processing_success(message_id: str, user_email: str, processing_time_ms: int) -> None

Log successful email processing.

Parameters:

Name	Type	Description	Default
message_id	str	Email message ID	required
user_email	str	User email address	required
processing_time_ms	int	Processing time in milliseconds	required

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def log_email_processing_success(
    self, message_id: str, user_email: str, processing_time_ms: int
) -> None:
    """
    Log successful email processing.

    Args:
        message_id: Email message ID
        user_email: User email address
        processing_time_ms: Processing time in milliseconds
    """
    pass

log_email_processing_error abstractmethod

log_email_processing_error(error: str, message_id: str | None = None, user_email: str | None = None) -> None

Log email processing error.

Parameters:

Name	Type	Description	Default
error	str	Error message	required
message_id	str | None	Email message ID (if available)	None
user_email	str | None	User email address (if available)	None

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def log_email_processing_error(
    self, error: str, message_id: str | None = None, user_email: str | None = None
) -> None:
    """
    Log email processing error.

    Args:
        error: Error message
        message_id: Email message ID (if available)
        user_email: User email address (if available)
    """
    pass

log_queue_message_received abstractmethod

log_queue_message_received(queue_name: str, message_id: str) -> None

Log queue message processing.

Parameters:

Name	Type	Description	Default
queue_name	str	Name of the queue	required
message_id	str	Message ID	required

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def log_queue_message_received(self, queue_name: str, message_id: str) -> None:
    """
    Log queue message processing.

    Args:
        queue_name: Name of the queue
        message_id: Message ID
    """
    pass

log_storage_operation abstractmethod

log_storage_operation(operation: str, container: str, blob_name: str, success: bool) -> None

Log storage operations.

Parameters:

Name	Type	Description	Default
operation	str	Type of storage operation	required
container	str	Storage container name	required
blob_name	str	Blob name	required
success	bool	Whether the operation succeeded	required

Source code in azure_bootstrap/services/interfaces/telemetry_manager_interface.py

@abstractmethod
def log_storage_operation(
    self, operation: str, container: str, blob_name: str, success: bool
) -> None:
    """
    Log storage operations.

    Args:
        operation: Type of storage operation
        container: Storage container name
        blob_name: Blob name
        success: Whether the operation succeeded
    """
    pass