azpaddypy 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

azpaddypy/mgmt/logging.py

@@ -4,21 +4,27 @@ import json
 import functools
 import time
 import asyncio
-from typing import Optional, Dict, Any, Union, List
+from typing import Optional, Dict, Any, Union, Callable
 from datetime import datetime
 from azure.monitor.opentelemetry import configure_azure_monitor
+from opentelemetry.metrics import get_meter_provider
+from opentelemetry.trace import get_tracer_provider
+from opentelemetry._logs import get_logger_provider
 from opentelemetry import trace
 from opentelemetry.trace import Status, StatusCode, Span
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.resources import Resource
 from opentelemetry import baggage
 from opentelemetry.context import Context
 
 
 class AzureLogger:
     """
-    Comprehensive logging class for Azure Functions and Azure Web Apps
-    using Azure Monitor OpenTelemetry integration with advanced tracing capabilities.
+    A comprehensive logging class for Azure applications.
+
+    This logger integrates with Azure Monitor OpenTelemetry for distributed
+    tracing and structured logging, providing advanced capabilities for
+
+    It supports correlation tracking, baggage propagation, and automated
+    tracing for functions and dependencies.
     """
 
     def __init__(
@@ -29,6 +35,7 @@ class AzureLogger:
         log_level: int = logging.INFO,
         enable_console_logging: bool = True,
         custom_resource_attributes: Optional[Dict[str, str]] = None,
+        clean_legacy_logging: bool = True,
     ):
         """
         Initialize the Azure Logger with OpenTelemetry tracing
@@ -40,7 +47,20 @@ class AzureLogger:
             log_level: Logging level (default: INFO)
             enable_console_logging: Enable console output for local development
             custom_resource_attributes: Additional resource attributes
+            clean_legacy_logging: A flag to clean up legacy logging providers.
         """
+        if clean_legacy_logging:
+            # cleaning stale loggers
+            logger_provider = get_logger_provider()
+            if logger_provider:
+                logger_provider.shutdown()
+            tracer_provider = get_tracer_provider()
+            if tracer_provider:
+                tracer_provider.shutdown()
+            meter_provider = get_meter_provider()
+            if meter_provider:
+                meter_provider.shutdown()
+
         self.service_name = service_name
         self.service_version = service_version
         self.connection_string = connection_string or os.getenv(
@@ -97,7 +117,12 @@ class AzureLogger:
         )
 
     def _setup_console_handler(self):
