azpaddypy 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

azpaddypy/mgmt/logging.py

@@ -3,6 +3,7 @@ import os
 import functools
 import time
 import asyncio
+import uuid
 from typing import Optional, Dict, Any, Union, Callable
 from datetime import datetime
 from azure.monitor.opentelemetry import configure_azure_monitor
@@ -19,12 +20,23 @@ class AzureLogger:
     tracking, baggage propagation, and automated function tracing for Azure
     applications with seamless local development support.
 
+    CLOUD ROLE NAME INTEGRATION:
+    The service_name parameter automatically sets the cloud role name for 
+    Application Insights. When multiple services emit telemetry to the same 
+    Application Insights resource, each service will appear as a separate 
+    node on the Application Map, enabling proper service topology visualization.
+
+    CORRELATION ID AUTOMATION:
+    The trace_function decorator automatically generates UUID4 correlation IDs
+    when none are manually set, ensuring consistent distributed tracing across
+    all function calls without requiring manual configuration.
+
     Supports all standard logging levels (debug, info, warning, error, exception, 
     critical) with enhanced context including trace IDs, correlation IDs, and 
     baggage propagation.
 
     Attributes:
-        service_name: Service identifier for telemetry
+        service_name: Service identifier for telemetry and cloud role name
         service_version: Service version for context
         connection_string: Application Insights connection string
         logger: Python logger instance
@@ -40,17 +52,24 @@ class AzureLogger:
         enable_console_logging: bool = True,
         custom_resource_attributes: Optional[Dict[str, str]] = None,
         instrumentation_options: Optional[Dict[str, Any]] = None,
+        cloud_role_name: Optional[str] = None,
     ):
         """Initialize Azure Logger with OpenTelemetry tracing.
 
+        The service_name parameter automatically sets the cloud role name for 
+        Application Insights Application Map visualization. When multiple services
+        emit telemetry to the same Application Insights resource, each service
+        will appear as a separate node on the Application Map.
+
         Args:
-            service_name: Service identifier for telemetry
+            service_name: Service identifier for telemetry and cloud role name
             service_version: Service version for metadata
             connection_string: Application Insights connection string
             log_level: Python logging level (default: INFO)
             enable_console_logging: Enable console output for local development
             custom_resource_attributes: Additional OpenTelemetry resource attributes
             instrumentation_options: Azure Monitor instrumentation options
+            cloud_role_name: Override cloud role name (defaults to service_name)
         """
         self.service_name = service_name
         self.service_version = service_version
@@ -58,9 +77,14 @@ class AzureLogger:
             "APPLICATIONINSIGHTS_CONNECTION_STRING"
         )
 
+        # Use explicit cloud role name or default to service name
+        effective_cloud_role_name = cloud_role_name or service_name
+        self.cloud_role_name = effective_cloud_role_name
+
         # Configure resource attributes
+        # NOTE: service.name automatically maps to cloud role name in Application Insights
         resource_attributes = {
-            "service.name": service_name,
+            "service.name": effective_cloud_role_name,
             "service.version": service_version,
             "service.instance.id": os.getenv("WEBSITE_INSTANCE_ID", "local"),
         }
@@ -100,7 +124,8 @@ class AzureLogger:
         self._correlation_id = None
 
         self.info(
-            f"Azure Logger initialized for service '{service_name}' v{service_version}"
+            f"Azure Logger initialized for service '{service_name}' v{service_version} "
+            f"(cloud role: '{effective_cloud_role_name}')"
         )
 
     def _setup_console_handler(self):
@@ -115,16 +140,27 @@ class AzureLogger:
     def set_correlation_id(self, correlation_id: str):
         """Set correlation ID for request/transaction tracking.
 
+        Manually sets the correlation ID that will be used for all subsequent
+        tracing operations. This value takes precedence over auto-generated
+        correlation IDs in the trace_function decorator.
+
         Args:
             correlation_id: Unique identifier for transaction correlation
+
+        Note:
+            If not set manually, the trace_function decorator will automatically
+            generate a UUID4 correlation_id on first use.
         """
         self._correlation_id = correlation_id
 
     def get_correlation_id(self) -> Optional[str]:
         """Get current correlation ID.
 
+        Returns the currently active correlation ID, whether manually set
+        or automatically generated by the trace_function decorator.
+
         Returns:
-            Current correlation ID if set, otherwise None
+            Current correlation ID if set (manual or auto-generated), otherwise None
         """
         return self._correlation_id
 
@@ -167,8 +203,16 @@ class AzureLogger:
 
         Returns:
             Enhanced dictionary with service context, correlation ID, trace
