praisonaiagents 0.0.152__py3-none-any.whl → 0.0.154__py3-none-any.whl

praisonaiagents/telemetry/performance_monitor.py

@@ -13,6 +13,7 @@ Features:
 - Easy integration with existing agents and workflows
 """
 
+import os
 import time
 import json
 import threading
@@ -32,6 +33,7 @@ except ImportError:
 logger = logging.getLogger(__name__)
 
 
+
 class PerformanceMonitor:
     """
     User-friendly performance monitoring for functions, API calls, and workflows.
@@ -50,6 +52,20 @@ class PerformanceMonitor:
         Args:
             max_entries: Maximum number of performance entries to keep in memory
         """
+        # Check if performance monitoring is disabled
+        from .telemetry import _is_monitoring_disabled
+        self._monitoring_disabled = _is_monitoring_disabled()
+        
+        # If monitoring is disabled, use minimal initialization
+        if self._monitoring_disabled:
+            self.max_entries = 0
+            self._lock = None
+            self._function_stats = {}
+            self._api_calls = {}
+            self._function_flow = []
+            self._active_calls = {}
+            self._telemetry = None
+            return
         self.max_entries = max_entries
         self._lock = threading.RLock()
         
@@ -97,6 +113,12 @@ class PerformanceMonitor:
             def my_function():
                 return "result"
         """
+        # If monitoring is disabled, return unmodified function
+        if self._monitoring_disabled:
+            def decorator(func: Callable) -> Callable:
+                return func
+            return decorator
+        
         def decorator(func: Callable) -> Callable:
             name = func_name or f"{func.__module__}.{func.__qualname__}"
             
@@ -170,6 +192,10 @@ class PerformanceMonitor:
             with performance_monitor.track_api_call("openai", "/v1/chat/completions"):
                 response = openai_client.chat.completions.create(...)
         """
+        # If monitoring is disabled, provide no-op context manager
+        if self._monitoring_disabled:
+            yield
+            return
         call_name = f"{api_name}:{endpoint}" if endpoint else api_name
         start_time = time.time()
         
@@ -189,6 +215,9 @@ class PerformanceMonitor:
     def _record_function_performance(self, func_name: str, execution_time: float, 
                                    success: bool, error: Optional[str] = None):
         """Record function performance statistics."""
+        if self._monitoring_disabled:
+            return
+            
         with self._lock:
             stats = self._function_stats[func_name]
             stats['call_count'] += 1
@@ -212,6 +241,9 @@ class PerformanceMonitor:
     def _record_api_call(self, api_name: str, execution_time: float,
                         success: bool, error: Optional[str] = None):
         """Record API call performance statistics."""
+        if self._monitoring_disabled:
+            return
+            
         with self._lock:
             stats = self._api_calls[api_name]
             stats['call_count'] += 1
@@ -241,6 +273,10 @@ class PerformanceMonitor:
         Returns:
             Dictionary with performance statistics
         """
+        # If monitoring is disabled, return empty results
+        if self._monitoring_disabled:
+            return {}
+            
         with self._lock:
             if func_name:
                 if func_name not in self._function_stats:
@@ -287,6 +323,10 @@ class PerformanceMonitor:
         Returns:
             Dictionary with API call performance statistics
         """
+        # If monitoring is disabled, return empty results
+        if self._monitoring_disabled:
+            return {}
+            
         with self._lock:
             if api_name:
                 if api_name not in self._api_calls:
@@ -515,6 +555,9 @@ class PerformanceMonitor:
         Returns:
             Performance data in requested format
         """
