roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/logging/error_logging.py

@@ -0,0 +1,217 @@
+"""Error logging utilities for structured error handling and diagnostics.
+
+Provides functions to log errors with context, classify errors, and provide
+recovery suggestions for better debugging and operational visibility.
+"""
+
+import traceback
+from typing import Any
+
+from roadmap.common.logging.loggers import get_logger
+
+logger = get_logger(__name__)
+
+
+class ErrorClassification:
+    """Error classification constants."""
+
+    USER_ERROR = "user_error"  # User input or usage error
+    SYSTEM_ERROR = "system_error"  # Internal system failure
+    EXTERNAL_ERROR = "external_error"  # External service failure
+    UNKNOWN_ERROR = "unknown_error"  # Unclassified
+
+
+def classify_error(error: Exception) -> str:
+    """Classify an error to help with diagnostics and recovery.
+
+    Args:
+        error: The exception to classify
+
+    Returns:
+        Error classification string
+    """
+    # Import these locally to avoid circular imports
+    from roadmap.common.errors import RoadmapError, ValidationError
+
+    if isinstance(error, ValidationError | ValueError | TypeError | KeyError):
+        return ErrorClassification.USER_ERROR
+
+    if isinstance(error, OSError | RoadmapError):
+        return ErrorClassification.SYSTEM_ERROR
+
+    if isinstance(error, ConnectionError | TimeoutError):
+        return ErrorClassification.EXTERNAL_ERROR
+
+    return ErrorClassification.UNKNOWN_ERROR
+
+
+def is_error_recoverable(error: Exception) -> bool:
+    """Determine if an error is recoverable with retry.
+
+    Args:
+        error: The exception to evaluate
+
+    Returns:
+        True if the error is likely recoverable with retry
+    """
+    recoverable_errors = (
+        ConnectionError,
+        TimeoutError,
+        BlockingIOError,
+        BrokenPipeError,
+    )
+    return isinstance(error, recoverable_errors)
+
+
+def suggest_recovery(error: Exception, context: dict | None = None) -> str:
+    """Suggest a recovery action for an error.
+
+    Args:
+        error: The exception to suggest recovery for
+        context: Additional context about the operation
+
+    Returns:
+        Suggested recovery action
+    """
+    classification = classify_error(error)
+
+    if is_error_recoverable(error):
+        return "retry"
+
+    if classification == ErrorClassification.USER_ERROR:
+        return "validate_input"
+
+    if classification == ErrorClassification.EXTERNAL_ERROR:
+        return "check_connectivity"
+
+    if classification == ErrorClassification.SYSTEM_ERROR:
+        return "manual_intervention"
+
+    return "contact_support"
+
+
+def log_error_with_context(
+    error: Exception,
+    operation: str,
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    additional_context: dict | None = None,
+    include_traceback: bool = False,
+) -> None:
+    """Log an error with comprehensive context for debugging.
+
+    Args:
+        error: The exception that occurred
+        operation: Name of the operation that failed
+        entity_type: Type of entity being operated on
+        entity_id: ID of the entity
+        additional_context: Any additional context dictionary
+        include_traceback: Whether to include full traceback
+    """
+    classification = classify_error(error)
+    recoverable = is_error_recoverable(error)
+    recovery_action = suggest_recovery(error)
+
+    context = {
+        "operation": operation,
+        "entity_type": entity_type,
+        "entity_id": entity_id,
+        "error_type": type(error).__name__,
+        "error_message": str(error),
+        "error_classification": classification,
+        "is_recoverable": recoverable,
+        "suggested_action": recovery_action,
+    }
+
+    if additional_context:
+        context.update(additional_context)
+
+    if include_traceback:
+        context["traceback"] = traceback.format_exc()
+
+    logger.error("operation_failed", **context)
+
+
+def log_validation_error(
+    error: Exception,
+    entity_type: str,
+    field_name: str | None = None,
+    proposed_value: Any | None = None,
+) -> None:
+    """Log a validation error with field-specific context.
+
+    Args:
+        error: The validation error
+        entity_type: Type of entity being validated
+        field_name: Name of the field that failed validation
+        proposed_value: The value that failed validation
+    """
+    logger.warning(
+        "validation_error",
+        error_type=type(error).__name__,
+        error_message=str(error),
+        entity_type=entity_type,
+        field_name=field_name,
+        proposed_value=proposed_value,
+        suggested_action="validate_input",
+    )
+
+
+def log_database_error(
+    error: Exception,
+    operation: str,
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    retry_count: int = 0,
+) -> None:
+    """Log a database error with recovery context.
+
+    Args:
+        error: The database error
+        operation: Database operation that failed (create, read, update, delete)
+        entity_type: Type of entity
+        entity_id: ID of the entity
+        retry_count: Number of retries attempted
+    """
+    recoverable = is_error_recoverable(error)
+    recovery_action = "retry" if recoverable else "manual_intervention"
+
+    logger.error(
+        "database_operation_failed",
+        operation=operation,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        error_type=type(error).__name__,
+        error_message=str(error),
+        retry_count=retry_count,
+        is_recoverable=recoverable,
+        suggested_action=recovery_action,
+    )
+
+
+def log_external_service_error(
+    error: Exception,
+    service_name: str,
+    operation: str,
+    retry_count: int = 0,
+) -> None:
+    """Log an external service error (GitHub API, etc.).
+
+    Args:
+        error: The error from external service
+        service_name: Name of the external service
+        operation: Operation being performed
+        retry_count: Number of retries attempted
+    """
+    logger.error(
+        "external_service_error",
+        service_name=service_name,
+        operation=operation,
+        error_type=type(error).__name__,
+        error_message=str(error),
+        retry_count=retry_count,
+        is_recoverable=is_error_recoverable(error),
+        suggested_action="check_connectivity"
+        if is_error_recoverable(error)
+        else "contact_support",
+    )

