roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/services/metrics.py

@@ -0,0 +1,161 @@
+"""Metrics collection and reporting for monitoring operation performance."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from ..logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class OperationMetric:
+    """Track operation performance and success.
+
+    Attributes:
+        operation: Name of the operation being tracked
+        duration_ms: Duration of the operation in milliseconds
+        success: Whether the operation succeeded
+        error: Error message if operation failed, None otherwise
+        timestamp: When the operation completed (UTC)
+        metadata: Additional context about the operation
+    """
+
+    operation: str
+    duration_ms: float
+    success: bool
+    error: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class MetricsCollector:
+    """Collect and report application metrics.
+
+    This class maintains a collection of operation metrics and provides
+    aggregated statistics for monitoring and observability.
+    """
+
+    def __init__(self):
+        """Initialize an empty metrics collector."""
+        self.metrics: list[OperationMetric] = []
+        logger.debug("metrics_collector_initialized")
+
+    def record(self, metric: OperationMetric) -> None:
+        """Record a metric.
+
+        Args:
+            metric: The operation metric to record
+        """
+        self.metrics.append(metric)
+        logger.debug(
+            "metric_recorded",
+            operation=metric.operation,
+            duration_ms=metric.duration_ms,
+            success=metric.success,
+            error=metric.error,
+        )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get aggregated statistics from recorded metrics.
+
+        Returns:
+            Dictionary containing:
+                - total_operations: Total number of operations recorded
+                - success_rate: Percentage of successful operations (0.0-1.0)
+                - avg_duration_ms: Average operation duration in milliseconds
+                - errors: List of failed operation metrics
+                - operations_by_type: Count of operations grouped by type
+        """
+        if not self.metrics:
+            return {
+                "total_operations": 0,
+                "success_rate": 0.0,
+                "avg_duration_ms": 0.0,
+                "errors": [],
+                "operations_by_type": {},
+            }
+
+        total = len(self.metrics)
+        successful = sum(1 for m in self.metrics if m.success)
+        success_rate = successful / total if total > 0 else 0.0
+        avg_duration = sum(m.duration_ms for m in self.metrics) / total
+        errors = [m for m in self.metrics if not m.success]
+
+        # Count operations by type
+        operations_by_type: dict[str, int] = {}
+        for metric in self.metrics:
+            operations_by_type[metric.operation] = (
+                operations_by_type.get(metric.operation, 0) + 1
+            )
+
+        return {
+            "total_operations": total,
+            "success_rate": success_rate,
+            "avg_duration_ms": avg_duration,
+            "errors": errors,
+            "operations_by_type": operations_by_type,
+        }
+
+    def clear(self) -> None:
+        """Clear all recorded metrics."""
+        count = len(self.metrics)
+        self.metrics.clear()
+        logger.debug("metrics_cleared", count=count)
+
+    def get_error_rate(self) -> float:
+        """Get the error rate (1 - success_rate).
+
+        Returns:
+            Error rate as a float between 0.0 and 1.0
+        """
+        if not self.metrics:
+            return 0.0
+        return 1.0 - self.get_stats()["success_rate"]
+
+    def get_operation_stats(self, operation: str) -> dict[str, Any]:
+        """Get statistics for a specific operation type.
+
+        Args:
+            operation: Name of the operation to get stats for
+
+        Returns:
+            Dictionary with stats specific to this operation type
+        """
+        op_metrics = [m for m in self.metrics if m.operation == operation]
+
+        if not op_metrics:
+            return {
+                "count": 0,
+                "success_rate": 0.0,
+                "avg_duration_ms": 0.0,
+                "errors": [],
+            }
+
+        total = len(op_metrics)
+        successful = sum(1 for m in op_metrics if m.success)
+
+        return {
+            "count": total,
+            "success_rate": successful / total,
+            "avg_duration_ms": sum(m.duration_ms for m in op_metrics) / total,
+            "errors": [m for m in op_metrics if not m.success],
+        }
+
+
+# Global metrics collector instance
+_global_collector: MetricsCollector | None = None
+
+
+def get_metrics_collector() -> MetricsCollector:
+    """Get or create the global metrics collector instance.
+
+    Returns:
+        The global MetricsCollector instance
+    """
+    global _global_collector
+    if _global_collector is None:
+        _global_collector = MetricsCollector()
+        logger.debug("global_metrics_collector_created")
+    return _global_collector

roadmap/common/services/performance.py