+        if self._monitoring_disabled:
+            return {} if format == "dict" else "{}"
+            
         data = {
             'functions': self.get_function_performance(),
             'api_calls': self.get_api_call_performance(),
@@ -526,6 +569,119 @@ class PerformanceMonitor:
         if format == "json":
             return json.dumps(data, indent=2)
         return data
+    
+    def export_metrics_for_external_apm(self, service_name: str = "praisonai-agents") -> Dict[str, Any]:
+        """
+        Export lightweight metrics suitable for external APM tools like DataDog or New Relic.
+        
+        This method provides a minimal overhead way to export key performance metrics
+        without the expensive flow analysis operations.
+        
+        Args:
+            service_name: Name of the service for APM tagging
+            
+        Returns:
+            Dictionary with lightweight metrics suitable for external monitoring
+        """
+        if self._monitoring_disabled:
+            return {}
+            
+        timestamp = datetime.now().isoformat()
+        metrics = []
+        
+        # Function performance metrics (lightweight)
+        for func_name, stats in self._function_stats.items():
+            if stats['call_count'] > 0:
+                avg_duration = stats['total_time'] / stats['call_count']
+                error_rate = stats['error_count'] / stats['call_count']
+                
+                # Create metrics in a format suitable for external APM
+                metrics.append({
+                    'metric_name': 'function.execution.duration',
+                    'metric_type': 'gauge',
+                    'value': avg_duration,
+                    'timestamp': timestamp,
+                    'tags': {
+                        'service': service_name,
+                        'function_name': func_name,
+                        'unit': 'seconds'
+                    }
+                })
+                
+                metrics.append({
+                    'metric_name': 'function.execution.count', 
+                    'metric_type': 'counter',
+                    'value': stats['call_count'],
+                    'timestamp': timestamp,
+                    'tags': {
+                        'service': service_name,
+                        'function_name': func_name
+                    }
+                })
+                
+                metrics.append({
+                    'metric_name': 'function.error.rate',
+                    'metric_type': 'gauge', 
+                    'value': error_rate,
+                    'timestamp': timestamp,
+                    'tags': {
+                        'service': service_name,
+                        'function_name': func_name,
+                        'unit': 'ratio'
+                    }
+                })
+        
+        # API call metrics (lightweight)
+        for api_name, stats in self._api_calls.items():
+            if stats['call_count'] > 0:
+                avg_duration = stats['total_time'] / stats['call_count'] 
+                success_rate = stats['success_count'] / stats['call_count']
+                
+                metrics.append({
+                    'metric_name': 'api.call.duration',
+                    'metric_type': 'gauge',
+                    'value': avg_duration,
+                    'timestamp': timestamp,
+                    'tags': {
+                        'service': service_name,
+                        'api_name': api_name,
+                        'unit': 'seconds'
+                    }
+                })
+                
+                metrics.append({
+                    'metric_name': 'api.call.count',
+                    'metric_type': 'counter',
+                    'value': stats['call_count'], 
+                    'timestamp': timestamp,
+                    'tags': {
+                        'service': service_name,
+                        'api_name': api_name
+                    }
+                })
+                
+                metrics.append({
+                    'metric_name': 'api.success.rate',
+                    'metric_type': 'gauge',
+                    'value': success_rate,
+                    'timestamp': timestamp, 
+                    'tags': {
+                        'service': service_name,
+                        'api_name': api_name,
+                        'unit': 'ratio'
+                    }
+                })
+        
+        return {
+            'service_name': service_name,
+            'timestamp': timestamp,
+            'metrics': metrics,
+            'metadata': {
+                'total_functions_monitored': len(self._function_stats),
+                'total_apis_monitored': len(self._api_calls),
+                'monitoring_enabled': not self._monitoring_disabled
+            }
+        }
 
 
 # Global performance monitor instance
@@ -570,4 +726,9 @@ def get_slowest_apis(limit: int = 10) -> List[Dict[str, Any]]:
 
 def clear_performance_data():
     """Clear all performance monitoring data."""
-    performance_monitor.clear_statistics()
+    performance_monitor.clear_statistics()
+
+
+def export_external_apm_metrics(service_name: str = "praisonai-agents") -> Dict[str, Any]:
+    """Export lightweight metrics for external APM tools."""
+    return performance_monitor.export_metrics_for_external_apm(service_name)

praisonaiagents/telemetry/performance_utils.py

@@ -5,13 +5,14 @@ This module provides advanced analysis tools for function flow visualization,
 performance bottleneck identification, and comprehensive reporting.
 
 Features:
-- Function flow analysis and visualization
+- Function flow analysis and visualization (opt-in via PRAISONAI_FLOW_ANALYSIS_ENABLED)
 - Performance bottleneck detection
 - Execution path mapping
 - Performance trend analysis
 - Advanced reporting utilities
 """
 
+import os
 import json
 from collections import defaultdict
 from typing import Dict, Any, List, Optional
@@ -27,6 +28,9 @@ except ImportError:
 
 logger = logging.getLogger(__name__)
 
+# Check if expensive flow analysis should be enabled (opt-in only)
+_FLOW_ANALYSIS_ENABLED = os.environ.get('PRAISONAI_FLOW_ANALYSIS_ENABLED', '').lower() in ('true', '1', 'yes')
+
 # Performance analysis thresholds
 BOTTLENECK_THRESHOLD_AVERAGE = 1.0  # seconds - average duration to consider bottleneck
 BOTTLENECK_THRESHOLD_MAX = 5.0      # seconds - max duration to consider bottleneck
@@ -45,17 +49,28 @@ class FunctionFlowAnalyzer:
     
     def __init__(self):
         self.logger = logging.getLogger(__name__)
+        
+        # Check if performance monitoring is disabled
+        from .telemetry import _is_monitoring_disabled
+        self._analysis_disabled = _is_monitoring_disabled()
     
     def analyze_execution_flow(self, flow_data: Optional[List[Dict]] = None) -> Dict[str, Any]:
         """
         Analyze function execution flow to identify patterns and bottlenecks.
         
+        Note: Expensive flow analysis operations are opt-in only via PRAISONAI_FLOW_ANALYSIS_ENABLED
+        environment variable to avoid performance overhead.
+        
         Args:
             flow_data: Optional flow data, or None to use current monitor data
             
         Returns:
             Analysis results with flow patterns, bottlenecks, and statistics
         """
+        # Early exit if analysis is disabled
+        if self._analysis_disabled:
+            return {"message": "Flow analysis disabled via environment variables"}
+        
         if flow_data is None:
             if not PERFORMANCE_MONITOR_AVAILABLE:
                 return {"error": "Performance monitor not available and no flow data provided"}
@@ -66,17 +81,24 @@ class FunctionFlowAnalyzer:
         
         analysis = {
             "total_events": len(flow_data),
-            "execution_patterns": self._analyze_patterns(flow_data),
-            "bottlenecks": self._identify_bottlenecks(flow_data),
-            "parallelism": self._analyze_parallelism(flow_data),
-            "call_chains": self._build_call_chains(flow_data),
             "statistics": self._calculate_flow_statistics(flow_data)
         }
         
+        # Only include expensive analysis if explicitly enabled
+        if _FLOW_ANALYSIS_ENABLED:
+            analysis.update({
+                "execution_patterns": self._analyze_patterns(flow_data),
+                "bottlenecks": self._identify_bottlenecks(flow_data),
+                "parallelism": self._analyze_parallelism(flow_data),
+                "call_chains": self._build_call_chains(flow_data),
+            })
+        else:
+            analysis["note"] = "Advanced flow analysis disabled. Set PRAISONAI_FLOW_ANALYSIS_ENABLED=true to enable expensive pattern detection."
+        
         return analysis
     
     def _analyze_patterns(self, flow_data: List[Dict]) -> Dict[str, Any]:
-        """Analyze execution patterns in the flow data."""
+        """Analyze execution patterns in the flow data (optimized to avoid O(n²) complexity)."""
         patterns = {
             "most_frequent_sequences": [],
             "recursive_calls": [],
@@ -84,6 +106,12 @@ class FunctionFlowAnalyzer:
             "error_patterns": []
         }
         
+        # Limit analysis to reasonable data size to prevent performance issues
+        MAX_EVENTS_TO_ANALYZE = 1000
+        if len(flow_data) > MAX_EVENTS_TO_ANALYZE:
+            # Sample the most recent events instead of analyzing all (create copy to avoid modifying input)
+            flow_data = flow_data[-MAX_EVENTS_TO_ANALYZE:].copy()
+        
         # Group events by function to find sequences
         function_sequences = defaultdict(list)
         
@@ -91,7 +119,7 @@ class FunctionFlowAnalyzer:
             func_name = event.get('function', 'unknown')
             function_sequences[func_name].append(event)
         
-        # Find most frequent function sequences
+        # Find most frequent function sequences (optimized - single pass)
         sequence_counts = defaultdict(int)
         for i in range(len(flow_data) - 1):
             current_func = flow_data[i].get('function')

praisonaiagents/telemetry/telemetry.py

@@ -13,20 +13,66 @@ import threading
 from typing import Dict, Any, Optional
 from datetime import datetime
 import logging
+from concurrent.futures import ThreadPoolExecutor
 
-# Try to import PostHog
-try:
-    from posthog import Posthog
-    POSTHOG_AVAILABLE = True
-except ImportError:
-    POSTHOG_AVAILABLE = False
+# Lazy imports - only import when needed
+_POSTHOG_AVAILABLE = None
+_POSTHOG_CLASS = None
 
-# Check for opt-out environment variables
-_TELEMETRY_DISABLED = any([
-    os.environ.get('PRAISONAI_TELEMETRY_DISABLED', '').lower() in ('true', '1', 'yes'),
-    os.environ.get('PRAISONAI_DISABLE_TELEMETRY', '').lower() in ('true', '1', 'yes'),
-    os.environ.get('DO_NOT_TRACK', '').lower() in ('true', '1', 'yes'),
-])
+def _get_posthog():
+    """Lazy import PostHog to avoid import overhead when disabled."""
+    global _POSTHOG_AVAILABLE, _POSTHOG_CLASS
+    if _POSTHOG_AVAILABLE is None:
+        try:
+            from posthog import Posthog
+            _POSTHOG_CLASS = Posthog
+            _POSTHOG_AVAILABLE = True
+        except ImportError:
+            _POSTHOG_AVAILABLE = False
+            _POSTHOG_CLASS = None
+    return _POSTHOG_CLASS if _POSTHOG_AVAILABLE else None
+
+# Cached result to avoid repeated environment variable checks
+_TELEMETRY_DISABLED_CACHE = None
+
+def _is_monitoring_disabled() -> bool:
+    """
+    Check if monitoring/telemetry is disabled via environment variables.
+    
+    NEW BEHAVIOR: Performance monitoring is now DISABLED BY DEFAULT.
+    To enable monitoring, set PRAISONAI_PERFORMANCE_ENABLED=true.
+    
+    The legacy disable flags still work for backward compatibility.
+    
+    This function is cached to avoid repeated environment variable lookups.
+    """
+    global _TELEMETRY_DISABLED_CACHE
+    
+    # Return cached result if available
+    if _TELEMETRY_DISABLED_CACHE is not None:
+        return _TELEMETRY_DISABLED_CACHE
+    
+    # Check if explicitly disabled via legacy flags
+    explicitly_disabled = any([
+        os.environ.get('PRAISONAI_PERFORMANCE_DISABLED', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('PRAISONAI_TELEMETRY_DISABLED', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('PRAISONAI_DISABLE_TELEMETRY', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('DO_NOT_TRACK', '').lower() in ('true', '1', 'yes'),
+    ])
+    
+    if explicitly_disabled:
+        _TELEMETRY_DISABLED_CACHE = True
+        return True
+    
+    # NEW: Check if explicitly enabled (required for monitoring to be active)
+    explicitly_enabled = any([
+        os.environ.get('PRAISONAI_PERFORMANCE_ENABLED', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('PRAISONAI_TELEMETRY_ENABLED', '').lower() in ('true', '1', 'yes'),
+    ])
+    
+    # Disabled by default unless explicitly enabled
+    _TELEMETRY_DISABLED_CACHE = not explicitly_enabled
+    return _TELEMETRY_DISABLED_CACHE
 
 
 class MinimalTelemetry:
@@ -61,17 +107,32 @@ class MinimalTelemetry:
         if enabled is not None:
             self.enabled = enabled
         else:
-            self.enabled = not _TELEMETRY_DISABLED
+            self.enabled = not _is_monitoring_disabled()
+        
+        # Fast path for disabled telemetry - minimal initialization
+        if not self.enabled:
+            self.logger = logging.getLogger(__name__)
+            self.logger.debug("Telemetry is disabled")
+            # Set minimal required attributes for disabled state
+            self._shutdown_complete = True
+            self._shutdown_lock = None
+            self._thread_pool = None
+            self._posthog = None
+            self._metrics = {}
+            self._metrics_lock = None
+            self.session_id = None
+            self._environment = {}
+            return
             
+        # Full initialization only when enabled
         self.logger = logging.getLogger(__name__)
         
         # Add shutdown tracking to prevent double shutdown
         self._shutdown_complete = False
         self._shutdown_lock = threading.Lock()
         
-        if not self.enabled:
-            self.logger.debug("Telemetry is disabled")
-            return
+        # Initialize thread pool for non-blocking telemetry operations
+        self._thread_pool = None
             
         # Generate anonymous session ID (not user ID)
         session_data = f"{datetime.now().isoformat()}-{os.getpid()}-{time.time()}"
@@ -96,28 +157,51 @@ class MinimalTelemetry:
         
         self.logger.debug(f"Telemetry enabled with session {self.session_id}")
         
-        # Initialize PostHog if available
-        if POSTHOG_AVAILABLE:
+        # Initialize thread pool for efficient telemetry operations
+        self._thread_pool = ThreadPoolExecutor(
+            max_workers=2, 
+            thread_name_prefix="telemetry"
+        )
+        
+        # Initialize PostHog lazily - only when needed
+        self._posthog = None
+        self._posthog_initialized = False
+    
+    def _get_framework_version(self) -> str:
+        """Get the PraisonAI Agents version."""
+        try:
+            from .. import __version__
+            return __version__
+        except (ImportError, KeyError, AttributeError):
+            return "unknown"
+    
+    def _get_posthog_client(self):
+        """Lazy initialization of PostHog client."""
+        if not self.enabled:
+            return None
+            
+        if self._posthog_initialized:
+            return self._posthog
+            
+        self._posthog_initialized = True
+        posthog_class = _get_posthog()
+        
+        if posthog_class:
             try:
-                self._posthog = Posthog(
+                self._posthog = posthog_class(
                     project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
                     host='https://eu.i.posthog.com',
                     disable_geoip=True,
                     on_error=lambda e: self.logger.debug(f"PostHog error: {e}"),
                     sync_mode=False  # Use async mode to prevent blocking
                 )
-            except:
+            except Exception as e:
+                self.logger.debug(f"Failed to initialize PostHog: {e}")
                 self._posthog = None
         else:
             self._posthog = None
-    
-    def _get_framework_version(self) -> str:
-        """Get the PraisonAI Agents version."""
-        try:
-            from .. import __version__
-            return __version__
-        except (ImportError, KeyError, AttributeError):
-            return "unknown"
+            
+        return self._posthog
     
     def track_agent_execution(self, agent_name: str = None, success: bool = True, async_mode: bool = False):
         """
@@ -138,12 +222,13 @@ class MinimalTelemetry:
         self.logger.debug(f"Agent execution tracked: success={success}")
         
         # Send event to PostHog
-        if self._posthog:
+        posthog_client = self._get_posthog_client()
+        if posthog_client:
             if async_mode:
-                # Use a background thread to prevent blocking streaming responses
+                # Use thread pool for efficient background execution
                 def _async_capture():
                     try:
-                        self._posthog.capture(
+                        posthog_client.capture(
                             distinct_id=self.session_id,
                             event='agent_execution',
                             properties={
@@ -155,13 +240,17 @@ class MinimalTelemetry:
                         # Silently handle any telemetry errors to avoid disrupting user experience
                         self.logger.debug(f"Async PostHog capture error: {e}")
                 
-                # Execute in background thread with daemon flag for clean shutdown
-                import threading
-                thread = threading.Thread(target=_async_capture, daemon=True)
-                thread.start()
+                # Use thread pool instead of creating new threads
+                if self._thread_pool:
+                    self._thread_pool.submit(_async_capture)
+                else:
+                    # Fallback to direct thread creation if pool not available
+                    import threading
+                    thread = threading.Thread(target=_async_capture, daemon=True)
+                    thread.start()
             else:
                 # Synchronous capture for backward compatibility
-                self._posthog.capture(
+                posthog_client.capture(
                     distinct_id=self.session_id,
                     event='agent_execution',
                     properties={
@@ -185,7 +274,8 @@ class MinimalTelemetry:
             self._metrics["task_completions"] += 1
         
         # Send event to PostHog
-        if self._posthog:
+        posthog_client = self._get_posthog_client()
+        if posthog_client:
             self._posthog.capture(
                 distinct_id=self.session_id,
                 event='task_completion',
@@ -229,7 +319,8 @@ class MinimalTelemetry:
                     timing_list[:] = timing_list[-self._max_timing_entries:]
         
         # Send event to PostHog
-        if self._posthog:
+        posthog_client = self._get_posthog_client()
+        if posthog_client:
             properties = {
                 'tool_name': tool_name,
                 'success': success,
@@ -266,7 +357,8 @@ class MinimalTelemetry:
             self._metrics["errors"] += 1
         
         # Send event to PostHog
-        if self._posthog:
+        posthog_client = self._get_posthog_client()
+        if posthog_client:
             self._posthog.capture(
                 distinct_id=self.session_id,
                 event='error',
@@ -290,7 +382,8 @@ class MinimalTelemetry:
             return
             
         # Send event to PostHog
-        if self._posthog:
+        posthog_client = self._get_posthog_client()
+        if posthog_client:
             self._posthog.capture(
                 distinct_id=self.session_id,
                 event='feature_usage',
@@ -336,10 +429,11 @@ class MinimalTelemetry:
         self.logger.debug(f"Telemetry flush: {metrics}")
         
         # Send to PostHog if available
-        if hasattr(self, '_posthog') and self._posthog:
+        posthog_client = self._get_posthog_client()
+        if posthog_client:
             
             try:
-                self._posthog.capture(
+                posthog_client.capture(
                     distinct_id='anonymous',
                     event='sdk_used',
                     properties={
@@ -376,6 +470,15 @@ class MinimalTelemetry:
         # Final flush
         self.flush()
         
+        # Shutdown thread pool
+        if self._thread_pool:
+            try:
+                self._thread_pool.shutdown(wait=True)  # Removed invalid timeout parameter
+            except Exception as e:
+                self.logger.debug(f"Thread pool shutdown error: {e}")
+            finally:
+                self._thread_pool = None
+        
         # Shutdown PostHog if available
         posthog_client = getattr(self, '_posthog', None)
         if posthog_client: