kubectl-mcp-server 1.15.0__py3-none-any.whl → 1.17.0__py3-none-any.whl

kubectl_mcp_tool/observability/metrics.py

@@ -0,0 +1,223 @@
+"""
+Prometheus metrics for kubectl-mcp-server.
+
+Provides standard Prometheus format metrics for production monitoring.
+
+Metrics exposed:
+- mcp_tool_calls_total: Counter of tool invocations (labels: tool_name, status)
+- mcp_tool_errors_total: Counter of tool errors (labels: tool_name, error_type)
+- mcp_tool_duration_seconds: Histogram of tool call durations (labels: tool_name)
+- mcp_http_requests_total: Counter of HTTP requests (labels: endpoint, method, status)
+- mcp_server_info: Gauge with server metadata
+
+Requires: prometheus-client>=0.19.0 (optional dependency)
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Check if prometheus_client is available
+_prometheus_available = False
+_REGISTRY = None
+_tool_calls_counter = None
+_tool_errors_counter = None
+_tool_duration_histogram = None
+_http_requests_counter = None
+_server_info_gauge = None
+
+try:
+    from prometheus_client import (
+        Counter,
+        Histogram,
+        Gauge,
+        CollectorRegistry,
+        generate_latest,
+        CONTENT_TYPE_LATEST,
+    )
+    _prometheus_available = True
+
+    # Create a custom registry to avoid conflicts
+    _REGISTRY = CollectorRegistry()
+
+    # Tool call counter
+    _tool_calls_counter = Counter(
+        "mcp_tool_calls_total",
+        "Total number of MCP tool calls",
+        ["tool_name", "status"],
+        registry=_REGISTRY,
+    )
+
+    # Tool error counter
+    _tool_errors_counter = Counter(
+        "mcp_tool_errors_total",
+        "Total number of MCP tool errors",
+        ["tool_name", "error_type"],
+        registry=_REGISTRY,
+    )
+
+    # Tool duration histogram
+    # Buckets optimized for typical k8s API call durations
+    _tool_duration_histogram = Histogram(
+        "mcp_tool_duration_seconds",
+        "Duration of MCP tool calls in seconds",
+        ["tool_name"],
+        buckets=(0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0),
+        registry=_REGISTRY,
+    )
+
+    # HTTP requests counter
+    _http_requests_counter = Counter(
+        "mcp_http_requests_total",
+        "Total number of HTTP requests",
+        ["endpoint", "method", "status"],
+        registry=_REGISTRY,
+    )
+
+    # Server info gauge (version, features)
+    _server_info_gauge = Gauge(
+        "mcp_server_info",
+        "MCP server information",
+        ["version", "transport"],
+        registry=_REGISTRY,
+    )
+
+    logger.debug("Prometheus metrics initialized successfully")
+
+except ImportError:
+    logger.debug(
+        "prometheus_client not installed. Prometheus metrics disabled. "
+        "Install with: pip install kubectl-mcp-server[observability]"
+    )
+
+
+def is_prometheus_available() -> bool:
+    """Check if Prometheus client is available."""
+    return _prometheus_available
+
+
+def record_tool_call_metric(
+    tool_name: str,
+    success: bool = True,
+    duration: float = 0.0
+) -> None:
+    """
+    Record a tool call in Prometheus metrics.
+
+    Args:
+        tool_name: Name of the tool called
+        success: Whether the call succeeded
+        duration: Call duration in seconds
+    """
+    if not _prometheus_available:
+        return
+
+    status = "success" if success else "error"
+    _tool_calls_counter.labels(tool_name=tool_name, status=status).inc()
+
+    if duration > 0:
+        _tool_duration_histogram.labels(tool_name=tool_name).observe(duration)
+
+
+def record_tool_error_metric(
+    tool_name: str,
+    error_type: str = "unknown"
+) -> None:
+    """
+    Record a tool error in Prometheus metrics.
+
+    Args:
+        tool_name: Name of the tool that errored
+        error_type: Type/category of error (e.g., "timeout", "validation", "k8s_api")
+    """
+    if not _prometheus_available:
+        return
+
+    _tool_errors_counter.labels(
+        tool_name=tool_name,
+        error_type=error_type
+    ).inc()
+
+
+def record_tool_duration_metric(tool_name: str, duration: float) -> None:
+    """
+    Record tool duration in Prometheus histogram.
+
+    Args:
+        tool_name: Name of the tool
+        duration: Duration in seconds
+    """
+    if not _prometheus_available:
+        return
+
+    _tool_duration_histogram.labels(tool_name=tool_name).observe(duration)
+
+
+def record_http_request_metric(
+    endpoint: str,
+    method: str,
+    status: int = 200
+) -> None:
+    """
+    Record an HTTP request in Prometheus metrics.
+
+    Args:
+        endpoint: Request endpoint path
+        method: HTTP method
+        status: HTTP status code
+    """
+    if not _prometheus_available:
+        return
+
+    _http_requests_counter.labels(
+        endpoint=endpoint,
+        method=method,
+        status=str(status)
+    ).inc()
+
+
+def set_server_info(version: str, transport: str) -> None:
+    """
+    Set server info in Prometheus gauge.
+
+    Args:
+        version: Server version
+        transport: Transport type (stdio, sse, http)
+    """
+    if not _prometheus_available:
+        return
+
+    _server_info_gauge.labels(version=version, transport=transport).set(1)
+
+
+def get_metrics() -> str:
+    """
+    Get metrics in Prometheus text format.
+
+    Returns:
+        Prometheus metrics as text, or error message if unavailable
+    """
+    if not _prometheus_available:
+        return (
+            "# Prometheus metrics not available.\n"
+            "# Install with: pip install kubectl-mcp-server[observability]\n"
+        )
+
+    try:
+        return generate_latest(_REGISTRY).decode("utf-8")
+    except Exception as e:
+        logger.error(f"Error generating Prometheus metrics: {e}")
+        return f"# Error generating metrics: {e}\n"
+
+
+def get_metrics_content_type() -> str:
+    """
+    Get the content type for Prometheus metrics.
+
+    Returns:
+        Prometheus content type string
+    """
+    if not _prometheus_available:
+        return "text/plain; charset=utf-8"
+    return CONTENT_TYPE_LATEST

kubectl_mcp_tool/observability/stats.py

@@ -0,0 +1,255 @@
+"""
+Runtime statistics collection for kubectl-mcp-server.
+
+Provides a singleton StatsCollector that tracks:
+- tool_calls_total: Total number of tool invocations
+- tool_errors_total: Total number of tool errors
+- tool_calls_by_name: Breakdown of calls by tool name
+- http_requests_total: Total HTTP requests (for SSE/HTTP transports)
+- uptime: Server uptime in seconds
+"""
+
+import time
+import threading
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional
+
+
+@dataclass
+class ToolStats:
+    """Statistics for a single tool."""
+    calls: int = 0
+    errors: int = 0
+    total_duration: float = 0.0
+    last_call_time: Optional[float] = None
+    last_error_time: Optional[float] = None
+
+
+class StatsCollector:
+    """
+    Singleton class for collecting runtime statistics.
+
+    Thread-safe statistics collection for production observability.
+
+    Usage:
+        stats = get_stats_collector()
+        stats.record_tool_call("get_pods", success=True, duration=0.5)
+
+        # Get current stats
+        data = stats.get_stats()
+    """
+
+    _instance: Optional["StatsCollector"] = None
+    _lock = threading.Lock()
+
+    def __new__(cls) -> "StatsCollector":
+        """Ensure singleton pattern."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        """Initialize the stats collector (only once)."""
+        if self._initialized:
+            return
+
+        self._stats_lock = threading.Lock()
+        self._start_time = time.time()
+
+        # Core counters
+        self._tool_calls_total = 0
+        self._tool_errors_total = 0
+        self._http_requests_total = 0
+
+        # Per-tool statistics
+        self._tool_stats: Dict[str, ToolStats] = defaultdict(ToolStats)
+
+        # HTTP request breakdown
+        self._http_requests_by_endpoint: Dict[str, int] = defaultdict(int)
+        self._http_requests_by_method: Dict[str, int] = defaultdict(int)
+
+        self._initialized = True
+
+    def record_tool_call(
+        self,
+        tool_name: str,
+        success: bool = True,
+        duration: float = 0.0
+    ) -> None:
+        """
+        Record a tool call.
+
+        Args:
+            tool_name: Name of the tool that was called
+            success: Whether the call succeeded
+            duration: Call duration in seconds
+        """
+        with self._stats_lock:
+            self._tool_calls_total += 1
+
+            stats = self._tool_stats[tool_name]
+            stats.calls += 1
+            stats.total_duration += duration
+            stats.last_call_time = time.time()
+
+            if not success:
+                self._tool_errors_total += 1
+                stats.errors += 1
+                stats.last_error_time = time.time()
+
+    def record_tool_error(self, tool_name: str) -> None:
+        """
+        Record a tool error (shorthand for failed call).
+
+        Args:
+            tool_name: Name of the tool that errored
+        """
+        self.record_tool_call(tool_name, success=False)
+
+    def record_http_request(
+        self,
+        endpoint: str = "/",
+        method: str = "POST"
+    ) -> None:
+        """
+        Record an HTTP request.
+
+        Args:
+            endpoint: Request endpoint path
+            method: HTTP method (GET, POST, etc.)
+        """
+        with self._stats_lock:
+            self._http_requests_total += 1
+            self._http_requests_by_endpoint[endpoint] += 1
+            self._http_requests_by_method[method] += 1
+
+    @property
+    def uptime(self) -> float:
+        """Get server uptime in seconds."""
+        return time.time() - self._start_time
+
+    @property
+    def tool_calls_total(self) -> int:
+        """Get total tool calls."""
+        with self._stats_lock:
+            return self._tool_calls_total
+
+    @property
+    def tool_errors_total(self) -> int:
+        """Get total tool errors."""
+        with self._stats_lock:
+            return self._tool_errors_total
+
+    @property
+    def http_requests_total(self) -> int:
+        """Get total HTTP requests."""
+        with self._stats_lock:
+            return self._http_requests_total
+
+    def get_tool_stats(self, tool_name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get statistics for a specific tool.
+
+        Args:
+            tool_name: Name of the tool
+
+        Returns:
+            Dictionary with tool statistics or None if not found
+        """
+        with self._stats_lock:
+            if tool_name not in self._tool_stats:
+                return None
+
+            stats = self._tool_stats[tool_name]
+            avg_duration = (
+                stats.total_duration / stats.calls
+                if stats.calls > 0 else 0.0
+            )
+
+            return {
+                "calls": stats.calls,
+                "errors": stats.errors,
+                "error_rate": stats.errors / stats.calls if stats.calls > 0 else 0.0,
+                "total_duration_seconds": stats.total_duration,
+                "average_duration_seconds": avg_duration,
+                "last_call_time": stats.last_call_time,
+                "last_error_time": stats.last_error_time,
+            }
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get all statistics as a JSON-serializable dictionary.
+
+        Returns:
+            Dictionary containing all collected statistics
+        """
+        with self._stats_lock:
+            # Calculate tool-level stats
+            tool_stats_dict = {}
+            for tool_name, stats in self._tool_stats.items():
+                avg_duration = (
+                    stats.total_duration / stats.calls
+                    if stats.calls > 0 else 0.0
+                )
+                tool_stats_dict[tool_name] = {
+                    "calls": stats.calls,
+                    "errors": stats.errors,
+                    "error_rate": stats.errors / stats.calls if stats.calls > 0 else 0.0,
+                    "average_duration_seconds": round(avg_duration, 4),
+                }
+
+            # Sort tools by call count (descending)
+            sorted_tools = dict(
+                sorted(
+                    tool_stats_dict.items(),
+                    key=lambda x: x[1]["calls"],
+                    reverse=True
+                )
+            )
+
+            return {
+                "uptime_seconds": round(self.uptime, 2),
+                "tool_calls_total": self._tool_calls_total,
+                "tool_errors_total": self._tool_errors_total,
+                "tool_error_rate": (
+                    self._tool_errors_total / self._tool_calls_total
+                    if self._tool_calls_total > 0 else 0.0
+                ),
+                "http_requests_total": self._http_requests_total,
+                "http_requests_by_endpoint": dict(self._http_requests_by_endpoint),
+                "http_requests_by_method": dict(self._http_requests_by_method),
+                "tool_calls_by_name": sorted_tools,
+                "unique_tools_called": len(self._tool_stats),
+            }
+
+    def reset(self) -> None:
+        """Reset all statistics (useful for testing)."""
+        with self._stats_lock:
+            self._start_time = time.time()
+            self._tool_calls_total = 0
+            self._tool_errors_total = 0
+            self._http_requests_total = 0
+            self._tool_stats.clear()
+            self._http_requests_by_endpoint.clear()
+            self._http_requests_by_method.clear()
+
+
+# Module-level singleton accessor
+_stats_collector: Optional[StatsCollector] = None
+
+
+def get_stats_collector() -> StatsCollector:
+    """
+    Get the singleton StatsCollector instance.
+
+    Returns:
+        The global StatsCollector instance
+    """
+    global _stats_collector
+    if _stats_collector is None:
+        _stats_collector = StatsCollector()
+    return _stats_collector