-        """Setup console logging handler with structured format"""
+        """Sets up a console handler for logging to the standard output.
+
+        This is useful for local development and debugging purposes. The handler
+        is configured with a structured formatter to ensure log messages are
+        consistent and easy to read.
+        """
         console_handler = logging.StreamHandler()
         formatter = logging.Formatter(
             "%(asctime)s - %(name)s - %(levelname)s - %(message)s - %(pathname)s:%(lineno)d"
@@ -106,11 +131,22 @@ class AzureLogger:
         self.logger.addHandler(console_handler)
 
     def set_correlation_id(self, correlation_id: str):
-        """Set correlation ID for request tracking"""
+        """Sets a correlation ID for tracking a request or transaction.
+
+        This ID is automatically included in all subsequent logs and traces,
+        allowing for easy filtering and correlation of telemetry data.
+
+        Args:
+            correlation_id: The unique identifier for the transaction.
+        """
         self._correlation_id = correlation_id
 
     def get_correlation_id(self) -> Optional[str]:
-        """Get current correlation ID"""
+        """Retrieves the current correlation ID.
+
+        Returns:
+            The current correlation ID if it has been set, otherwise None.
+        """
         return self._correlation_id
 
     def set_baggage(self, key: str, value: str) -> Context:
@@ -128,27 +164,38 @@ class AzureLogger:
 
     def get_baggage(self, key: str) -> Optional[str]:
         """
-        Get a baggage item from the current context
+        Retrieves a baggage item from the current OpenTelemetry context.
 
         Args:
-            key: Baggage key
+            key: The baggage key.
 
         Returns:
-            Baggage value if exists, None otherwise
+            The baggage value if it exists, otherwise None.
         """
         return baggage.get_baggage(key)
 
     def get_all_baggage(self) -> Dict[str, str]:
         """
-        Get all baggage items from the current context
+        Retrieves all baggage items from the current OpenTelemetry context.
 
         Returns:
-            Dictionary of all baggage items
+            A dictionary containing all baggage items.
         """
         return dict(baggage.get_all())
 
     def _enhance_extra(self, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Enhance log extra data with correlation and service info"""
+        """
+        Enriches log records with contextual information.
+
+        This method adds service details, correlation IDs, trace context,
+        and baggage items to the log's `extra` dictionary.
+
+        Args:
+            extra: An optional dictionary of custom data to include.
+
+        Returns:
+            The enhanced dictionary with added contextual data.
+        """
         enhanced_extra = {
             "service_name": self.service_name,
             "service_version": self.service_version,
@@ -176,15 +223,15 @@ class AzureLogger:
         return enhanced_extra
 
     def debug(self, message: str, extra: Optional[Dict[str, Any]] = None):
-        """Log debug message with enhanced context"""
+        """Logs a debug message with enhanced context."""
         self.logger.debug(message, extra=self._enhance_extra(extra))
 
     def info(self, message: str, extra: Optional[Dict[str, Any]] = None):
-        """Log info message with enhanced context"""
+        """Logs an info message with enhanced context."""
         self.logger.info(message, extra=self._enhance_extra(extra))
 
     def warning(self, message: str, extra: Optional[Dict[str, Any]] = None):
-        """Log warning message with enhanced context"""
+        """Logs a warning message with enhanced context."""
         self.logger.warning(message, extra=self._enhance_extra(extra))
 
     def error(
@@ -193,11 +240,11 @@ class AzureLogger:
         extra: Optional[Dict[str, Any]] = None,
         exc_info: bool = True,
     ):
-        """Log error message with enhanced context and exception info"""
+        """Logs an error message with enhanced context and exception info."""
         self.logger.error(message, extra=self._enhance_extra(extra), exc_info=exc_info)
 
     def critical(self, message: str, extra: Optional[Dict[str, Any]] = None):
-        """Log critical message with enhanced context"""
+        """Logs a critical message with enhanced context."""
         self.logger.critical(message, extra=self._enhance_extra(extra))
 
     def log_function_execution(
@@ -208,13 +255,16 @@ class AzureLogger:
         extra: Optional[Dict[str, Any]] = None,
     ):
         """
-        Log function execution metrics with performance data
+        Logs a custom event for a function's execution metrics.
+
+        This captures performance data such as duration and success status,
+        which can be queried in Azure Monitor.
 
         Args:
-            function_name: Name of the executed function
-            duration_ms: Execution duration in milliseconds
-            success: Whether the function executed successfully
-            extra: Additional custom properties
+            function_name: The name of the executed function.
+            duration_ms: The execution duration in milliseconds.
+            success: A flag indicating whether the function executed successfully.
+            extra: Additional custom properties to include in the log.
         """
         log_data = {
             "function_name": function_name,
@@ -310,13 +360,105 @@ class AzureLogger:
 
         return span
 
+    def _setup_span_for_function_trace(
+        self,
+        span: Span,
+        func: Callable,
+        is_async: bool,
+        log_args: bool,
+        args: tuple,
+        kwargs: dict,
+    ):
+        """Helper to set up span attributes for function tracing."""
+        span.set_attribute("function.name", func.__name__)
+        span.set_attribute("function.module", func.__module__)
+        span.set_attribute("service.name", self.service_name)
+        span.set_attribute("function.is_async", is_async)
+
+        if self._correlation_id:
+            span.set_attribute("correlation.id", self._correlation_id)
+
+        if log_args:
+            if args:
+                span.set_attribute("function.args_count", len(args))
+            if kwargs:
+                span.set_attribute("function.kwargs_count", len(kwargs))
+
+    def _handle_function_success(
+        self,
+        span: Span,
+        func: Callable,
+        duration_ms: float,
+        result: Any,
+        log_result: bool,
+        log_execution: bool,
+        is_async: bool,
+        args: tuple,
+        kwargs: dict,
+    ):
+        """Helper to handle successful function execution tracing."""
+        span.set_attribute("function.duration_ms", duration_ms)
+        span.set_attribute("function.success", True)
+        span.set_status(Status(StatusCode.OK))
+
+        if log_result and result is not None:
+            span.set_attribute("function.has_result", True)
+            span.set_attribute("function.result_type", type(result).__name__)
+
+        if log_execution:
+            self.log_function_execution(
+                func.__name__,
+                duration_ms,
+                True,
+                {
+                    "args_count": len(args) if args else 0,
+                    "kwargs_count": len(kwargs) if kwargs else 0,
+                    "is_async": is_async,
+                },
+            )
+
+        log_prefix = "Async function" if is_async else "Function"
+        self.debug(f"{log_prefix} execution completed: {func.__name__}")
+
+    def _handle_function_exception(
+        self,
+        span: Span,
+        func: Callable,
+        duration_ms: float,
+        e: Exception,
+        log_execution: bool,
+        is_async: bool,
+    ):
+        """Helper to handle failed function execution tracing."""
+        span.set_status(Status(StatusCode.ERROR, str(e)))
+        span.record_exception(e)
+        span.set_attribute("function.duration_ms", duration_ms)
+        span.set_attribute("function.success", False)
+        span.set_attribute("error.type", type(e).__name__)
+        span.set_attribute("error.message", str(e))
+
+        if log_execution:
+            self.log_function_execution(
+                func.__name__,
+                duration_ms,
+                False,
+                {
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "is_async": is_async,
+                },
+            )
+
+        log_prefix = "Async function" if is_async else "Function"
+        self.error(f"{log_prefix} execution failed: {func.__name__} - {str(e)}")
+
     def trace_function(
         self,
         function_name: Optional[str] = None,
         log_args: bool = False,
         log_result: bool = False,
         log_execution: bool = True,
-    ):
+    ) -> Callable:
         """
         Decorator to automatically trace function execution with comprehensive logging.
         Supports both synchronous and asynchronous functions.
@@ -332,166 +474,64 @@ class AzureLogger:
             @functools.wraps(func)
             async def async_wrapper(*args, **kwargs):
                 span_name = function_name or f"{func.__module__}.{func.__name__}"
-
                 with self.tracer.start_as_current_span(span_name) as span:
-                    # Add function metadata
-                    span.set_attribute("function.name", func.__name__)
-                    span.set_attribute("function.module", func.__module__)
-                    span.set_attribute("service.name", self.service_name)
-                    span.set_attribute("function.is_async", True)
-
-                    if self._correlation_id:
-                        span.set_attribute("correlation.id", self._correlation_id)
-
-                    if log_args and args:
-                        span.set_attribute("function.args_count", len(args))
-                    if log_args and kwargs:
-                        span.set_attribute("function.kwargs_count", len(kwargs))
-
+                    self._setup_span_for_function_trace(
+                        span, func, True, log_args, args, kwargs
+                    )
                     start_time = time.time()
-
                     try:
                         self.debug(
                             f"Starting async function execution: {func.__name__}"
                         )
-
                         result = await func(*args, **kwargs)
                         duration_ms = (time.time() - start_time) * 1000
-
-                        # Mark span as successful
-                        span.set_attribute("function.duration_ms", duration_ms)
-                        span.set_attribute("function.success", True)
-                        span.set_status(Status(StatusCode.OK))
-
-                        if log_result and result is not None:
-                            span.set_attribute("function.has_result", True)
-                            span.set_attribute(
-                                "function.result_type", type(result).__name__
-                            )
-
-                        if log_execution:
-                            self.log_function_execution(
-                                func.__name__,
-                                duration_ms,
-                                True,
-                                {
-                                    "args_count": len(args) if args else 0,
-                                    "kwargs_count": len(kwargs) if kwargs else 0,
-                                    "is_async": True,
-                                },
-                            )
-
-                        self.debug(
-                            f"Async function execution completed: {func.__name__}"
+                        self._handle_function_success(
+                            span,
+                            func,
+                            duration_ms,
+                            result,
+                            log_result,
+                            log_execution,
+                            True,
+                            args,
+                            kwargs,
                         )
                         return result
-
                     except Exception as e:
                         duration_ms = (time.time() - start_time) * 1000
-
-                        # Mark span as failed
-                        span.set_status(Status(StatusCode.ERROR, str(e)))
-                        span.record_exception(e)
-                        span.set_attribute("function.duration_ms", duration_ms)
-                        span.set_attribute("function.success", False)
-                        span.set_attribute("error.type", type(e).__name__)
-                        span.set_attribute("error.message", str(e))
-
-                        if log_execution:
-                            self.log_function_execution(
-                                func.__name__,
-                                duration_ms,
-                                False,
-                                {
-                                    "error_type": type(e).__name__,
-                                    "error_message": str(e),
-                                    "is_async": True,
-                                },
-                            )
-
-                        self.error(
-                            f"Async function execution failed: {func.__name__} - {str(e)}"
+                        self._handle_function_exception(
+                            span, func, duration_ms, e, log_execution, True
                         )
                         raise
 
             @functools.wraps(func)
             def sync_wrapper(*args, **kwargs):
                 span_name = function_name or f"{func.__module__}.{func.__name__}"
-
                 with self.tracer.start_as_current_span(span_name) as span:
-                    # Add function metadata
-                    span.set_attribute("function.name", func.__name__)
-                    span.set_attribute("function.module", func.__module__)
-                    span.set_attribute("service.name", self.service_name)
-                    span.set_attribute("function.is_async", False)
-
-                    if self._correlation_id:
-                        span.set_attribute("correlation.id", self._correlation_id)
-
-                    if log_args and args:
-                        span.set_attribute("function.args_count", len(args))
-                    if log_args and kwargs:
-                        span.set_attribute("function.kwargs_count", len(kwargs))
-
+                    self._setup_span_for_function_trace(
+                        span, func, False, log_args, args, kwargs
+                    )
                     start_time = time.time()
-
                     try:
                         self.debug(f"Starting function execution: {func.__name__}")
-
                         result = func(*args, **kwargs)
                         duration_ms = (time.time() - start_time) * 1000
-
-                        # Mark span as successful
-                        span.set_attribute("function.duration_ms", duration_ms)
-                        span.set_attribute("function.success", True)
-                        span.set_status(Status(StatusCode.OK))
-
-                        if log_result and result is not None:
-                            span.set_attribute("function.has_result", True)
-                            span.set_attribute(
-                                "function.result_type", type(result).__name__
-                            )
-
-                        if log_execution:
-                            self.log_function_execution(
-                                func.__name__,
-                                duration_ms,
-                                True,
-                                {
-                                    "args_count": len(args) if args else 0,
-                                    "kwargs_count": len(kwargs) if kwargs else 0,
-                                    "is_async": False,
-                                },
-                            )
-
-                        self.debug(f"Function execution completed: {func.__name__}")
+                        self._handle_function_success(
+                            span,
+                            func,
+                            duration_ms,
+                            result,
+                            log_result,
+                            log_execution,
+                            False,
+                            args,
+                            kwargs,
+                        )
                         return result
-
                     except Exception as e:
                         duration_ms = (time.time() - start_time) * 1000
-
-                        # Mark span as failed
-                        span.set_status(Status(StatusCode.ERROR, str(e)))
-                        span.record_exception(e)
-                        span.set_attribute("function.duration_ms", duration_ms)
-                        span.set_attribute("function.success", False)
-                        span.set_attribute("error.type", type(e).__name__)
-                        span.set_attribute("error.message", str(e))
-
-                        if log_execution:
-                            self.log_function_execution(
-                                func.__name__,
-                                duration_ms,
-                                False,
-                                {
-                                    "error_type": type(e).__name__,
-                                    "error_message": str(e),
-                                    "is_async": False,
-                                },
-                            )
-
-                        self.error(
-                            f"Function execution failed: {func.__name__} - {str(e)}"
+                        self._handle_function_exception(
+                            span, func, duration_ms, e, log_execution, False
                         )
                         raise
 
@@ -604,6 +644,9 @@ class AzureLogger:
 
 
 # Factory functions for easy instantiation
+_loggers: Dict[Any, "AzureLogger"] = {}
+
+
 def create_app_logger(
     service_name: str,
     service_version: str = "1.0.0",
@@ -611,9 +654,11 @@ def create_app_logger(
     log_level: int = logging.INFO,
     enable_console_logging: bool = True,
     custom_resource_attributes: Optional[Dict[str, str]] = None,
+    clean_legacy_logging: bool = True,
 ) -> AzureLogger:
     """
-    Factory function to create an AzureLogger instance
+    Factory function to create an AzureLogger instance. If a logger with the
+    same configuration has already been created, it will be returned.
 
     Args:
         service_name: Name of your service/application
@@ -622,18 +667,45 @@ def create_app_logger(
         log_level: Logging level
         enable_console_logging: Enable console output
         custom_resource_attributes: Additional resource attributes
+        clean_legacy_logging: Whether to clean up legacy logging providers.
 
     Returns:
         Configured AzureLogger instance
     """
-    return AzureLogger(
+    resolved_connection_string = connection_string or os.getenv(
+        "APPLICATIONINSIGHTS_CONNECTION_STRING"
+    )
+
+    attr_items = (
+        tuple(sorted(custom_resource_attributes.items()))
+        if custom_resource_attributes
+        else None
+    )
+
+    params_key = (
+        service_name,
+        service_version,
+        resolved_connection_string,
+        log_level,
+        enable_console_logging,
+        attr_items,
+        clean_legacy_logging,
+    )
+
+    if params_key in _loggers:
+        return _loggers[params_key]
+
+    logger = AzureLogger(
         service_name=service_name,
         service_version=service_version,
         connection_string=connection_string,
         log_level=log_level,
         enable_console_logging=enable_console_logging,
         custom_resource_attributes=custom_resource_attributes,
+        clean_legacy_logging=clean_legacy_logging,
     )
+    _loggers[params_key] = logger
+    return logger
 
 
 def create_function_logger(
@@ -641,6 +713,7 @@ def create_function_logger(
     function_name: str,
     service_version: str = "1.0.0",
     connection_string: Optional[str] = None,
+    clean_legacy_logging: bool = True,
 ) -> AzureLogger:
     """
     Factory function specifically for Azure Functions
@@ -665,4 +738,5 @@ def create_function_logger(
         service_version=service_version,
         connection_string=connection_string,
         custom_resource_attributes=custom_attributes,
+        clean_legacy_logging=clean_legacy_logging,
     )

azpaddypy-0.2.3.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: azpaddypy
+Version: 0.2.3
+Summary: Comprehensive Python logger for Azure, integrating OpenTelemetry for advanced, structured, and distributed tracing.
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: azure-monitor-opentelemetry==1.6.10
+Provides-Extra: dev
+Requires-Dist: trio>=0.22.2; extra == "dev"
+Requires-Dist: azure-functions>=1.17.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.1; extra == "dev"
+Requires-Dist: anyio>=3.7.1; extra == "dev"
+Requires-Dist: pip; extra == "dev"
+Dynamic: license-file

azpaddypy-0.2.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+azpaddypy/mgmt/__init__.py,sha256=5-0eZuJMZlCONZNJ5hEvWXfvLIM36mg7FsEVs32bY_A,183
+azpaddypy/mgmt/logging.py,sha256=LI7pvMuiUbT-RoW5wImyWxZTzexxvA6IDSD4RVyxCkg,26918
+azpaddypy/test_function/__init__.py,sha256=0NjUl36wvUWV79GpRwBFkgkBaC6uDZsTdaSVOIHMFEU,3481
+azpaddypy/test_function/function_app.py,sha256=6nX54-iq0L1l_hZpD6E744-j79oLxdaldFyWDCpwH7c,3867
+azpaddypy-0.2.3.dist-info/licenses/LICENSE,sha256=hQ6t0g2QaewGCQICHqTckBFbMVakGmoyTAzDpmEYV4c,1089
+azpaddypy-0.2.3.dist-info/METADATA,sha256=vEWDGAtY5Cxvz3qLRA9fJEeUjFObLaElceLsZGsyDi0,799
+azpaddypy-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+azpaddypy-0.2.3.dist-info/top_level.txt,sha256=hsDuboDhT61320ML8X479ezSTwT3rrlDWz1_Z45B2cs,10
+azpaddypy-0.2.3.dist-info/RECORD,,

azpaddypy-0.2.1.dist-info/METADATA

@@ -1,10 +0,0 @@
-Metadata-Version: 2.4
-Name: azpaddypy
-Version: 0.2.1
-Summary: Add your description here
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: azure-monitor-opentelemetry==1.6.10
-Dynamic: license-file

azpaddypy-0.2.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-azpaddypy/mgmt/__init__.py,sha256=5-0eZuJMZlCONZNJ5hEvWXfvLIM36mg7FsEVs32bY_A,183
-azpaddypy/mgmt/logging.py,sha256=9u114Ji-cwBMUf8D02i_b_Ei2dZc3TaIUH4uJv_tmSc,25451
-azpaddypy/test_function/__init__.py,sha256=0NjUl36wvUWV79GpRwBFkgkBaC6uDZsTdaSVOIHMFEU,3481
-azpaddypy/test_function/function_app.py,sha256=6nX54-iq0L1l_hZpD6E744-j79oLxdaldFyWDCpwH7c,3867
-azpaddypy-0.2.1.dist-info/licenses/LICENSE,sha256=hQ6t0g2QaewGCQICHqTckBFbMVakGmoyTAzDpmEYV4c,1089
-azpaddypy-0.2.1.dist-info/METADATA,sha256=ShjmEYaQg37Y05nj6Jv4zdm2KlU2Bkfo1ya0z5IdnUo,304
-azpaddypy-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-azpaddypy-0.2.1.dist-info/top_level.txt,sha256=hsDuboDhT61320ML8X479ezSTwT3rrlDWz1_Z45B2cs,10
-azpaddypy-0.2.1.dist-info/RECORD,,