-            context, and baggage items
+            context, and baggage items, with built-in LogRecord attributes filtered out
         """
+        # Define built-in LogRecord attributes that should not be overwritten
+        reserved_attributes = {
+            'name', 'msg', 'args', 'levelname', 'levelno', 'pathname', 'filename',
+            'module', 'exc_info', 'exc_text', 'stack_info', 'lineno', 'funcName',
+            'created', 'msecs', 'relativeCreated', 'thread', 'threadName',
+            'processName', 'process', 'getMessage'
+        }
+        
         enhanced_extra = {
             "service_name": self.service_name,
             "service_version": self.service_version,
@@ -185,13 +229,34 @@ class AzureLogger:
             enhanced_extra["trace_id"] = format(span_context.trace_id, "032x")
             enhanced_extra["span_id"] = format(span_context.span_id, "016x")
 
-        # Add baggage items
+        # Add baggage items, filtering out any reserved attribute names
         baggage_items = self.get_all_baggage()
         if baggage_items:
-            enhanced_extra["baggage"] = baggage_items
+            # Filter baggage items to avoid conflicts with LogRecord attributes
+            filtered_baggage = {k: v for k, v in baggage_items.items() if k not in reserved_attributes}
+            if filtered_baggage:
+                enhanced_extra["baggage"] = filtered_baggage
+            
+            # Log warning if any baggage keys were filtered out
+            filtered_baggage_keys = set(baggage_items.keys()) - set(filtered_baggage.keys())
+            if filtered_baggage_keys:
+                # Use the base logger directly to avoid infinite recursion
+                self.logger.warning(
+                    f"Filtered out reserved LogRecord attributes from baggage: {filtered_baggage_keys}"
+                )
 
         if isinstance(extra, dict):
-            enhanced_extra.update(extra)
+            # Filter out any keys that would conflict with built-in LogRecord attributes
+            filtered_extra = {k: v for k, v in extra.items() if k not in reserved_attributes}
+            enhanced_extra.update(filtered_extra)
+            
+            # Log warning if any keys were filtered out
+            filtered_keys = set(extra.keys()) - set(filtered_extra.keys())
+            if filtered_keys:
+                # Use the base logger directly to avoid infinite recursion
+                self.logger.warning(
+                    f"Filtered out reserved LogRecord attributes from extra data: {filtered_keys}"
+                )
 
         return enhanced_extra
 
@@ -481,16 +546,38 @@ class AzureLogger:
         log_args: bool = True,
         log_result: bool = False
     ) -> Callable:
-        """Decorator for automatic function execution tracing.
+        """Decorator for automatic function execution tracing with correlation ID support.
 
         Supports both synchronous and asynchronous functions with comprehensive
-        logging and OpenTelemetry span creation.
+        logging and OpenTelemetry span creation. Automatically generates and manages
+        correlation IDs for distributed tracing.
+
+        CORRELATION ID AUTOMATION:
+        - If no correlation_id is set, automatically generates a UUID4 correlation_id
+        - If correlation_id is manually set, preserves the existing value
+        - Correlation_id is automatically added to all spans and log entries
+        - Ensures consistent tracing across function calls
 
         Args:
             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
+
+        Returns:
+            Decorated function with automatic tracing and correlation ID support
+
+        Example:
+            # Automatic correlation_id generation
+            @logger.trace_function()
+            def my_function():
+                return "result"
+
+            # Manual correlation_id (preserved)
+            logger.set_correlation_id("manual-id")
+            @logger.trace_function()
+            def my_function():
+                return "result"
         """
 
         def decorator(func):
@@ -498,6 +585,11 @@ class AzureLogger:
             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:
+                    # Auto-generate correlation_id if not set - ensures consistent tracing
+                    # Manual correlation_ids take precedence over auto-generated ones
+                    if not self._correlation_id:
+                        self._correlation_id = str(uuid.uuid4())
+                    
                     self._setup_span_for_function_trace(
                         span, func, True, log_args, args, kwargs, log_result, log_execution
                     )
@@ -531,6 +623,11 @@ class AzureLogger:
             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:
+                    # Auto-generate correlation_id if not set - ensures consistent tracing
+                    # Manual correlation_ids take precedence over auto-generated ones
+                    if not self._correlation_id:
+                        self._correlation_id = str(uuid.uuid4())
+                    
                     self._setup_span_for_function_trace(
                         span, func, False, log_args, args, kwargs, log_result, log_execution
                     )