roadmap/common/logging/formatters.py

@@ -0,0 +1,124 @@
+"""Log formatters and data scrubbing for structured logging."""
+
+from typing import Any
+
+# Sensitive keys that should be redacted from logs
+SENSITIVE_KEYS = {
+    "token",
+    "password",
+    "secret",
+    "api_key",
+    "auth",
+    "credential",
+    "github_token",
+}
+
+
+class StructuredFormatter:
+    """Custom formatter that includes structured fields from event data.
+
+    This formatter enhances logging to include any extra fields that were
+    passed as structured data via structlog. This makes error context
+    (error_type, error_message, etc.) visible in console/file output.
+    """
+
+    def format(self, record: dict[str, Any]) -> str:
+        """Format event dict with structured fields.
+
+        Args:
+            record: Event dictionary from structlog
+
+        Returns:
+            Formatted log message with structured fields
+        """
+        # Get the base message
+        base_msg = record.get("event", "")
+
+        # Collect extra fields that aren't standard structlog attributes
+        standard_attrs = {
+            "event",
+            "log_level",
+            "timestamp",
+            "_from_structlog",
+            "_record",
+            "_logger",
+            "_method_name",
+            "_fn_module",
+            "_fn_name",
+            "_fn_lineno",
+            "exception",
+            "exc_info",
+            "stack_info",
+        }
+
+        extra_fields = {}
+        for key, value in record.items():
+            if key not in standard_attrs and not key.startswith("_"):
+                extra_fields[key] = value
+
+        # Append extra fields to message if any exist
+        if extra_fields:
+            # Format structured fields nicely
+            field_strs = []
+            for key, value in sorted(extra_fields.items()):
+                # Truncate very long values
+                value_str = str(value)
+                if len(value_str) > 200:
+                    value_str = value_str[:200] + "..."
+                field_strs.append(f"{key}={value_str}")
+
+            base_msg += " | " + " ".join(field_strs)
+
+        return base_msg
+
+
+def scrub_sensitive_data(_logger, _method_name, event_dict):
+    """Structlog processor to remove sensitive data from logs."""
+
+    def scrub_value(key, value):
+        """Recursively scrub sensitive values."""
+        if any(sensitive in key.lower() for sensitive in SENSITIVE_KEYS):
+            return "***REDACTED***"
+        if isinstance(value, dict):
+            return {k: scrub_value(k, v) for k, v in value.items()}
+        if isinstance(value, list | tuple):
+            return type(value)(scrub_value(f"item_{i}", v) for i, v in enumerate(value))
+        return value
+
+    return {k: scrub_value(k, v) for k, v in event_dict.items()}
+
+
+def include_structured_fields_in_message(_logger, _method_name, event_dict):
+    """Include structured fields (error_type, error_message, etc.) in the log message.
+
+    This processor appends structured fields to the message so they're visible
+    in console/file output, not just in the LogRecord attributes.
+    """
+    # Extract message
+    msg = event_dict.get("event", "")
+
+    # Collect non-standard fields (excluding stdlib ones)
+    standard_fields = {
+        "event",
+        "log_level",
+        "timestamp",
+        "correlation_id",
+        "_from_structlog",
+    }
+    extra_fields = {k: v for k, v in event_dict.items() if k not in standard_fields}
+
+    # Append extra fields to message if any exist
+    if extra_fields:
+        field_strs = []
+        for key in sorted(extra_fields.keys()):
+            value = extra_fields[key]
+            value_str = str(value)
+            # Truncate very long values
+            if len(value_str) > 100:
+                value_str = value_str[:100] + "..."
+            field_strs.append(f"{key}={value_str}")
+
+        if field_strs:
+            event_dict["event"] = msg + " | " + " ".join(field_strs)
+
+    return event_dict

