azpaddypy 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

azpaddypy/mgmt/__init__.py

@@ -4,6 +4,10 @@ AzPaddyPy - A standardized Python package for Azure cloud services integration.
 
 __version__ = "0.1.0"
 
-from azpaddypy.mgmt import logging
+from azpaddypy.mgmt.logging import AzureLogger
+from azpaddypy.mgmt.identity import AzureIdentity
 
-__all__ = ["AzureLogger"]
+__all__ = [
+    "AzureLogger", 
+    "AzureIdentity",
+]

azpaddypy/mgmt/identity.py

@@ -0,0 +1,335 @@
+from typing import Optional, Dict, Any, Union
+from azure.identity import (
+    TokenCachePersistenceOptions,
+    get_bearer_token_provider,
+    DefaultAzureCredential
+)
+from azure.core.credentials import AccessToken, TokenCredential
+from .logging import AzureLogger
+
+
+class AzureIdentity:
+    """Azure identity management with token caching and distributed tracing.
+
+    Provides standardized Azure authentication using DefaultAzureCredential
+    with integrated logging, caching, and OpenTelemetry tracing support.
+    Prioritizes Managed Identity, then Environment variables per Azure SDK
+    best practices.
+
+    Attributes:
+        service_name: Service identifier for logging and tracing
+        service_version: Service version for context
+        enable_token_cache: Whether token caching is enabled
+        allow_unencrypted_storage: Whether to allow unencrypted token storage
+        logger: AzureLogger instance for structured logging
+    """
+
+    def __init__(
+        self,
+        service_name: str = "azure_identity",
+        service_version: str = "1.0.0",
+        enable_token_cache: bool = True,
+        allow_unencrypted_storage: bool = True,
+        custom_credential_options: Optional[Dict[str, Any]] = None,
+        logger: Optional[AzureLogger] = None,
+        connection_string: Optional[str] = None,
+    ):
+        """Initialize Azure Identity with comprehensive configuration.
+
+        Args:
+            service_name: Service name for tracing context
+            service_version: Service version for metadata
+            enable_token_cache: Enable in-memory token persistence
+            allow_unencrypted_storage: Allow unencrypted token storage
+            custom_credential_options: Additional DefaultAzureCredential options
+            logger: Optional AzureLogger instance
+            connection_string: Application Insights connection string
+        """
+        self.service_name = service_name
+        self.service_version = service_version
+        self.enable_token_cache = enable_token_cache
+        self.allow_unencrypted_storage = allow_unencrypted_storage
+
+        # Initialize logger - use provided instance or create new one
+        if logger is not None:
+            self.logger = logger
+        else:
+            self.logger = AzureLogger(
+                service_name=service_name,
+                service_version=service_version,
+                connection_string=connection_string,
+                enable_console_logging=True,
+            )
+
+        self._credential = None
+        self._setup_credential(custom_credential_options)
+
+        self.logger.info(
+            f"Azure Identity initialized for service '{service_name}' v{service_version}"
+        )
+
+    def _setup_credential(self, custom_options: Optional[Dict[str, Any]] = None):
+        """Configure DefaultAzureCredential with appropriate settings.
+
+        Args:
+            custom_options: Additional options for DefaultAzureCredential
+
+        Raises:
+            Exception: If credential initialization fails
+        """
+        try:
+            credential_options = {}
+
+            # Add token cache configuration if enabled
+            if self.enable_token_cache:
+                token_cache_options = TokenCachePersistenceOptions(
+                    allow_unencrypted_storage=self.allow_unencrypted_storage
+                )
+                credential_options["token_cache_persistence_options"] = token_cache_options
+
+            # Merge custom options
+            if custom_options:
+                credential_options.update(custom_options)
+
+            self._credential = DefaultAzureCredential(**credential_options)
+            
+            self.logger.debug(
+                "DefaultAzureCredential configured successfully",
+                extra={
+                    "token_cache_enabled": self.enable_token_cache,
+                    "unencrypted_storage": self.allow_unencrypted_storage,
+                }
+            )
+
+        except Exception as e:
+            self.logger.error(
+                f"Failed to initialize DefaultAzureCredential: {e}",
+                exc_info=True
+            )
+            raise
+
+    def get_credential(self) -> TokenCredential:
+        """Get the configured DefaultAzureCredential instance.
+
+        Returns:
+            Configured TokenCredential instance
+
+        Raises:
+            RuntimeError: If credential is not initialized
+        """
+        with self.logger.create_span(
+            "AzureIdentity.get_credential",
+            attributes={
+                "service.name": self.service_name,
+                "operation.type": "credential_retrieval"
+            }
+        ):
+            if self._credential is None:
+                error_msg = "Credential not initialized"
+                self.logger.error(error_msg)
+                raise RuntimeError(error_msg)
+
+            self.logger.debug("Retrieving DefaultAzureCredential instance")
+            return self._credential
+
+    def get_token(
+        self, 
+        scopes: Union[str, list],
+        **kwargs
+    ) -> AccessToken:
+        """Acquire an access token for specified scopes.
+
+        Args:
+            scopes: Target scope(s) for token request
+            **kwargs: Additional token request parameters
+
+        Returns:
+            AccessToken with token and expiration information
+
+        Raises:
+            RuntimeError: If credential is not initialized
+            Exception: If token acquisition fails
+        """
+        # Normalize to list format
+        if isinstance(scopes, str):
+            scopes = [scopes]
+
+        with self.logger.create_span(
+            "AzureIdentity.get_token",
+            attributes={
+                "service.name": self.service_name,
+                "operation.type": "token_acquisition",
+                "token.scopes": ", ".join(scopes),
+                "token.scope_count": len(scopes)
+            }
+        ):
+            if self._credential is None:
+                raise RuntimeError("Credential not initialized")
+
+            self.logger.debug(
+                "Acquiring access token",
+                extra={
+                    "scopes": scopes,
+                    "scope_count": len(scopes)
+                }
+            )
+
+            token = self._credential.get_token(*scopes, **kwargs)
+            
+            self.logger.info(
+                "Access token acquired successfully",
+                extra={
+                    "scopes": scopes,
+                    "expires_on": token.expires_on if hasattr(token, 'expires_on') else None
+                }
+            )
+            
+            return token
+
+    def get_token_provider(
+        self, 
+        scopes: Union[str, list],
+        **kwargs
+    ) -> callable:
+        """Create a bearer token provider for specified scopes.
+
+        Useful for Azure SDK clients that accept token providers.
+
+        Args:
+            scopes: Target scope(s) for the token provider
+            **kwargs: Additional token provider parameters
+
+        Returns:
+            Callable that returns bearer tokens
+
+        Raises:
+            RuntimeError: If credential is not initialized
+            Exception: If token provider creation fails
+        """
+        # Normalize to list format
+        if isinstance(scopes, str):
+            scopes = [scopes]
+
+        with self.logger.create_span(
+            "AzureIdentity.get_token_provider",
+            attributes={
+                "service.name": self.service_name,
+                "operation.type": "token_provider_creation",
+                "token.scopes": ", ".join(scopes),
+                "token.scope_count": len(scopes)
+            }
+        ):
+            if self._credential is None:
+                raise RuntimeError("Credential not initialized")
+
+            self.logger.debug(
+                "Creating bearer token provider",
+                extra={
+                    "scopes": scopes,
+                    "scope_count": len(scopes)
+                }
+            )
+
+            provider = get_bearer_token_provider(self._credential, *scopes, **kwargs)
+            
+            self.logger.info(
+                "Bearer token provider created successfully",
+                extra={
+                    "scopes": scopes
+                }
+            )
+            
+            return provider
+
+    def test_credential(self, test_scopes: Optional[Union[str, list]] = None) -> bool:
+        """Test credential by attempting token acquisition.
+
+        Args:
+            test_scopes: Scopes to test with (defaults to Azure Management API)
+
+        Returns:
+            True if credential works, False otherwise
+        """
+        if test_scopes is None:
+            test_scopes = ["https://management.azure.com/.default"]
+        elif isinstance(test_scopes, str):
+            test_scopes = [test_scopes]
+
+        with self.logger.create_span(
+            "AzureIdentity.test_credential",
+            attributes={
+                "service.name": self.service_name,
+                "operation.type": "credential_test",
+                "test.scopes": ", ".join(test_scopes)
+            }
+        ):
+            try:
+                self.logger.info("Testing credential authentication")
+                token = self.get_token(test_scopes)
+                
+                if token and hasattr(token, 'token') and token.token:
+                    self.logger.info("Credential test successful")
+                    return True
+                else:
+                    self.logger.warning("Credential test returned empty token")
+                    return False
+
+            except Exception as e:
+                self.logger.warning(
+                    f"Credential test failed: {e}",
+                    extra={"test_scopes": test_scopes}
+                )
+                return False
+
+    def set_correlation_id(self, correlation_id: str):
+        """Set correlation ID for tracking identity operations.
+        
+        Args:
+            correlation_id: Unique identifier for transaction tracking
+        """
+        self.logger.set_correlation_id(correlation_id)
+
+    def get_correlation_id(self) -> Optional[str]:
+        """Get the current correlation ID.
+        
+        Returns:
+            Current correlation ID if set, otherwise None
+        """
+        return self.logger.get_correlation_id()
+
+
+def create_azure_identity(
+    service_name: str = "azure_identity",
+    service_version: str = "1.0.0",
+    enable_token_cache: bool = True,
+    allow_unencrypted_storage: bool = True,
+    custom_credential_options: Optional[Dict[str, Any]] = None,
+    logger: Optional[AzureLogger] = None,
+    connection_string: Optional[str] = None,
+) -> AzureIdentity:
+    """Create a configured AzureIdentity instance.
+
+    Factory function providing convenient AzureIdentity instantiation with
+    commonly used settings.
+
+    Args:
+        service_name: Service name for tracing context
+        service_version: Service version for metadata
+        enable_token_cache: Enable in-memory token persistence
+        allow_unencrypted_storage: Allow unencrypted token storage
+        custom_credential_options: Additional DefaultAzureCredential options
+        logger: Optional AzureLogger instance
+        connection_string: Application Insights connection string
+
+    Returns:
+        Configured AzureIdentity instance
+    """
+    return AzureIdentity(
+        service_name=service_name,
+        service_version=service_version,
+        enable_token_cache=enable_token_cache,
+        allow_unencrypted_storage=allow_unencrypted_storage,
+        custom_credential_options=custom_credential_options,
+        logger=logger,
+        connection_string=connection_string,
+    )