@@ -675,19 +772,23 @@ def create_app_logger(
     enable_console_logging: bool = True,
     custom_resource_attributes: Optional[Dict[str, str]] = None,
     instrumentation_options: Optional[Dict[str, Any]] = None,
+    cloud_role_name: Optional[str] = None,
 ) -> AzureLogger:
     """Create cached AzureLogger instance for applications.
 
     Returns existing logger if one with same configuration exists.
+    The service_name automatically becomes the cloud role name in Application Insights
+    unless explicitly overridden with cloud_role_name parameter.
 
     Args:
-        service_name: Service identifier for telemetry
+        service_name: Service identifier for telemetry and cloud role name
         service_version: Service version for metadata
         connection_string: Application Insights connection string
         log_level: Python logging level
         enable_console_logging: Enable console output
         custom_resource_attributes: Additional OpenTelemetry resource attributes
         instrumentation_options: Azure Monitor instrumentation options
+        cloud_role_name: Override cloud role name (defaults to service_name)
 
     Returns:
         Configured AzureLogger instance
@@ -709,6 +810,7 @@ def create_app_logger(
         log_level,
         enable_console_logging,
         attr_items,
+        cloud_role_name,
     )
 
     if params_key in _loggers:
@@ -721,6 +823,8 @@ def create_app_logger(
         log_level=log_level,
         enable_console_logging=enable_console_logging,
         custom_resource_attributes=custom_resource_attributes,
+        instrumentation_options=instrumentation_options,
+        cloud_role_name=cloud_role_name,
     )
     _loggers[params_key] = logger
     return logger
@@ -732,15 +836,21 @@ def create_function_logger(
     service_version: str = "1.0.0",
     connection_string: Optional[str] = None,
     instrumentation_options: Optional[Dict[str, Any]] = None,
+    cloud_role_name: Optional[str] = None,
 ) -> AzureLogger:
     """Create AzureLogger optimized for Azure Functions.
 
+    Automatically creates cloud role name in the format '{function_app_name}.{function_name}'
+    unless explicitly overridden. This ensures each function appears as a separate
+    component in the Application Insights Application Map.
+
     Args:
         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
+        cloud_role_name: Override cloud role name (defaults to '{function_app_name}.{function_name}')
 
     Returns:
         Configured AzureLogger with Azure Functions context
@@ -751,10 +861,13 @@ def create_function_logger(
         "azure.resource.type": "function",
     }
 
+    default_service_name = f"{function_app_name}.{function_name}"
+
     return create_app_logger(
-        service_name=f"{function_app_name}.{function_name}",
+        service_name=default_service_name,
         service_version=service_version,
         connection_string=connection_string,
         custom_resource_attributes=custom_attributes,
         instrumentation_options=instrumentation_options,
+        cloud_role_name=cloud_role_name,
     )

{azpaddypy-0.3.2.dist-info → azpaddypy-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: azpaddypy
-Version: 0.3.2
+Version: 0.3.4
 Summary: Comprehensive Python logger for Azure, integrating OpenTelemetry for advanced, structured, and distributed tracing.
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent

{azpaddypy-0.3.2.dist-info → azpaddypy-0.3.4.dist-info}/RECORD

@@ -1,10 +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=5sAqUWwjX6nZMgqK8BurMoWhId4JJ21RZ9H29gXWqA4,28835
+azpaddypy/mgmt/logging.py,sha256=pivPsHeySF1Dyx6HKCSos7HBOYyJMVeRP25wYZu3Sno,35117
 azpaddypy/test_function/__init__.py,sha256=0NjUl36wvUWV79GpRwBFkgkBaC6uDZsTdaSVOIHMFEU,3481
 azpaddypy/test_function/function_app.py,sha256=6nX54-iq0L1l_hZpD6E744-j79oLxdaldFyWDCpwH7c,3867
-azpaddypy-0.3.2.dist-info/licenses/LICENSE,sha256=hQ6t0g2QaewGCQICHqTckBFbMVakGmoyTAzDpmEYV4c,1089
-azpaddypy-0.3.2.dist-info/METADATA,sha256=rR7GtG1mvgOR0WWYGkGt-2ZTtdwcye-GO8ea2QXNhos,705
-azpaddypy-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-azpaddypy-0.3.2.dist-info/top_level.txt,sha256=hsDuboDhT61320ML8X479ezSTwT3rrlDWz1_Z45B2cs,10
-azpaddypy-0.3.2.dist-info/RECORD,,
+azpaddypy-0.3.4.dist-info/licenses/LICENSE,sha256=hQ6t0g2QaewGCQICHqTckBFbMVakGmoyTAzDpmEYV4c,1089
+azpaddypy-0.3.4.dist-info/METADATA,sha256=QDqVtpO7pbf_VGJM4e3W6QHV0VtOB3gc6kH8pAoe7jQ,705
+azpaddypy-0.3.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+azpaddypy-0.3.4.dist-info/top_level.txt,sha256=hsDuboDhT61320ML8X479ezSTwT3rrlDWz1_Z45B2cs,10
+azpaddypy-0.3.4.dist-info/RECORD,,