roadmap/common/logging/loggers.py

@@ -0,0 +1,68 @@
+"""Logger factory functions for different application layers."""
+
+import structlog
+
+
+def get_logger(name: str = "roadmap") -> structlog.stdlib.BoundLogger:
+    """Get a logger instance.
+
+    Args:
+        name: Logger name
+
+    Returns:
+        Configured structlog logger
+    """
+    return structlog.get_logger(name)
+
+
+def get_domain_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get logger for domain layer.
+
+    Args:
+        name: Component name (e.g., "issue", "milestone")
+
+    Returns:
+        Logger with domain namespace
+    """
+    return get_logger(f"roadmap.domain.{name}")
+
+
+def get_application_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get logger for application layer.
+
+    Args:
+        name: Component name (e.g., "issue_service", "sync_service")
+
+    Returns:
+        Logger with application namespace
+    """
+    return get_logger(f"roadmap.application.{name}")
+
+
+def get_infrastructure_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get logger for infrastructure layer.
+
+    Args:
+        name: Component name (e.g., "github", "storage")
+
+    Returns:
+        Logger with infrastructure namespace
+    """
+    return get_logger(f"roadmap.infrastructure.{name}")
+
+
+def get_presentation_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get logger for presentation layer.
+
+    Args:
+        name: Component name (e.g., "cli.issues", "cli.milestones")
+
+    Returns:
+        Logger with presentation namespace
+    """
+    return get_logger(f"roadmap.presentation.{name}")
+
+
+def get_security_logger():
+    """Get the security logger for backwards compatibility."""
+    return get_logger("roadmap.security")

roadmap/common/logging/performance_tracking.py

