Add server operating metrics (#422)

* Add server-side metrics reporting

---------

Co-authored-by: Joakim Sørensen <[email protected]>

Author: bbangert

pyproject.toml

@@ -52,7 +52,6 @@ target-version = "py311"
 ignore = [
   "A005",     # https://docs.astral.sh/ruff/rules/stdlib-module-shadowing/
   "ASYNC110", # https://docs.astral.sh/ruff/rules/async-busy-wait/
-  "ANN101",   # https://docs.astral.sh/ruff/rules/missing-type-self/
   "EM101",    # https://docs.astral.sh/ruff/rules/raw-string-in-exception/
   "EM102",    # https://docs.astral.sh/ruff/rules/f-string-in-exception/
   "FBT",      # https://docs.astral.sh/ruff/rules/#flake8-boolean-trap-fbt
@@ -61,8 +60,9 @@ ignore = [
   "PERF203",  # https://docs.astral.sh/ruff/rules/try-except-in-loop/
   "S101",     # https://docs.astral.sh/ruff/rules/assert/
   "S104",     # https://docs.astral.sh/ruff/rules/hardcoded-bind-all-interfaces/
-  "TCH001",   # https://docs.astral.sh/ruff/rules/typing-only-first-party-import/
-  "TCH003",   # https://docs.astral.sh/ruff/rules/typing-only-standard-library-import/
+  "TC001",    # https://docs.astral.sh/ruff/rules/typing-only-first-party-import/
+  "TC003",    # https://docs.astral.sh/ruff/rules/typing-only-standard-library-import/
+  "TC006",    # https://docs.astral.sh/ruff/rules/runtime-cast-value/
   "TID252",   # https://docs.astral.sh/ruff/rules/relative-imports/
   "TRY003",   # https://docs.astral.sh/ruff/rules/raise-vanilla-args/
   "TRY301",   # https://docs.astral.sh/ruff/rules/raise-within-try/
@@ -104,6 +104,7 @@ zip-safe = false
 [tool.setuptools.packages.find]
 include = [
   "snitun",
+  "snitun.metrics",
   "snitun.server",
   "snitun.client",
   "snitun.multiplexer",

snitun/metrics/__init__.py

@@ -0,0 +1,10 @@
+"""SniTun metrics collection system."""
+
+from .base import MetricsCollector
+from .factory import MetricsFactory, create_noop_metrics_collector
+
+__all__ = [
+    "MetricsCollector",
+    "MetricsFactory",
+    "create_noop_metrics_collector",
+]

snitun/metrics/base.py

@@ -0,0 +1,71 @@
+"""Base metrics collector interface."""
+
+from abc import ABC, abstractmethod
+
+
+class MetricsCollector(ABC):
+    """Abstract base class for metrics collection."""
+
+    @abstractmethod
+    def gauge(
+        self,
+        name: str,
+        value: float,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Set a gauge metric to a specific value.
+
+        Args:
+            name: Metric name (e.g., 'snitun.peer.connections')
+            value: Current value
+            tags: Optional tags for the metric
+        """
+
+    @abstractmethod
+    def increment(
+        self,
+        name: str,
+        value: float = 1,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Increment a counter metric.
+
+        Args:
+            name: Metric name (e.g., 'snitun.connections.new')
+            value: Amount to increment (default: 1)
+            tags: Optional tags for the metric
+        """
+
+    @abstractmethod
+    def histogram(
+        self,
+        name: str,
+        value: float,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Record a value in a histogram.
+
+        Args:
+            name: Metric name (e.g., 'snitun.connection.duration')
+            value: Value to record
+            tags: Optional tags for the metric
+        """
+
+    @abstractmethod
+    def timing(
+        self,
+        name: str,
+        value: float,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Record a timing value.
+
+        Args:
+            name: Metric name (e.g., 'snitun.handshake.time')
+            value: Time in milliseconds
+            tags: Optional tags for the metric
+        """

snitun/metrics/factory.py

@@ -0,0 +1,19 @@
+"""Factory functions for creating metrics collectors."""
+
+from collections.abc import Callable
+
+from .base import MetricsCollector
+from .noop import NoOpMetricsCollector
+
+# Type alias for metrics factory function
+MetricsFactory = Callable[[], MetricsCollector]
+
+
+def create_noop_metrics_collector() -> MetricsCollector:
+    """
+    Create a no-op metrics collector for zero overhead.
+
+    Returns:
+        NoOpMetricsCollector instance that does nothing.
+    """
+    return NoOpMetricsCollector()

snitun/metrics/noop.py

@@ -0,0 +1,39 @@
+"""No-operation metrics collector for zero overhead."""
+
+from .base import MetricsCollector
+
+
+class NoOpMetricsCollector(MetricsCollector):
+    """No-operation metrics collector with zero overhead."""
+
+    def gauge(
+        self,
+        name: str,
+        value: float,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """No-op gauge implementation."""
+
+    def increment(
+        self,
+        name: str,
+        value: float = 1,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """No-op increment implementation."""
+
+    def histogram(
+        self,
+        name: str,
+        value: float,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """No-op histogram implementation."""
+
+    def timing(
+        self,
+        name: str,
+        value: float,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """No-op timing implementation."""

snitun/server/listener_peer.py

@@ -7,6 +7,7 @@
 import logging
 
 from ..exceptions import SniTunChallengeError, SniTunInvalidPeer
+from ..metrics.base import MetricsCollector
 from ..utils.asyncio import asyncio_timeout
 from .peer_manager import PeerManager
 
@@ -23,11 +24,13 @@ def __init__(
         peer_manager: PeerManager,
         host: str | None = None,
         port: int | None = None,
+        metrics: MetricsCollector | None = None,
     ) -> None:
         """Initialize SNI Proxy interface."""
         self._peer_manager = peer_manager
         self._host = host
         self._port = port or 8080
+        self._metrics = metrics
         self._server: asyncio.Server | None = None
 
     async def start(self) -> None:
@@ -69,11 +72,26 @@ async def handle_connection(
             # Connection closed before data received
             if not fernet_data:
                 return
+
+            # Track authentication attempt
+            if self._metrics:
+                self._metrics.increment(
+                    "snitun.auth.attempts",
+                    tags={"result": "started"},
+                )
+
             peer = self._peer_manager.create_peer(fernet_data)
 
             # Start multiplexer
             await peer.init_multiplexer_challenge(reader, writer)
 
+            # Authentication successful
+            if self._metrics:
+                self._metrics.increment(
+                    "snitun.auth.attempts",
+                    tags={"result": "success"},
+                )
+
             self._peer_manager.add_peer(peer)
             while peer.is_connected:
                 try:
@@ -85,9 +103,19 @@ async def handle_connection(
 
         except SniTunInvalidPeer:
             _LOGGER.debug("Close because invalid fernet data")
+            if self._metrics:
+                self._metrics.increment(
+                    "snitun.auth.failures",
+                    tags={"reason": "invalid_token"},
+                )
 
         except SniTunChallengeError:
             _LOGGER.debug("Close because challenge was wrong")
+            if self._metrics:
+                self._metrics.increment(
+                    "snitun.auth.failures",
+                    tags={"reason": "challenge_failed"},
+                )
 
         finally:
             if peer:

snitun/server/peer.py

@@ -77,6 +77,11 @@ def is_ready(self) -> bool:
             return False
         return self.multiplexer.is_connected
 
+    @property
+    def protocol_version(self) -> int:
+        """Return the protocol version."""
+        return self._protocol_version
+
     async def init_multiplexer_challenge(
         self,
         reader: asyncio.StreamReader,

snitun/server/peer_manager.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Callable, ValuesView
 from datetime import UTC, datetime
 from enum import Enum
 import json
@@ -47,6 +47,10 @@ def connections(self) -> int:
         """Return count of connected devices."""
         return len(self._peers)
 
+    def iter_peers(self) -> ValuesView[Peer]:
+        """Iterate over all peers."""
+        return self._peers.values()
+
     def create_peer(self, fernet_data: bytes) -> Peer:
         """Create a new peer from crypt config."""
         try:

snitun/server/run.py

@@ -17,6 +17,7 @@
 from typing import Any
 
 from ..exceptions import ParseSNIIncompleteError
+from ..metrics import MetricsCollector, MetricsFactory, create_noop_metrics_collector
 from ..utils.asyncio import asyncio_timeout
 from ..utils.server import MAX_BUFFER_SIZE, MAX_READ_SIZE
 from .listener_peer import PeerListener
@@ -198,6 +199,8 @@ def __init__(
         port: int | None = None,
         worker_size: int | None = None,
         throttling: int | None = None,
+        metrics_factory: MetricsFactory | None = None,
+        metrics_interval: int = 60,
     ) -> None:
         """Initialize SniTun Server."""
         super().__init__()
@@ -209,6 +212,9 @@ def __init__(
         self._worker_size: int = worker_size or (cpu_count() * 2)
         self._workers: list[ServerWorker] = []
         self._running: bool = False
+        self._metrics_factory = metrics_factory or create_noop_metrics_collector
+        self._metrics_interval = metrics_interval
+        self._metrics: MetricsCollector | None = None
 
         # TCP server
         self._server: socket.socket | None = None
@@ -221,10 +227,17 @@ def peer_counter(self) -> int:
 
     def start(self) -> None:
         """Run server."""
+        self._metrics = self._metrics_factory()
+
         # Init first all worker, we don't want the epoll on the childs
         _LOGGER.info("Run SniTun with %d worker", self._worker_size)
         for _ in range(self._worker_size):
-            worker = ServerWorker(self._fernet_keys, throttling=self._throttling)
+            worker = ServerWorker(
+                self._fernet_keys,
+                throttling=self._throttling,
+                metrics_factory=self._metrics_factory,
+                metrics_interval=self._metrics_interval,
+            )
             worker.start()
             self._workers.append(worker)