azpaddypy/mgmt/logging.py

@@ -1,15 +1,11 @@
 import logging
 import os
-import json
 import functools
 import time
 import asyncio
 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 import baggage
@@ -17,14 +13,18 @@ from opentelemetry.context import Context
 
 
 class AzureLogger:
-    """
-    A comprehensive logging class for Azure applications.
+    """Azure-integrated logger with OpenTelemetry distributed tracing.
 
-    This logger integrates with Azure Monitor OpenTelemetry for distributed
-    tracing and structured logging, providing advanced capabilities for
+    Provides comprehensive logging with Azure Monitor integration, correlation
+    tracking, baggage propagation, and automated function tracing for Azure
+    applications with seamless local development support.
 
-    It supports correlation tracking, baggage propagation, and automated
-    tracing for functions and dependencies.
+    Attributes:
+        service_name: Service identifier for telemetry
+        service_version: Service version for context
+        connection_string: Application Insights connection string
+        logger: Python logger instance
+        tracer: OpenTelemetry tracer for spans
     """
 
     def __init__(
@@ -35,17 +35,18 @@ class AzureLogger:
         log_level: int = logging.INFO,
         enable_console_logging: bool = True,
         custom_resource_attributes: Optional[Dict[str, str]] = None,
+        instrumentation_options: Optional[Dict[str, Any]] = None,
     ):
-        """
-        Initialize the Azure Logger with OpenTelemetry tracing
+        """Initialize Azure Logger with OpenTelemetry tracing.
 
         Args:
-            service_name: Name of your service/application
-            service_version: Version of your service
+            service_name: Service identifier for telemetry
+            service_version: Service version for metadata
             connection_string: Application Insights connection string
-            log_level: Logging level (default: INFO)
+            log_level: Python logging level (default: INFO)
             enable_console_logging: Enable console output for local development
-            custom_resource_attributes: Additional resource attributes
+            custom_resource_attributes: Additional OpenTelemetry resource attributes
+            instrumentation_options: Azure Monitor instrumentation options
         """
         self.service_name = service_name
         self.service_version = service_version
