truthound 1.0.8__py3-none-any.whl

truthound/checkpoint/monitoring/views/base.py

@@ -0,0 +1,172 @@
+"""Base view implementation.
+
+Provides abstract base class for monitoring views with common formatting.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from truthound.checkpoint.monitoring.protocols import (
+    MonitoringViewProtocol,
+    QueueMetrics,
+    WorkerMetrics,
+    TaskMetrics,
+)
+
+
+class BaseView(ABC):
+    """Abstract base class for monitoring views.
+
+    Provides common formatting functionality and enforces
+    the view protocol interface.
+    """
+
+    def __init__(self, name: str | None = None) -> None:
+        """Initialize view.
+
+        Args:
+            name: View name.
+        """
+        self._name = name or self.__class__.__name__
+
+    @property
+    def name(self) -> str:
+        """Get view name."""
+        return self._name
+
+    @abstractmethod
+    def render(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> dict[str, Any]:
+        """Render metrics as a dictionary.
+
+        Args:
+            metrics: Metrics to render.
+
+        Returns:
+            Rendered view as dictionary.
+        """
+        pass
+
+    @abstractmethod
+    def render_summary(
+        self,
+        queue_metrics: list[QueueMetrics],
+        worker_metrics: list[WorkerMetrics],
+    ) -> dict[str, Any]:
+        """Render a summary view.
+
+        Args:
+            queue_metrics: Queue metrics.
+            worker_metrics: Worker metrics.
+
+        Returns:
+            Summary view as dictionary.
+        """
+        pass
+
+    def format_for_api(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> dict[str, Any]:
+        """Format metrics for REST API response.
+
+        Default implementation uses render() and adds API metadata.
+
+        Args:
+            metrics: Metrics to format.
+
+        Returns:
+            API-formatted dictionary.
+        """
+        rendered = self.render(metrics)
+        return {
+            "data": rendered,
+            "type": self._get_metrics_type(metrics),
+            "view": self.name,
+            "generated_at": datetime.now().isoformat(),
+        }
+
+    @abstractmethod
+    def format_for_cli(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> str:
+        """Format metrics for CLI display.
+
+        Args:
+            metrics: Metrics to format.
+
+        Returns:
+            CLI-formatted string.
+        """
+        pass
+
+    def _get_metrics_type(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> str:
+        """Get the type name of the metrics."""
+        if isinstance(metrics, QueueMetrics):
+            return "queue"
+        elif isinstance(metrics, WorkerMetrics):
+            return "worker"
+        elif isinstance(metrics, TaskMetrics):
+            return "task"
+        return "unknown"
+
+    def _format_duration(self, milliseconds: float) -> str:
+        """Format duration in human-readable form."""
+        if milliseconds < 1000:
+            return f"{milliseconds:.0f}ms"
+        elif milliseconds < 60000:
+            return f"{milliseconds / 1000:.1f}s"
+        elif milliseconds < 3600000:
+            return f"{milliseconds / 60000:.1f}m"
+        else:
+            return f"{milliseconds / 3600000:.1f}h"
+
+    def _format_count(self, count: int) -> str:
+        """Format large counts in human-readable form."""
+        if count < 1000:
+            return str(count)
+        elif count < 1000000:
+            return f"{count / 1000:.1f}K"
+        elif count < 1000000000:
+            return f"{count / 1000000:.1f}M"
+        else:
+            return f"{count / 1000000000:.1f}B"
+
+    def _format_rate(self, rate: float) -> str:
+        """Format rate in human-readable form."""
+        if rate < 1:
+            return f"{rate * 60:.1f}/min"
+        elif rate < 100:
+            return f"{rate:.1f}/s"
+        else:
+            return f"{rate:.0f}/s"
+
+    def _format_percentage(self, value: float) -> str:
+        """Format percentage value."""
+        return f"{value * 100:.1f}%"
+
+    def _status_emoji(self, status: str) -> str:
+        """Get emoji for status (for CLI display)."""
+        emoji_map = {
+            "online": "[+]",
+            "offline": "[-]",
+            "busy": "[~]",
+            "draining": "[!]",
+            "pending": "[ ]",
+            "running": "[>]",
+            "succeeded": "[v]",
+            "failed": "[x]",
+            "healthy": "[v]",
+            "degraded": "[!]",
+            "critical": "[x]",
+        }
+        return emoji_map.get(status.lower(), "[?]")

truthound/checkpoint/monitoring/views/queue_view.py

@@ -0,0 +1,220 @@
+"""Queue status view.
+
+Renders queue metrics for display in various formats.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from truthound.checkpoint.monitoring.protocols import (
+    QueueMetrics,
+    WorkerMetrics,
+    TaskMetrics,
+)
+from truthound.checkpoint.monitoring.views.base import BaseView
+
+
+class QueueStatusView(BaseView):
+    """View for rendering queue status.
+
+    Example:
+        >>> view = QueueStatusView()
+        >>>
+        >>> # Render single queue
+        >>> output = view.render(queue_metrics)
+        >>>
+        >>> # Render for CLI
+        >>> print(view.format_for_cli(queue_metrics))
+        Queue: default
+        ├── Status: healthy [v]
+        ├── Pending: 5
+        ├── Running: 3
+        ├── Completed: 1,234
+        └── Throughput: 2.5/s
+    """
+
+    def __init__(self, name: str = "queue_status") -> None:
+        """Initialize queue status view."""
+        super().__init__(name=name)
+
+    def render(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> dict[str, Any]:
+        """Render queue metrics as dictionary."""
+        if not isinstance(metrics, QueueMetrics):
+            return {"error": "Expected QueueMetrics"}
+
+        return {
+            "queue_name": metrics.queue_name,
+            "status": "healthy" if metrics.is_healthy else "degraded",
+            "counts": {
+                "pending": metrics.pending_count,
+                "running": metrics.running_count,
+                "completed": metrics.completed_count,
+                "failed": metrics.failed_count,
+                "total": metrics.total_tasks,
+            },
+            "performance": {
+                "avg_wait_time_ms": round(metrics.avg_wait_time_ms, 2),
+                "avg_execution_time_ms": round(metrics.avg_execution_time_ms, 2),
+                "throughput_per_second": round(metrics.throughput_per_second, 3),
+                "success_rate": round(metrics.success_rate, 4),
+            },
+            "timestamp": metrics.timestamp.isoformat(),
+            "labels": metrics.labels,
+        }
+
+    def render_summary(
+        self,
+        queue_metrics: list[QueueMetrics],
+        worker_metrics: list[WorkerMetrics],
+    ) -> dict[str, Any]:
+        """Render summary of all queues."""
+        if not queue_metrics:
+            return {
+                "queues": [],
+                "totals": {
+                    "queue_count": 0,
+                    "pending": 0,
+                    "running": 0,
+                    "completed": 0,
+                    "failed": 0,
+                },
+                "health": {
+                    "healthy": 0,
+                    "degraded": 0,
+                    "status": "no_data",
+                },
+            }
+
+        queues = [self.render(qm) for qm in queue_metrics]
+        healthy_count = sum(1 for qm in queue_metrics if qm.is_healthy)
+        degraded_count = len(queue_metrics) - healthy_count
+
+        # Determine overall health status
+        if degraded_count == 0:
+            overall_status = "healthy"
+        elif degraded_count < len(queue_metrics) / 2:
+            overall_status = "degraded"
+        else:
+            overall_status = "critical"
+
+        return {
+            "queues": queues,
+            "totals": {
+                "queue_count": len(queue_metrics),
+                "pending": sum(qm.pending_count for qm in queue_metrics),
+                "running": sum(qm.running_count for qm in queue_metrics),
+                "completed": sum(qm.completed_count for qm in queue_metrics),
+                "failed": sum(qm.failed_count for qm in queue_metrics),
+                "throughput": sum(qm.throughput_per_second for qm in queue_metrics),
+            },
+            "health": {
+                "healthy": healthy_count,
+                "degraded": degraded_count,
+                "status": overall_status,
+            },
+        }
+
+    def format_for_cli(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> str:
+        """Format queue metrics for CLI display."""
+        if not isinstance(metrics, QueueMetrics):
+            return "Error: Expected QueueMetrics"
+
+        status = "healthy" if metrics.is_healthy else "degraded"
+        status_icon = self._status_emoji(status)
+
+        lines = [
+            f"Queue: {metrics.queue_name}",
+            f"├── Status: {status} {status_icon}",
+            f"├── Pending: {self._format_count(metrics.pending_count)}",
+            f"├── Running: {self._format_count(metrics.running_count)}",
+            f"├── Completed: {self._format_count(metrics.completed_count)}",
+            f"├── Failed: {self._format_count(metrics.failed_count)}",
+            f"├── Success Rate: {self._format_percentage(metrics.success_rate)}",
+            f"├── Avg Wait: {self._format_duration(metrics.avg_wait_time_ms)}",
+            f"├── Avg Exec: {self._format_duration(metrics.avg_execution_time_ms)}",
+            f"└── Throughput: {self._format_rate(metrics.throughput_per_second)}",
+        ]
+
+        return "\n".join(lines)
+
+    def format_summary_for_cli(
+        self,
+        queue_metrics: list[QueueMetrics],
+    ) -> str:
+        """Format queue summary for CLI display."""
+        if not queue_metrics:
+            return "No queues found."
+
+        lines = ["Queue Summary", "=" * 50]
+
+        # Add each queue
+        for i, qm in enumerate(queue_metrics):
+            status = "healthy" if qm.is_healthy else "degraded"
+            icon = self._status_emoji(status)
+
+            line = (
+                f"{icon} {qm.queue_name:20s} "
+                f"P:{qm.pending_count:4d} "
+                f"R:{qm.running_count:4d} "
+                f"C:{qm.completed_count:6d} "
+                f"F:{qm.failed_count:4d} "
+                f"({self._format_percentage(qm.success_rate)})"
+            )
+            lines.append(line)
+
+        # Add totals
+        lines.append("-" * 50)
+        total_pending = sum(qm.pending_count for qm in queue_metrics)
+        total_running = sum(qm.running_count for qm in queue_metrics)
+        total_completed = sum(qm.completed_count for qm in queue_metrics)
+        total_failed = sum(qm.failed_count for qm in queue_metrics)
+        total_throughput = sum(qm.throughput_per_second for qm in queue_metrics)
+
+        lines.append(
+            f"{'Total':25s} "
+            f"P:{total_pending:4d} "
+            f"R:{total_running:4d} "
+            f"C:{total_completed:6d} "
+            f"F:{total_failed:4d}"
+        )
+        lines.append(f"Total Throughput: {self._format_rate(total_throughput)}")
+
+        return "\n".join(lines)
+
+    def format_for_table(
+        self,
+        queue_metrics: list[QueueMetrics],
+    ) -> list[list[str]]:
+        """Format queue metrics as table rows.
+
+        Returns:
+            List of rows, first row is headers.
+        """
+        headers = [
+            "Queue", "Status", "Pending", "Running",
+            "Completed", "Failed", "Success %", "Throughput"
+        ]
+
+        rows = [headers]
+        for qm in queue_metrics:
+            status = "healthy" if qm.is_healthy else "degraded"
+            row = [
+                qm.queue_name,
+                status,
+                str(qm.pending_count),
+                str(qm.running_count),
+                str(qm.completed_count),
+                str(qm.failed_count),
+                f"{qm.success_rate * 100:.1f}%",
+                self._format_rate(qm.throughput_per_second),
+            ]
+            rows.append(row)
+
+        return rows

truthound/checkpoint/monitoring/views/task_view.py

@@ -0,0 +1,240 @@
+"""Task detail view.
+
+Renders task metrics for display in various formats.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from truthound.checkpoint.monitoring.protocols import (
+    QueueMetrics,
+    WorkerMetrics,
+    TaskMetrics,
+)
+from truthound.checkpoint.monitoring.views.base import BaseView
+
+
+class TaskDetailView(BaseView):
+    """View for rendering task details.
+
+    Example:
+        >>> view = TaskDetailView()
+        >>>
+        >>> # Render single task
+        >>> output = view.render(task_metrics)
+        >>>
+        >>> # Render for CLI
+        >>> print(view.format_for_cli(task_metrics))
+        Task: task-abc123
+        ├── Checkpoint: daily_validation
+        ├── State: running [>]
+        ├── Queue: default
+        ├── Worker: worker-1
+        ├── Wait Time: 150ms
+        └── Running For: 2.5s
+    """
+
+    def __init__(self, name: str = "task_detail") -> None:
+        """Initialize task detail view."""
+        super().__init__(name=name)
+
+    def render(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> dict[str, Any]:
+        """Render task metrics as dictionary."""
+        if not isinstance(metrics, TaskMetrics):
+            return {"error": "Expected TaskMetrics"}
+
+        return {
+            "task_id": metrics.task_id,
+            "checkpoint_name": metrics.checkpoint_name,
+            "state": metrics.state,
+            "queue_name": metrics.queue_name,
+            "worker_id": metrics.worker_id,
+            "timing": {
+                "submitted_at": metrics.submitted_at.isoformat(),
+                "started_at": metrics.started_at.isoformat() if metrics.started_at else None,
+                "completed_at": metrics.completed_at.isoformat() if metrics.completed_at else None,
+                "wait_time_ms": metrics.wait_time_ms,
+                "execution_time_ms": metrics.execution_time_ms,
+                "total_time_ms": metrics.total_time_ms,
+            },
+            "retries": metrics.retries,
+            "error": metrics.error,
+        }
+
+    def render_summary(
+        self,
+        queue_metrics: list[QueueMetrics],
+        worker_metrics: list[WorkerMetrics],
+    ) -> dict[str, Any]:
+        """Render task summary (placeholder - tasks are typically listed individually)."""
+        return {
+            "note": "Task view is typically used for individual tasks",
+            "queues": len(queue_metrics),
+            "workers": len(worker_metrics),
+        }
+
+    def render_task_list(
+        self,
+        tasks: list[TaskMetrics],
+    ) -> dict[str, Any]:
+        """Render a list of tasks."""
+        by_state: dict[str, list[dict]] = {}
+
+        for task in tasks:
+            rendered = self.render(task)
+            state = task.state
+            if state not in by_state:
+                by_state[state] = []
+            by_state[state].append(rendered)
+
+        return {
+            "tasks": [self.render(t) for t in tasks],
+            "by_state": by_state,
+            "totals": {
+                "total": len(tasks),
+                **{state: len(tasks) for state, tasks in by_state.items()},
+            },
+        }
+
+    def format_for_cli(
+        self,
+        metrics: QueueMetrics | WorkerMetrics | TaskMetrics,
+    ) -> str:
+        """Format task metrics for CLI display."""
+        if not isinstance(metrics, TaskMetrics):
+            return "Error: Expected TaskMetrics"
+
+        state_icon = self._status_emoji(metrics.state)
+
+        lines = [
+            f"Task: {metrics.task_id}",
+            f"├── Checkpoint: {metrics.checkpoint_name}",
+            f"├── State: {metrics.state} {state_icon}",
+            f"├── Queue: {metrics.queue_name}",
+        ]
+
+        if metrics.worker_id:
+            lines.append(f"├── Worker: {metrics.worker_id}")
+
+        lines.append(f"├── Submitted: {self._format_time(metrics.submitted_at)}")
+
+        if metrics.started_at:
+            lines.append(f"├── Started: {self._format_time(metrics.started_at)}")
+            if metrics.wait_time_ms:
+                lines.append(f"├── Wait Time: {self._format_duration(metrics.wait_time_ms)}")
+
+        if metrics.completed_at:
+            lines.append(f"├── Completed: {self._format_time(metrics.completed_at)}")
+            if metrics.execution_time_ms:
+                lines.append(f"├── Exec Time: {self._format_duration(metrics.execution_time_ms)}")
+        elif metrics.started_at:
+            running_for = (datetime.now() - metrics.started_at).total_seconds() * 1000
+            lines.append(f"├── Running For: {self._format_duration(running_for)}")
+
+        if metrics.retries > 0:
+            lines.append(f"├── Retries: {metrics.retries}")
+
+        if metrics.error:
+            lines.append(f"└── Error: {metrics.error[:50]}...")
+        else:
+            # Remove the last ├── and replace with └──
+            if lines:
+                lines[-1] = lines[-1].replace("├──", "└──")
+
+        return "\n".join(lines)
+
+    def _format_time(self, dt: datetime) -> str:
+        """Format datetime for display."""
+        return dt.strftime("%H:%M:%S")
+
+    def format_task_list_for_cli(
+        self,
+        tasks: list[TaskMetrics],
+        show_completed: bool = False,
+    ) -> str:
+        """Format task list for CLI display."""
+        if not tasks:
+            return "No tasks found."
+
+        # Filter out completed tasks unless requested
+        if not show_completed:
+            tasks = [t for t in tasks if t.state not in ("succeeded", "failed", "cancelled")]
+
+        if not tasks:
+            return "No active tasks."
+
+        lines = ["Active Tasks", "=" * 70]
+
+        # Group by state
+        by_state: dict[str, list[TaskMetrics]] = {}
+        for task in tasks:
+            if task.state not in by_state:
+                by_state[task.state] = []
+            by_state[task.state].append(task)
+
+        for state, state_tasks in by_state.items():
+            icon = self._status_emoji(state)
+            lines.append(f"\n{icon} {state.upper()} ({len(state_tasks)})")
+            lines.append("-" * 40)
+
+            for task in state_tasks[:10]:  # Limit to 10 per state
+                age = self._format_age(task)
+                line = (
+                    f"  {task.task_id[:16]:16s} "
+                    f"{task.checkpoint_name[:20]:20s} "
+                    f"{task.queue_name:10s} "
+                    f"{age:8s}"
+                )
+                lines.append(line)
+
+            if len(state_tasks) > 10:
+                lines.append(f"  ... and {len(state_tasks) - 10} more")
+
+        return "\n".join(lines)
+
+    def _format_age(self, task: TaskMetrics) -> str:
+        """Format task age."""
+        if task.completed_at:
+            return "done"
+
+        if task.started_at:
+            elapsed = (datetime.now() - task.started_at).total_seconds()
+            return self._format_duration(elapsed * 1000)
+
+        elapsed = (datetime.now() - task.submitted_at).total_seconds()
+        return f"wait {self._format_duration(elapsed * 1000)}"
+
+    def format_for_table(
+        self,
+        tasks: list[TaskMetrics],
+    ) -> list[list[str]]:
+        """Format task list as table rows.
+
+        Returns:
+            List of rows, first row is headers.
+        """
+        headers = [
+            "Task ID", "Checkpoint", "State", "Queue",
+            "Worker", "Wait", "Exec", "Retries"
+        ]
+
+        rows = [headers]
+        for task in tasks:
+            row = [
+                task.task_id[:16],
+                task.checkpoint_name[:20],
+                task.state,
+                task.queue_name,
+                task.worker_id or "-",
+                self._format_duration(task.wait_time_ms or 0),
+                self._format_duration(task.execution_time_ms or 0),
+                str(task.retries),
+            ]
+            rows.append(row)
+
+        return rows