@@ -0,0 +1,267 @@
+"""Performance tracking utilities for operation timing and monitoring.
+
+Provides context managers and decorators to track operation duration,
+identify bottlenecks, and monitor system performance.
+"""
+
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from roadmap.common.logging.loggers import get_logger
+
+logger = get_logger(__name__)
+
+
+@contextmanager
+def track_operation_time(
+    operation_name: str,
+    warn_threshold_ms: int = 5000,
+    log_level: str = "debug",
+) -> Generator[dict, None, None]:
+    """Context manager to track operation timing.
+
+    Args:
+        operation_name: Name of the operation being timed
+        warn_threshold_ms: Log warning if operation exceeds this time
+        log_level: Log level to use for normal operations (debug or info)
+
+    Example:
+        with track_operation_time("sync_issues", warn_threshold_ms=5000):
+            sync_to_github()
+    """
+    start_time = time.time()
+    result = {"duration_ms": 0, "exceeded_threshold": False}
+
+    try:
+        yield result
+    finally:
+        duration_ms = (time.time() - start_time) * 1000
+        result["duration_ms"] = duration_ms
+
+        if duration_ms > warn_threshold_ms:
+            result["exceeded_threshold"] = True
+            logger.warning(
+                "operation_slow",
+                operation_name=operation_name,
+                duration_ms=duration_ms,
+                threshold_ms=warn_threshold_ms,
+            )
+        else:
+            log_func = getattr(logger, log_level, logger.debug)
+            log_func(
+                "operation_completed",
+                operation_name=operation_name,
+                duration_ms=duration_ms,
+            )
+
+
+@contextmanager
+def track_database_operation(
+    operation: str,
+    entity_type: str,
+    entity_id: str | None = None,
+    warn_threshold_ms: int = 1000,
+) -> Generator[dict, None, None]:
+    """Context manager to track database operation timing.
+
+    Args:
+        operation: Type of operation (create, read, update, delete)
+        entity_type: Type of entity
+        entity_id: ID of the entity (if applicable)
+        warn_threshold_ms: Warn if operation exceeds this time
+
+    Example:
+        with track_database_operation("create", "issue", entity_id="123"):
+            db.create_issue(...)
+    """
+    start_time = time.time()
+    result = {"duration_ms": 0, "exceeded_threshold": False}
+
+    try:
+        yield result
+    finally:
+        duration_ms = (time.time() - start_time) * 1000
+        result["duration_ms"] = duration_ms
+
+        if duration_ms > warn_threshold_ms:
+            result["exceeded_threshold"] = True
+            logger.warning(
+                "database_operation_slow",
+                operation=operation,
+                entity_type=entity_type,
+                entity_id=entity_id,
+                duration_ms=duration_ms,
+                threshold_ms=warn_threshold_ms,
+            )
+        else:
+            logger.debug(
+                "database_operation_completed",
+                operation=operation,
+                entity_type=entity_type,
+                entity_id=entity_id,
+                duration_ms=duration_ms,
+            )
+
+
+@contextmanager
+def track_file_operation(
+    operation: str,
+    file_path: str,
+    warn_threshold_ms: int = 500,
+) -> Generator[dict, None, None]:
+    """Context manager to track file I/O operation timing.
+
+    Args:
+        operation: Type of operation (read, write, sync)
+        file_path: Path to the file
+        warn_threshold_ms: Warn if operation exceeds this time
+
+    Example:
+        with track_file_operation("sync", "issue.md"):
+            sync_issue_file(...)
+    """
+    start_time = time.time()
+    result = {"duration_ms": 0, "exceeded_threshold": False}
+
+    try:
+        yield result
+    finally:
+        duration_ms = (time.time() - start_time) * 1000
+        result["duration_ms"] = duration_ms
+
+        if duration_ms > warn_threshold_ms:
+            result["exceeded_threshold"] = True
+            logger.warning(
+                "file_operation_slow",
+                operation=operation,
+                file_path=file_path,
+                duration_ms=duration_ms,
+                threshold_ms=warn_threshold_ms,
+            )
+        else:
+            logger.debug(
+                "file_operation_completed",
+                operation=operation,
+                file_path=file_path,
+                duration_ms=duration_ms,
+            )
+
+
+@contextmanager
+def track_sync_operation(
+    operation_name: str,
+    entity_count: int | None = None,
+    warn_threshold_ms: int = 10000,
+) -> Generator[dict, None, None]:
+    """Context manager to track sync operation timing and throughput.
+
+    Args:
+        operation_name: Name of the sync operation
+        entity_count: Number of entities being synced
+        warn_threshold_ms: Warn if operation exceeds this time
+
+    Example:
+        with track_sync_operation("sync_to_github", entity_count=10):
+            github_client.sync_issues(...)
+    """
+    start_time = time.time()
+    result = {
+        "duration_ms": 0,
+        "exceeded_threshold": False,
+        "throughput_items_per_sec": 0,
+    }
+
+    try:
+        yield result
+    finally:
+        duration_ms = (time.time() - start_time) * 1000
+        result["duration_ms"] = duration_ms
+
+        if entity_count:
+            result["throughput_items_per_sec"] = (entity_count * 1000) / duration_ms
+
+        if duration_ms > warn_threshold_ms:
+            result["exceeded_threshold"] = True
+            logger.warning(
+                "operation_slow",
+                operation_name=operation_name,
+                duration_ms=duration_ms,
+                entity_count=entity_count,
+                threshold_ms=warn_threshold_ms,
+                throughput_items_per_sec=result.get("throughput_items_per_sec"),
+            )
+        else:
+            logger.info(
+                "operation_completed",
+                operation_name=operation_name,
+                duration_ms=duration_ms,
+                entity_count=entity_count,
+                throughput_items_per_sec=result.get("throughput_items_per_sec"),
+            )
+
+
+class OperationTimer:
+    """Class for tracking multi-step operations and performance metrics."""
+
+    def __init__(self, operation_name: str):
+        """Initialize operation timer.
+
+        Args:
+            operation_name: Name of the overall operation
+        """
+        self.operation_name = operation_name
+        self.start_time = time.time()
+        self.steps = {}
+        self.current_step = None
+        self.current_step_start = None
+
+    def start_step(self, step_name: str) -> None:
+        """Start tracking a named step.
+
+        Args:
+            step_name: Name of the step
+        """
+        if self.current_step:
+            self.end_step()
+
+        self.current_step = step_name
+        self.current_step_start = time.time()
+
+    def end_step(self) -> None:
+        """End tracking current step."""
+        if self.current_step and self.current_step_start:
+            duration_ms = (time.time() - self.current_step_start) * 1000
+            self.steps[self.current_step] = duration_ms
+            logger.debug(
+                "step_completed",
+                operation_name=self.operation_name,
+                step=self.current_step,
+                duration_ms=duration_ms,
+            )
+            self.current_step = None
+            self.current_step_start = None
+
+    def finish(self) -> dict:
+        """Finish timing operation and return summary.
+
+        Returns:
+            Dictionary with timing information
+        """
+        if self.current_step:
+            self.end_step()
+
+        total_duration_ms = (time.time() - self.start_time) * 1000
+        result = {
+            "operation": self.operation_name,
+            "total_duration_ms": total_duration_ms,
+            "steps": self.steps,
+        }
+
+        logger.info(
+            "operation_finished",
+            operation_name=self.operation_name,
+            **result,
+        )
+
+        return result