@@ -53,7 +54,7 @@ class AzureLogger:
             "APPLICATIONINSIGHTS_CONNECTION_STRING"
         )
 
-        # Prepare resource attributes
+        # Configure resource attributes
         resource_attributes = {
             "service.name": service_name,
             "service.version": service_version,
@@ -63,13 +64,14 @@ class AzureLogger:
         if custom_resource_attributes:
             resource_attributes.update(custom_resource_attributes)
 
-        # Configure Azure Monitor if connection string is available
+        # Configure Azure Monitor if connection string available
         if self.connection_string:
             try:
                 configure_azure_monitor(
                     connection_string=self.connection_string,
                     resource_attributes=resource_attributes,
                     enable_live_metrics=True,
+                    instrumentation_options=instrumentation_options,
                 )
                 self._telemetry_enabled = True
             except Exception as e:
@@ -81,21 +83,16 @@ class AzureLogger:
                 "Warning: No Application Insights connection string found. Telemetry disabled."
             )
 
-        # Set up logger without instrumentor
+        # Configure Python logger
         self.logger = logging.getLogger(service_name)
         self.logger.setLevel(log_level)
-
-        # Clear existing handlers to avoid duplicates
         self.logger.handlers.clear()
 
-        # Add console handler for local development
         if enable_console_logging:
             self._setup_console_handler()
 
-        # Get tracer for manual span creation
+        # Initialize OpenTelemetry tracer and correlation context
         self.tracer = trace.get_tracer(__name__)
-
-        # Initialize correlation context
         self._correlation_id = None
 
         self.info(
@@ -103,12 +100,7 @@ class AzureLogger:
         )
 
     def _setup_console_handler(self):
-        """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.
-        """
+        """Configure console handler for local development."""
         console_handler = logging.StreamHandler()
         formatter = logging.Formatter(
             "%(asctime)s - %(name)s - %(levelname)s - %(message)s - %(pathname)s:%(lineno)d"
@@ -117,70 +109,61 @@ class AzureLogger:
         self.logger.addHandler(console_handler)
 
     def set_correlation_id(self, correlation_id: str):
-        """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.
+        """Set correlation ID for request/transaction tracking.
 
         Args:
-            correlation_id: The unique identifier for the transaction.
+            correlation_id: Unique identifier for transaction correlation
         """
         self._correlation_id = correlation_id
 
     def get_correlation_id(self) -> Optional[str]:
-        """Retrieves the current correlation ID.
+        """Get current correlation ID.
 
         Returns:
-            The current correlation ID if it has been set, otherwise None.
+            Current correlation ID if set, otherwise None
         """
         return self._correlation_id
 
     def set_baggage(self, key: str, value: str) -> Context:
-        """
-        Set a baggage item in the current context
+        """Set baggage item in OpenTelemetry context.
 
         Args:
             key: Baggage key
             value: Baggage value
 
         Returns:
-            Updated context with the new baggage item
+            Updated context with baggage item
         """
         return baggage.set_baggage(key, value)
 
     def get_baggage(self, key: str) -> Optional[str]:
-        """
-        Retrieves a baggage item from the current OpenTelemetry context.
+        """Get baggage item from current context.
 
         Args:
-            key: The baggage key.
+            key: Baggage key
 
         Returns:
-            The baggage value if it exists, otherwise None.
+            Baggage value if exists, otherwise None
         """
         return baggage.get_baggage(key)
 
     def get_all_baggage(self) -> Dict[str, str]:
-        """
-        Retrieves all baggage items from the current OpenTelemetry context.
+        """Get all baggage items from current context.
 
         Returns:
-            A dictionary containing all baggage items.
+            Dictionary of all baggage items
         """
         return dict(baggage.get_all())
 
     def _enhance_extra(self, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """
-        Enriches log records with contextual information.
-
-        This method adds service details, correlation IDs, trace context,
-        and baggage items to the log's `extra` dictionary.
+        """Enrich log records with contextual information.
 
         Args:
-            extra: An optional dictionary of custom data to include.
+            extra: Optional custom data dictionary
 
         Returns:
-            The enhanced dictionary with added contextual data.
+            Enhanced dictionary with service context, correlation ID, trace
+            context, and baggage items
         """
         enhanced_extra = {
             "service_name": self.service_name,
@@ -209,15 +192,15 @@ class AzureLogger:
         return enhanced_extra
 
     def debug(self, message: str, extra: Optional[Dict[str, Any]] = None):
-        """Logs a debug message with enhanced context."""
+        """Log 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):
-        """Logs an info message with enhanced context."""
+        """Log 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):
-        """Logs a warning message with enhanced context."""
+        """Log warning message with enhanced context."""
         self.logger.warning(message, extra=self._enhance_extra(extra))
 
     def error(
@@ -226,11 +209,11 @@ class AzureLogger:
         extra: Optional[Dict[str, Any]] = None,
         exc_info: bool = True,
     ):
-        """Logs an error message with enhanced context and exception info."""
+        """Log 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):
-        """Logs a critical message with enhanced context."""
+        """Log critical message with enhanced context."""
         self.logger.critical(message, extra=self._enhance_extra(extra))
 
     def log_function_execution(
@@ -240,17 +223,13 @@ class AzureLogger:
         success: bool = True,
         extra: Optional[Dict[str, Any]] = None,
     ):
-        """
-        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.
+        """Log function execution metrics for performance monitoring.
 
         Args:
-            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.
+            function_name: Name of executed function
+            duration_ms: Execution duration in milliseconds
+            success: Whether function executed successfully
+            extra: Additional custom properties
         """
         log_data = {
             "function_name": function_name,
@@ -262,7 +241,6 @@ class AzureLogger:
         if extra:
             log_data.update(extra)
 
-        log_level = logging.INFO if success else logging.ERROR
         message = f"Function '{function_name}' executed in {duration_ms:.2f}ms - {'SUCCESS' if success else 'FAILED'}"
 
         if success:
@@ -278,13 +256,12 @@ class AzureLogger:
         duration_ms: float,
         extra: Optional[Dict[str, Any]] = None,
     ):
-        """
-        Log HTTP request with comprehensive details
+        """Log HTTP request with comprehensive details.
 
         Args:
-            method: HTTP method
+            method: HTTP method (GET, POST, etc.)
             url: Request URL
-            status_code: HTTP status code
+            status_code: HTTP response status code
             duration_ms: Request duration in milliseconds
             extra: Additional custom properties
         """
@@ -299,7 +276,7 @@ class AzureLogger:
         if extra:
             log_data.update(extra)
 
-        # Determine log level based on status code
+        # Determine log level and status based on status code
         if status_code < 400:
             log_level = logging.INFO
             status_text = "SUCCESS"
@@ -320,19 +297,18 @@ class AzureLogger:
         span_name: str,
         attributes: Optional[Dict[str, Union[str, int, float, bool]]] = None,
     ) -> Span:
-        """
-        Create a new span for distributed tracing
+        """Create OpenTelemetry span for distributed tracing.
 
         Args:
-            span_name: Name of the span
-            attributes: Initial attributes for the span
+            span_name: Name for the span
+            attributes: Initial span attributes
 
         Returns:
             OpenTelemetry span context manager
         """
         span = self.tracer.start_span(span_name)
 
-        # Add default attributes
+        # Add default service attributes
         span.set_attribute("service.name", self.service_name)
         span.set_attribute("service.version", self.service_version)
 
@@ -354,21 +330,65 @@ class AzureLogger:
         log_args: bool,
         args: tuple,
         kwargs: dict,
+        log_result: bool,
+        log_execution: bool,
     ):
