update

Author: Yunnglin

src/twinkle/server/gateway/server.py

@@ -13,6 +13,7 @@
 from typing import Any
 
 import twinkle_client.types as types
+from twinkle.server.utils.metrics import create_metrics_middleware
 from twinkle.server.utils.state import get_server_state
 from twinkle.server.utils.validation import verify_request_token
 from twinkle.utils.logger import get_logger
@@ -93,7 +94,6 @@ def build_server_app(deploy_options: dict[str, Any],
     async def verify_token(request: Request, call_next):
         return await verify_request_token(request=request, call_next=call_next)
 
-    from twinkle.server.utils.metrics import create_metrics_middleware
     app.middleware('http')(create_metrics_middleware('Gateway'))
 
     def get_self() -> GatewayServer:

src/twinkle/server/model/app.py

@@ -15,6 +15,7 @@
 import twinkle
 from twinkle import DeviceGroup, DeviceMesh
 from twinkle.server.utils.lifecycle import AdapterManagerMixin
+from twinkle.server.utils.metrics import create_metrics_middleware
 from twinkle.server.utils.state import ServerStateProxy, get_server_state
 from twinkle.server.utils.task_queue import TaskQueueConfig, TaskQueueMixin
 from twinkle.server.utils.validation import get_token_from_request, verify_request_token
@@ -164,7 +165,6 @@ def build_model_app(model_id: str,
     async def verify_token(request: Request, call_next):
         return await verify_request_token(request=request, call_next=call_next)
 
-    from twinkle.server.utils.metrics import create_metrics_middleware
     app.middleware('http')(create_metrics_middleware('Model'))
 
     def get_self() -> ModelManagement:

src/twinkle/server/processor/app.py

@@ -21,6 +21,7 @@
 import twinkle
 from twinkle import DeviceGroup, DeviceMesh, get_logger
 from twinkle.server.utils.lifecycle import ProcessorManagerMixin
+from twinkle.server.utils.metrics import create_metrics_middleware
 from twinkle.server.utils.state import ServerStateProxy, get_server_state
 from twinkle.server.utils.validation import verify_request_token
 from .twinkle_handlers import _register_processor_routes
@@ -124,7 +125,6 @@ def build_processor_app(ncpu_proc_per_node: int,
     async def verify_token(request: Request, call_next):
         return await verify_request_token(request=request, call_next=call_next)
 
-    from twinkle.server.utils.metrics import create_metrics_middleware
     app.middleware('http')(create_metrics_middleware('Processor'))
 
     def get_self() -> ProcessorManagement:

src/twinkle/server/sampler/app.py

@@ -13,6 +13,7 @@
 
 import twinkle
 from twinkle import DeviceGroup, DeviceMesh
+from twinkle.server.utils.metrics import create_metrics_middleware
 from twinkle.server.utils.state import ServerStateProxy, get_server_state
 from twinkle.server.utils.task_queue import TaskQueueConfig, TaskQueueMixin
 from twinkle.server.utils.validation import get_token_from_request, verify_request_token
@@ -135,7 +136,6 @@ def build_sampler_app(model_id: str,
     async def verify_token(request: Request, call_next):
         return await verify_request_token(request=request, call_next=call_next)
 
-    from twinkle.server.utils.metrics import create_metrics_middleware
     app.middleware('http')(create_metrics_middleware('Sampler'))
 
     def get_self() -> SamplerManagement:

src/twinkle/server/utils/metrics.py

@@ -17,7 +17,7 @@
 from __future__ import annotations
 
 import time
-from collections import namedtuple
+from pydantic import BaseModel
 from ray.util.metrics import Counter, Gauge, Histogram
 from typing import Any, Callable
 
@@ -47,33 +47,57 @@
 # ---------------------------------------------------------------------------
 # Lazy caches – populated on first call per deployment / globally
 # ---------------------------------------------------------------------------
-_task_metrics_cache: dict[str, Any] = {}
-_resource_metrics_cache: dict[str, Any] | None = None
-_request_metrics_cache: dict[str, Any] = {}
+_task_metrics_cache: dict[str, TaskMetrics] = {}
+_resource_metrics_cache: ResourceMetrics | None = None
+_request_metrics_cache: dict[str, _RequestMetrics] = {}
 
 # ---------------------------------------------------------------------------
-# Named tuples for structured metric access
+# Pydantic models for structured metric access
 # ---------------------------------------------------------------------------
-TaskMetrics = namedtuple('TaskMetrics', [
-    'queue_depth',
-    'tasks_total',
-    'execution_seconds',
-    'queue_wait_seconds',
-    'rate_limit_rejections',
-    'rate_limiter_active_tokens',
-])
-
-ResourceMetrics = namedtuple('ResourceMetrics', [
-    'active_sessions',
-    'active_models',
-    'active_sampling_sessions',
-    'active_futures',
-])
-
-_RequestMetrics = namedtuple('_RequestMetrics', [
-    'requests_total',
-    'request_duration_seconds',
-])
+
+
+class TaskMetrics(BaseModel):
+    """Task queue metrics container.
+
+    Attributes:
+        queue_depth: Current number of queued tasks.
+        tasks_total: Total task completions.
+        execution_seconds: Pure task execution time in seconds.
+        queue_wait_seconds: Time from enqueue to execution start.
+        rate_limit_rejections: Total rate-limit rejections.
+        rate_limiter_active_tokens: Tokens tracked by rate limiter.
+    """
+
+    queue_depth: Gauge
+    tasks_total: Counter
+    execution_seconds: Histogram
+    queue_wait_seconds: Histogram
+    rate_limit_rejections: Counter
+    rate_limiter_active_tokens: Gauge
+
+
+class ResourceMetrics(BaseModel):
+    """Resource gauge metrics container.
+
+    Attributes:
+        active_sessions: Current active session count.
+        active_models: Current registered model count.
+        active_sampling_sessions: Current sampling session count.
+        active_futures: Current future/request count.
+    """
+
+    active_sessions: Gauge
+    active_models: Gauge
+    active_sampling_sessions: Gauge
+    active_futures: Gauge
+
+
+class _RequestMetrics(BaseModel):
+    """HTTP request metrics container (internal)."""
+
+    requests_total: Counter
+    request_duration_seconds: Histogram
+
 
 # ---------------------------------------------------------------------------
 # A.  Request-level metrics  (FastAPI middleware)
@@ -146,7 +170,7 @@ async def metrics_middleware(request: Any, call_next: Callable) -> Any:
 def get_task_metrics(deployment: str) -> TaskMetrics:
     """Return (or create) per-deployment task-queue metrics.
 
-    Returns a :class:`TaskMetrics` namedtuple with:
+    Returns a :class:`TaskMetrics` Pydantic model with:
 
     - ``queue_depth``                – Gauge
     - ``tasks_total``                – Counter
@@ -204,7 +228,7 @@ def get_task_metrics(deployment: str) -> TaskMetrics:
 def get_resource_metrics() -> ResourceMetrics:
     """Return (or create) global resource gauge metrics.
 
-    Returns a :class:`ResourceMetrics` namedtuple with:
+    Returns a :class:`ResourceMetrics` Pydantic model with:
 
     - ``active_sessions``           – Gauge
     - ``active_models``             – Gauge