@@ -0,0 +1,219 @@
+"""Performance monitoring decorators and utilities."""
+
+import functools
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ..logging import get_logger
+from .metrics import OperationMetric, get_metrics_collector
+from .profiling import get_profiler
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def timed_operation(operation_name: str | None = None, record_metric: bool = True):
+    """Time operations and optionally record metrics.
+
+    This decorator measures the execution time of a function and logs it.
+    It can also record the timing as a metric in the global MetricsCollector
+    and performance profiler.
+
+    Args:
+        operation_name: Name for the operation (defaults to function name)
+        record_metric: Whether to record the timing as a metric
+
+    Example:
+        @timed_operation("create_issue")
+        def create_issue(title: str) -> Issue:
+            # ... implementation
+            pass
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            op_name = operation_name or func.__name__
+            start_time = time.perf_counter()
+            error: Exception | None = None
+            result: Any = None
+
+            # Record in profiler
+            profiler = get_profiler()
+            profiler.start_operation(op_name)
+
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                raise
+            finally:
+                # Calculate duration
+                duration_ms = (time.perf_counter() - start_time) * 1000
+
+                # Record in profiler
+                profiler.end_operation(op_name, error=error is not None)
+
+                # Log the timing
+                if error:
+                    logger.error(
+                        "operation_failed",
+                        operation=op_name,
+                        duration_ms=round(duration_ms, 2),
+                        error=str(error),
+                        error_type=type(error).__name__,
+                    )
+                else:
+                    logger.info(
+                        "operation_completed",
+                        operation=op_name,
+                        duration_ms=round(duration_ms, 2),
+                    )
+
+                # Record metric if requested
+                if record_metric:
+                    collector = get_metrics_collector()
+                    metric = OperationMetric(
+                        operation=op_name,
+                        duration_ms=duration_ms,
+                        success=error is None,
+                        error=str(error) if error else None,
+                    )
+                    collector.record(metric)
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def async_timed_operation(
+    operation_name: str | None = None, record_metric: bool = True
+):
+    """Async version of timed_operation decorator.
+
+    Args:
+        operation_name: Name for the operation (defaults to function name)
+        record_metric: Whether to record the timing as a metric
+
+    Example:
+        @async_timed_operation("fetch_issues")
+        async def fetch_issues() -> list[Issue]:
+            # ... async implementation
+            pass
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            op_name = operation_name or func.__name__
+            start_time = time.perf_counter()
+            error: Exception | None = None
+            result: Any = None
+
+            try:
+                result = await func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                raise
+            finally:
+                # Calculate duration
+                duration_ms = (time.perf_counter() - start_time) * 1000
+
+                # Log the timing
+                if error:
+                    logger.error(
+                        "async_operation_failed",
+                        operation=op_name,
+                        duration_ms=round(duration_ms, 2),
+                        error=str(error),
+                        error_type=type(error).__name__,
+                    )
+                else:
+                    logger.info(
+                        "async_operation_completed",
+                        operation=op_name,
+                        duration_ms=round(duration_ms, 2),
+                    )
+
+                # Record metric if requested
+                if record_metric:
+                    collector = get_metrics_collector()
+                    metric = OperationMetric(
+                        operation=op_name,
+                        duration_ms=duration_ms,
+                        success=error is None,
+                        error=str(error) if error else None,
+                    )
+                    collector.record(metric)
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+class OperationTimer:
+    """Context manager for timing code blocks.
+
+    Example:
+        with OperationTimer("database_query") as timer:
+            # ... perform operation
+            pass
+        print(f"Operation took {timer.duration_ms}ms")
+    """
+
+    def __init__(self, operation_name: str, record_metric: bool = True):
+        """Initialize the timer.
+
+        Args:
+            operation_name: Name of the operation being timed
+            record_metric: Whether to record the timing as a metric
+        """
+        self.operation_name = operation_name
+        self.record_metric = record_metric
+        self.start_time: float | None = None
+        self.end_time: float | None = None
+        self.duration_ms: float | None = None
+        self.error: Exception | None = None
+
+    def __enter__(self) -> "OperationTimer":
+        """Start the timer."""
+        self.start_time = time.perf_counter()
+        logger.debug("operation_started", operation=self.operation_name)
+        return self
+
+    def __exit__(self, _exc_type, exc_val, _exc_tb) -> None:
+        """Stop the timer and record metrics."""
+        self.end_time = time.perf_counter()
+        assert self.start_time is not None
+        self.duration_ms = (self.end_time - self.start_time) * 1000
+
+        if exc_val:
+            self.error = exc_val
+            logger.error(
+                "operation_failed",
+                operation=self.operation_name,
+                duration_ms=round(self.duration_ms, 2),
+                error=str(exc_val),
+                error_type=type(exc_val).__name__,
+            )
+        else:
+            logger.info(
+                "operation_completed",
+                operation=self.operation_name,
+                duration_ms=round(self.duration_ms, 2),
+            )
+
+        # Record metric if requested
+        if self.record_metric:
+            collector = get_metrics_collector()
+            metric = OperationMetric(
+                operation=self.operation_name,
+                duration_ms=self.duration_ms,
+                success=exc_val is None,
+                error=str(exc_val) if exc_val else None,
+            )
+            collector.record(metric)