-        """Helper to set up span attributes for function tracing."""
+        """Configure 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)
 
+        # Add decorator parameters as span attributes
+        span.set_attribute("function.decorator.log_args", log_args)
+        span.set_attribute("function.decorator.log_result", log_result)
+        span.set_attribute("function.decorator.log_execution", log_execution)
+
         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))
+                # Add positional arguments as span attributes
+                import inspect
+                try:
+                    sig = inspect.signature(func)
+                    param_names = list(sig.parameters.keys())
+                    for i, arg_value in enumerate(args):
+                        param_name = param_names[i] if i < len(param_names) else f"arg_{i}"
+                        try:
+                            # Convert to string for safe serialization
+                            attr_value = str(arg_value)
+                            # Truncate if too long to avoid excessive data
+                            if len(attr_value) > 1000:
+                                attr_value = attr_value[:1000] + "..."
+                            span.set_attribute(f"function.arg.{param_name}", attr_value)
+                        except Exception:
+                            span.set_attribute(f"function.arg.{param_name}", "<non-serializable>")
+                except Exception:
+                    # Fallback if signature inspection fails
+                    for i, arg_value in enumerate(args):
+                        try:
+                            attr_value = str(arg_value)
+                            if len(attr_value) > 1000:
+                                attr_value = attr_value[:1000] + "..."
+                            span.set_attribute(f"function.arg.{i}", attr_value)
+                        except Exception:
+                            span.set_attribute(f"function.arg.{i}", "<non-serializable>")
+                            
             if kwargs:
                 span.set_attribute("function.kwargs_count", len(kwargs))
+                # Add keyword arguments as span attributes
+                for key, value in kwargs.items():
+                    try:
+                        attr_value = str(value)
+                        # Truncate if too long to avoid excessive data
+                        if len(attr_value) > 1000:
+                            attr_value = attr_value[:1000] + "..."
+                        span.set_attribute(f"function.kwarg.{key}", attr_value)
+                    except Exception:
+                        span.set_attribute(f"function.kwarg.{key}", "<non-serializable>")
 
     def _handle_function_success(
         self,
@@ -382,7 +402,7 @@ class AzureLogger:
         args: tuple,
         kwargs: dict,
     ):
-        """Helper to handle successful function execution tracing."""
+        """Handle successful function execution in tracing."""
         span.set_attribute("function.duration_ms", duration_ms)
         span.set_attribute("function.success", True)
         span.set_status(Status(StatusCode.OK))
@@ -415,7 +435,7 @@ class AzureLogger:
         log_execution: bool,
         is_async: bool,
     ):
-        """Helper to handle failed function execution tracing."""
+        """Handle failed function execution in tracing."""
         span.set_status(Status(StatusCode.ERROR, str(e)))
         span.record_exception(e)
         span.set_attribute("function.duration_ms", duration_ms)
@@ -441,19 +461,20 @@ class AzureLogger:
     def trace_function(
         self,
         function_name: Optional[str] = None,
-        log_args: bool = False,
-        log_result: bool = False,
         log_execution: bool = True,
+        log_args: bool = True,
+        log_result: bool = False
     ) -> Callable:
-        """
-        Decorator to automatically trace function execution with comprehensive logging.
-        Supports both synchronous and asynchronous functions.
+        """Decorator for automatic function execution tracing.
+
+        Supports both synchronous and asynchronous functions with comprehensive
+        logging and OpenTelemetry span creation.
 
         Args:
-            function_name: Custom name for the span (defaults to function name)
+            function_name: Custom span name (defaults to function name)
+            log_execution: Whether to log execution metrics
             log_args: Whether to log function arguments
             log_result: Whether to log function result
-            log_execution: Whether to log execution metrics
         """
 
         def decorator(func):
@@ -462,7 +483,7 @@ class AzureLogger:
                 span_name = function_name or f"{func.__module__}.{func.__name__}"
                 with self.tracer.start_as_current_span(span_name) as span:
                     self._setup_span_for_function_trace(
-                        span, func, True, log_args, args, kwargs
+                        span, func, True, log_args, args, kwargs, log_result, log_execution
                     )
                     start_time = time.time()
                     try:
@@ -495,7 +516,7 @@ class AzureLogger:
                 span_name = function_name or f"{func.__module__}.{func.__name__}"
                 with self.tracer.start_as_current_span(span_name) as span:
                     self._setup_span_for_function_trace(
-                        span, func, False, log_args, args, kwargs
+                        span, func, False, log_args, args, kwargs, log_result, log_execution
                     )
                     start_time = time.time()
                     try:
@@ -521,7 +542,7 @@ class AzureLogger:
                         )
                         raise
 
-            # Return the appropriate wrapper based on whether the function is async
+            # Return appropriate wrapper based on function type
             if asyncio.iscoroutinefunction(func):
                 return async_wrapper
             return sync_wrapper
@@ -529,14 +550,14 @@ class AzureLogger:
         return decorator
 
     def add_span_attributes(self, attributes: Dict[str, Union[str, int, float, bool]]):
-        """Add attributes to the current active span"""
+        """Add attributes to current active span."""
         current_span = trace.get_current_span()
         if current_span and current_span.is_recording():
             for key, value in attributes.items():
                 current_span.set_attribute(key, value)
 
     def add_span_event(self, name: str, attributes: Optional[Dict[str, Any]] = None):
-        """Add an event to the current active span"""
+        """Add event to current active span."""
         current_span = trace.get_current_span()
         if current_span and current_span.is_recording():
             event_attributes = attributes or {}
@@ -547,7 +568,7 @@ class AzureLogger:
     def set_span_status(
         self, status_code: StatusCode, description: Optional[str] = None
     ):
-        """Set the status of the current active span"""
+        """Set status of current active span."""
         current_span = trace.get_current_span()
         if current_span and current_span.is_recording():
             current_span.set_status(Status(status_code, description))
@@ -560,15 +581,14 @@ class AzureLogger:
         extra: Optional[Dict[str, Any]] = None,
         span_attributes: Optional[Dict[str, Union[str, int, float, bool]]] = None,
     ):
-        """
-        Log a message within a span context
+        """Log message within a span context.
 
         Args:
-            span_name: Name of the span
+            span_name: Name for the span
             message: Log message
-            level: Log level
+            level: Python logging level
             extra: Additional log properties
-            span_attributes: Attributes to add to the span
+            span_attributes: Attributes to add to span
         """
         with self.tracer.start_as_current_span(span_name) as span:
             if span_attributes:
@@ -586,14 +606,13 @@ class AzureLogger:
         duration_ms: float,
         extra: Optional[Dict[str, Any]] = None,
     ):
-        """
-        Log external dependency calls (Database, HTTP, etc.)
+        """Log external dependency calls for monitoring.
 
         Args:
             dependency_type: Type of dependency (SQL, HTTP, etc.)
-            name: Name/identifier of the dependency
+            name: Dependency identifier
             command: Command/query executed
-            success: Whether the call was successful
+            success: Whether call was successful
             duration_ms: Call duration in milliseconds
             extra: Additional properties
         """
@@ -616,10 +635,9 @@ class AzureLogger:
         self.logger.log(log_level, message, extra=self._enhance_extra(log_data))
 
     def flush(self):
-        """Flush all pending telemetry data"""
+        """Flush pending telemetry data."""
         if self._telemetry_enabled:
             try:
-                # Force flush any pending telemetry
                 from opentelemetry.sdk.trace import TracerProvider
 
                 tracer_provider = trace.get_tracer_provider()
@@ -629,7 +647,7 @@ class AzureLogger:
                 self.warning(f"Failed to flush telemetry: {e}")
 
 
-# Factory functions for easy instantiation
+# Factory functions with logger caching
 _loggers: Dict[Any, "AzureLogger"] = {}
 
 
@@ -640,18 +658,20 @@ def create_app_logger(
     log_level: int = logging.INFO,
     enable_console_logging: bool = True,
     custom_resource_attributes: Optional[Dict[str, str]] = None,
+    instrumentation_options: Optional[Dict[str, Any]] = None,
 ) -> AzureLogger:
-    """
-    Factory function to create an AzureLogger instance. If a logger with the
-    same configuration has already been created, it will be returned.
+    """Create cached AzureLogger instance for applications.
+
+    Returns existing logger if one with same configuration exists.
 
     Args:
-        service_name: Name of your service/application
-        service_version: Version of your service
+        service_name: Service identifier for telemetry
+        service_version: Service version for metadata
         connection_string: Application Insights connection string
-        log_level: Logging level
+        log_level: Python logging level
         enable_console_logging: Enable console output
-        custom_resource_attributes: Additional resource attributes
+        custom_resource_attributes: Additional OpenTelemetry resource attributes
+        instrumentation_options: Azure Monitor instrumentation options
 
     Returns:
         Configured AzureLogger instance
@@ -695,18 +715,19 @@ def create_function_logger(
     function_name: str,
     service_version: str = "1.0.0",
     connection_string: Optional[str] = None,
+    instrumentation_options: Optional[Dict[str, Any]] = None,
 ) -> AzureLogger:
-    """
-    Factory function specifically for Azure Functions
+    """Create AzureLogger optimized for Azure Functions.
 
     Args:
-        function_app_name: Name of the Function App
-        function_name: Name of the specific function
-        service_version: Version of the service
+        function_app_name: Azure Function App name
+        function_name: Specific function name
+        service_version: Service version for metadata
         connection_string: Application Insights connection string