roadmap/common/services/profiling.py

@@ -0,0 +1,288 @@
+"""Performance benchmarking and profiling utilities.
+
+This module provides tools for measuring and analyzing performance of CLI operations,
+including execution timing, memory usage, and operation throughput.
+"""
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from ..logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class OperationProfile:
+    """Profile data for a single operation type.
+
+    Attributes:
+        operation: Name of the operation
+        count: Number of times operation was executed
+        total_time_ms: Total execution time in milliseconds
+        min_time_ms: Minimum single execution time
+        max_time_ms: Maximum single execution time
+    """
+
+    operation: str
+    count: int = 0
+    total_time_ms: float = 0.0
+    min_time_ms: float = float("inf")
+    max_time_ms: float = 0.0
+    errors: int = 0
+
+    @property
+    def avg_time_ms(self) -> float:
+        """Calculate average execution time."""
+        return self.total_time_ms / self.count if self.count > 0 else 0.0
+
+    @property
+    def throughput_per_sec(self) -> float:
+        """Calculate operations per second."""
+        if self.total_time_ms <= 0:
+            return 0.0
+        return (self.count / self.total_time_ms) * 1000
+
+    def record(self, duration_ms: float, error: bool = False) -> None:
+        """Record a single operation execution.
+
+        Args:
+            duration_ms: Execution time in milliseconds
+            error: Whether the operation failed
+        """
+        self.count += 1
+        self.total_time_ms += duration_ms
+        self.min_time_ms = min(self.min_time_ms, duration_ms)
+        self.max_time_ms = max(self.max_time_ms, duration_ms)
+        if error:
+            self.errors += 1
+
+
+class PerformanceProfiler:
+    """Profiles operation performance metrics across a session.
+
+    Tracks execution time, error rates, and throughput for all operations,
+    providing detailed performance insights.
+
+    Example:
+        profiler = PerformanceProfiler()
+        profiler.start_operation("fetch_issues")
+        # ... do work
+        profiler.end_operation("fetch_issues")
+
+        report = profiler.get_report()
+        print(report.format())
+    """
+
+    def __init__(self) -> None:
+        """Initialize profiler with no operations."""
+        self._profiles: dict[str, OperationProfile] = {}
+        self._start_times: dict[str, float] = {}
+        logger.debug("profiler_initialized")
+
+    def start_operation(self, operation: str) -> None:
+        """Mark the start of an operation.
+
+        Args:
+            operation: Name of the operation
+
+        Example:
+            profiler.start_operation("sync_all")
+        """
+        self._start_times[operation] = time.perf_counter()
+
+    def end_operation(self, operation: str, error: bool = False) -> float:
+        """Mark the end of an operation and record metrics.
+
+        Args:
+            operation: Name of the operation
+            error: Whether the operation failed
+
+        Returns:
+            Duration in milliseconds
+
+        Example:
+            try:
+                # ... do work
+                profiler.end_operation("sync_all")
+            except Exception:
+                profiler.end_operation("sync_all", error=True)
+                raise
+        """
+        if operation not in self._start_times:
+            logger.warning("operation_not_started", operation=operation)
+            return 0.0
+
+        start = self._start_times.pop(operation)
+        duration_ms = (time.perf_counter() - start) * 1000
+
+        if operation not in self._profiles:
+            self._profiles[operation] = OperationProfile(operation)
+
+        self._profiles[operation].record(duration_ms, error=error)
+        logger.debug(
+            "operation_profiled",
+            operation=operation,
+            duration_ms=duration_ms,
+            error=error,
+        )
+
+        return duration_ms
+
+    def get_profile(self, operation: str) -> OperationProfile | None:
+        """Get profile for a specific operation.
+
+        Args:
+            operation: Name of the operation
+
+        Returns:
+            OperationProfile if found, None otherwise
+        """
+        return self._profiles.get(operation)
+
+    def get_slowest_operations(self, limit: int = 10) -> list[OperationProfile]:
+        """Get the slowest operations by average execution time.
+
+        Args:
+            limit: Maximum number of results to return
+
+        Returns:
+            List of operations sorted by average time (slowest first)
+        """
+        sorted_ops = sorted(
+            self._profiles.values(), key=lambda p: p.avg_time_ms, reverse=True
+        )
+        return sorted_ops[:limit]
+
+    def get_report(self) -> "PerformanceReport":
+        """Generate a performance report for all operations.
+
+        Returns:
+            PerformanceReport with aggregated metrics
+        """
+        total_time_ms = sum(p.total_time_ms for p in self._profiles.values())
+        total_count = sum(p.count for p in self._profiles.values())
+        total_errors = sum(p.errors for p in self._profiles.values())
+
+        return PerformanceReport(
+            profiles=self._profiles.copy(),
+            total_time_ms=total_time_ms,
+            total_operations=total_count,
+            total_errors=total_errors,
+        )
+
+    def clear(self) -> None:
+        """Clear all profiles."""
+        self._profiles.clear()
+        self._start_times.clear()
+        logger.debug("profiler_cleared")
+
+
+@dataclass
+class PerformanceReport:
+    """Aggregated performance metrics for a session.
+
+    Attributes:
+        profiles: Dictionary of operation profiles
+        total_time_ms: Total execution time
+        total_operations: Total operations executed
+        total_errors: Total failed operations
+    """
+
+    profiles: dict[str, OperationProfile]
+    total_time_ms: float
+    total_operations: int
+    total_errors: int
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate overall success rate (0.0-1.0)."""
+        if self.total_operations == 0:
+            return 0.0
+        return (self.total_operations - self.total_errors) / self.total_operations
+
+    def format(self) -> str:
+        """Format report as human-readable string.
+
+        Returns:
+            Formatted performance report
+
+        Example:
+            report = profiler.get_report()
+            print(report.format())
+        """
+        lines = [
+            "═" * 70,
+            "PERFORMANCE REPORT",
+            "═" * 70,
+            f"Total Time: {self.total_time_ms:.2f}ms",
+            f"Total Operations: {self.total_operations}",
+            f"Success Rate: {self.success_rate:.1%}",
+            "",
+            "Operation Breakdown:",
+            "-" * 70,
+        ]
+
+        # Sort by total time
+        sorted_ops = sorted(
+            self.profiles.values(), key=lambda p: p.total_time_ms, reverse=True
+        )
+
+        for profile in sorted_ops:
+            pct = (
+                (profile.total_time_ms / self.total_time_ms * 100)
+                if self.total_time_ms > 0
+                else 0
+            )
+            error_str = f" ({profile.errors} errors)" if profile.errors > 0 else ""
+
+            lines.append(
+                f"{profile.operation:30} {profile.count:5} ops  "
+                f"{profile.avg_time_ms:8.2f}ms avg  {pct:5.1f}%{error_str}"
+            )
+
+        lines.append("═" * 70)
+        return "\n".join(lines)
+
+    def get_dict(self) -> dict[str, Any]:
+        """Convert report to dictionary format.
+
+        Returns:
+            Dictionary representation of the report
+        """
+        return {
+            "total_time_ms": self.total_time_ms,
+            "total_operations": self.total_operations,
+            "success_rate": self.success_rate,
+            "total_errors": self.total_errors,
+            "operations": {
+                name: {
+                    "count": profile.count,
+                    "total_ms": profile.total_time_ms,
+                    "avg_ms": profile.avg_time_ms,
+                    "min_ms": profile.min_time_ms if profile.count > 0 else 0,
+                    "max_ms": profile.max_time_ms,
+                    "throughput_ops_per_sec": profile.throughput_per_sec,
+                    "errors": profile.errors,
+                }
+                for name, profile in self.profiles.items()
+            },
+        }
+
+
+# Global profiler instance
+_profiler = PerformanceProfiler()
+
+
+def get_profiler() -> PerformanceProfiler:
+    """Get the global profiler instance.
+
+    Returns:
+        The singleton PerformanceProfiler instance
+
+    Example:
+        profiler = get_profiler()
+        profiler.start_operation("my_op")
+    """
+    return _profiler