+        instrumentation_options: Azure Monitor instrumentation options
 
     Returns:
-        Configured AzureLogger instance for Azure Functions
+        Configured AzureLogger with Azure Functions context
     """
     custom_attributes = {
         "azure.function.app": function_app_name,
@@ -719,4 +740,5 @@ def create_function_logger(
         service_version=service_version,
         connection_string=connection_string,
         custom_resource_attributes=custom_attributes,
+        instrumentation_options=instrumentation_options,
     )

{azpaddypy-0.2.6.dist-info → azpaddypy-0.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: azpaddypy
-Version: 0.2.6
+Version: 0.2.8
 Summary: Comprehensive Python logger for Azure, integrating OpenTelemetry for advanced, structured, and distributed tracing.
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
@@ -8,11 +8,10 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: azure-monitor-opentelemetry==1.6.10
+Requires-Dist: azure-functions==1.23.0
 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"
+Requires-Dist: azure-functions==1.23.0; extra == "dev"
+Requires-Dist: pytest==8.4.1; extra == "dev"
+Requires-Dist: pytest-asyncio==1.0.0; extra == "dev"
+Requires-Dist: anyio==4.9.0; extra == "dev"
 Dynamic: license-file

azpaddypy-0.2.8.dist-info/RECORD

@@ -0,0 +1,10 @@
+azpaddypy/mgmt/__init__.py,sha256=-jH8Ftx9C8qu4yF5dMVEapVZhNwG7m4QCUjyutesOoY,278
+azpaddypy/mgmt/identity.py,sha256=mA_krQslMsK_sDob-z-QA0B9khK_JUO2way7xwPopR8,12001
+azpaddypy/mgmt/logging.py,sha256=War3h9Td7KZyeOsvOz3t2_ESNQzJ3jeZcrFL5octoGo,28081
+azpaddypy/test_function/__init__.py,sha256=0NjUl36wvUWV79GpRwBFkgkBaC6uDZsTdaSVOIHMFEU,3481
+azpaddypy/test_function/function_app.py,sha256=6nX54-iq0L1l_hZpD6E744-j79oLxdaldFyWDCpwH7c,3867
+azpaddypy-0.2.8.dist-info/licenses/LICENSE,sha256=hQ6t0g2QaewGCQICHqTckBFbMVakGmoyTAzDpmEYV4c,1089
+azpaddypy-0.2.8.dist-info/METADATA,sha256=7zvYg76eo4n_0g_GFCqTwmC0pK4cgyVBrPuK4R52e6c,705
+azpaddypy-0.2.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+azpaddypy-0.2.8.dist-info/top_level.txt,sha256=hsDuboDhT61320ML8X479ezSTwT3rrlDWz1_Z45B2cs,10
+azpaddypy-0.2.8.dist-info/RECORD,,

azpaddypy-0.2.6.dist-info/RECORD

@@ -1,9 +0,0 @@
-azpaddypy/mgmt/__init__.py,sha256=5-0eZuJMZlCONZNJ5hEvWXfvLIM36mg7FsEVs32bY_A,183
-azpaddypy/mgmt/logging.py,sha256=7Ug99lg8gsvCGq0HukR0qWVl-_vacEq-poq2rUj24d4,26060
-azpaddypy/test_function/__init__.py,sha256=0NjUl36wvUWV79GpRwBFkgkBaC6uDZsTdaSVOIHMFEU,3481
-azpaddypy/test_function/function_app.py,sha256=6nX54-iq0L1l_hZpD6E744-j79oLxdaldFyWDCpwH7c,3867
-azpaddypy-0.2.6.dist-info/licenses/LICENSE,sha256=hQ6t0g2QaewGCQICHqTckBFbMVakGmoyTAzDpmEYV4c,1089
-azpaddypy-0.2.6.dist-info/METADATA,sha256=jycbdYSHrsBp0riAHepPVTGZ-oQNMGWzngkhwC0A7vk,747
-azpaddypy-0.2.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-azpaddypy-0.2.6.dist-info/top_level.txt,sha256=hsDuboDhT61320ML8X479ezSTwT3rrlDWz1_Z45B2cs,10
-azpaddypy-0.2.6.dist-info/RECORD,,