ccproxy-api 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

ccproxy/observability/metrics.py

@@ -205,6 +205,62 @@ class PrometheusMetrics:
             registry=self.registry,
         )
 
+        # Claude SDK Pool metrics
+        self.pool_clients_total = Gauge(
+            f"{self.namespace}_pool_clients_total",
+            "Total number of clients in the pool",
+            registry=self.registry,
+        )
+
+        self.pool_clients_available = Gauge(
+            f"{self.namespace}_pool_clients_available",
+            "Number of available clients in the pool",
+            registry=self.registry,
+        )
+
+        self.pool_clients_active = Gauge(
+            f"{self.namespace}_pool_clients_active",
+            "Number of active clients currently processing requests",
+            registry=self.registry,
+        )
+
+        self.pool_connections_created_total = Counter(
+            f"{self.namespace}_pool_connections_created_total",
+            "Total number of pool connections created",
+            registry=self.registry,
+        )
+
+        self.pool_connections_closed_total = Counter(
+            f"{self.namespace}_pool_connections_closed_total",
+            "Total number of pool connections closed",
+            registry=self.registry,
+        )
+
+        self.pool_acquisitions_total = Counter(
+            f"{self.namespace}_pool_acquisitions_total",
+            "Total number of client acquisitions from pool",
+            registry=self.registry,
+        )
+
+        self.pool_releases_total = Counter(
+            f"{self.namespace}_pool_releases_total",
+            "Total number of client releases to pool",
+            registry=self.registry,
+        )
+
+        self.pool_health_check_failures_total = Counter(
+            f"{self.namespace}_pool_health_check_failures_total",
+            "Total number of pool health check failures",
+            registry=self.registry,
+        )
+
+        self.pool_acquisition_duration = Histogram(
+            f"{self.namespace}_pool_acquisition_duration_seconds",
+            "Time taken to acquire a client from the pool",
+            buckets=[0.001, 0.005, 0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0],
+            registry=self.registry,
+        )
+
         # Set initial system info
         try:
             from ccproxy import __version__
@@ -468,6 +524,101 @@ class PrometheusMetrics:
             and self._pushgateway_client.is_enabled()
         )
 
+    # Claude SDK Pool metrics methods
+
+    def update_pool_gauges(
+        self,
+        total_clients: int,
+        available_clients: int,
+        active_clients: int,
+    ) -> None:
+        """
+        Update pool gauge metrics (current state).
+
+        Args:
+            total_clients: Total number of clients in pool
+            available_clients: Number of available clients
+            active_clients: Number of active clients
+        """
+        if not self._enabled:
+            return
+
+        # Update gauges
+        self.pool_clients_total.set(total_clients)
+        self.pool_clients_available.set(available_clients)
+        self.pool_clients_active.set(active_clients)
+
+        # Note: Counters are managed directly by the pool operations
+        # This method only updates the current gauges
+
+    def record_pool_acquisition_time(self, duration_seconds: float) -> None:
+        """
+        Record the time taken to acquire a client from the pool.
+
+        Args:
+            duration_seconds: Time in seconds to acquire client
+        """
+        if not self._enabled:
+            return
+
+        self.pool_acquisition_duration.observe(duration_seconds)
+
+    def inc_pool_connections_created(self) -> None:
+        """Increment the pool connections created counter."""
+        if not self._enabled:
+            return
+
+        self.pool_connections_created_total.inc()
+
+    def inc_pool_connections_closed(self) -> None:
+        """Increment the pool connections closed counter."""
+        if not self._enabled:
+            return
+
+        self.pool_connections_closed_total.inc()
+
+    def inc_pool_acquisitions(self) -> None:
+        """Increment the pool acquisitions counter."""
+        if not self._enabled:
+            return
+
+        self.pool_acquisitions_total.inc()
+
+    def inc_pool_releases(self) -> None:
+        """Increment the pool releases counter."""
+        if not self._enabled:
+            return
+
+        self.pool_releases_total.inc()
+
+    def inc_pool_health_check_failures(self) -> None:
+        """Increment the pool health check failures counter."""
+        if not self._enabled:
+            return
+
+        self.pool_health_check_failures_total.inc()
+
+    def set_pool_clients_total(self, count: int) -> None:
+        """Set the total number of clients in the pool."""
+        if not self._enabled:
+            return
+
+        self.pool_clients_total.set(count)
+
+    def set_pool_clients_available(self, count: int) -> None:
+        """Set the number of available clients in the pool."""
+        if not self._enabled:
+            return
+
+        self.pool_clients_available.set(count)
+
+    def set_pool_clients_active(self, count: int) -> None:
+        """Set the number of active clients in the pool."""
+        if not self._enabled:
+            return
+
+        self.pool_clients_active.set(count)
+
 
 # Global metrics instance
 _global_metrics: PrometheusMetrics | None = None

ccproxy/observability/storage/duckdb_simple.py

@@ -60,6 +60,18 @@ class AccessLogPayload(TypedDict, total=False):
     cache_write_tokens: int
     cost_usd: float
     cost_sdk_usd: float
+    num_turns: int  # number of conversation turns
+
+    # Session context metadata
+    session_type: str  # "session_pool" or "direct"
+    session_status: str  # active, idle, connecting, etc.
+    session_age_seconds: float  # how long session has been alive
+    session_message_count: int  # number of messages in session
+    session_client_id: str  # unique session client identifier
+    session_pool_enabled: bool  # whether session pooling is enabled
+    session_idle_seconds: float  # how long since last activity
+    session_error_count: int  # number of errors in this session
+    session_is_new: bool  # whether this is a newly created session
 
 
 class SimpleDuckDBStorage:

ccproxy/observability/storage/models.py

@@ -44,6 +44,22 @@ class AccessLog(SQLModel, table=True):
     cache_write_tokens: int = Field(default=0)
     cost_usd: float = Field(default=0.0)
     cost_sdk_usd: float = Field(default=0.0)
+    num_turns: int = Field(default=0)  # number of conversation turns
+
+    # Session context metadata
+    session_type: str = Field(default="")  # "session_pool" or "direct"
+    session_status: str = Field(default="")  # active, idle, connecting, etc.
+    session_age_seconds: float = Field(default=0.0)  # how long session has been alive
+    session_message_count: int = Field(default=0)  # number of messages in session
+    session_client_id: str = Field(default="")  # unique session client identifier
+    session_pool_enabled: bool = Field(
+        default=False
+    )  # whether session pooling is enabled
+    session_idle_seconds: float = Field(default=0.0)  # how long since last activity
+    session_error_count: int = Field(default=0)  # number of errors in this session
+    session_is_new: bool = Field(
+        default=True
+    )  # whether this is a newly created session
 
     class Config:
         """SQLModel configuration."""

ccproxy/observability/streaming_response.py

@@ -0,0 +1,107 @@
+"""FastAPI StreamingResponse with automatic access logging on completion.
+
+This module provides a reusable StreamingResponseWithLogging class that wraps
+any async generator and handles access logging when the stream completes,
+eliminating code duplication between different streaming endpoints.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+import structlog
+from fastapi.responses import StreamingResponse
+
+from ccproxy.observability.access_logger import log_request_access
+
+
+if TYPE_CHECKING:
+    from ccproxy.observability.context import RequestContext
+    from ccproxy.observability.metrics import PrometheusMetrics
+
+logger = structlog.get_logger(__name__)
+
+
+class StreamingResponseWithLogging(StreamingResponse):
+    """FastAPI StreamingResponse that triggers access logging on completion.
+
+    This class wraps a streaming response generator to automatically trigger
+    access logging when the stream completes (either successfully or with an error).
+    This eliminates the need for manual access logging in individual stream processors.
+    """
+
+    def __init__(
+        self,
+        content: AsyncGenerator[bytes, None] | AsyncIterator[bytes],
+        request_context: RequestContext,
+        metrics: PrometheusMetrics | None = None,
+        status_code: int = 200,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize streaming response with logging capability.
+
+        Args:
+            content: The async generator producing streaming content
+            request_context: The request context for access logging
+            metrics: Optional PrometheusMetrics instance for recording metrics
+            status_code: HTTP status code for the response
+            **kwargs: Additional arguments passed to StreamingResponse
+        """
+        # Wrap the content generator to add logging
+        logged_content = self._wrap_with_logging(
+            content, request_context, metrics, status_code
+        )
+        super().__init__(logged_content, status_code=status_code, **kwargs)
+
+    async def _wrap_with_logging(
+        self,
+        content: AsyncGenerator[bytes, None] | AsyncIterator[bytes],
+        context: RequestContext,
+        metrics: PrometheusMetrics | None,
+        status_code: int,
+    ) -> AsyncGenerator[bytes, None]:
+        """Wrap content generator with access logging on completion.
+
+        Args:
+            content: The original content generator
+            context: Request context for logging
+            metrics: Optional metrics instance
+            status_code: HTTP status code
+
+        Yields:
+            bytes: Content chunks from the original generator
+        """
+        try:
+            # Stream all content from the original generator
+            async for chunk in content:
+                yield chunk
+        except GeneratorExit:
+            # Client disconnected - log this and re-raise to propagate to underlying generators
+            logger.info(
+                "streaming_response_client_disconnected",
+                request_id=context.request_id,
+                message="Client disconnected from streaming response, propagating GeneratorExit",
+            )
+            # CRITICAL: Re-raise GeneratorExit to propagate disconnect to create_listener()
+            raise
+        finally:
+            # Log access when stream completes (success or error)
+            try:
+                # Add streaming completion event type to context
+                context.add_metadata(event_type="streaming_complete")
+
+                # Check if status_code was updated in context metadata (e.g., due to error)
+                final_status_code = context.metadata.get("status_code", status_code)
+
+                await log_request_access(
+                    context=context,
+                    status_code=final_status_code,
+                    metrics=metrics,
+                )
+            except Exception as e:
+                logger.warning(
+                    "streaming_access_log_failed",
+                    error=str(e),
+                    request_id=context.request_id,
+                )

ccproxy/scheduler/manager.py

@@ -7,6 +7,7 @@ from ccproxy.config.settings import Settings
 from .core import Scheduler
 from .registry import register_task
 from .tasks import (
+    PoolStatsTask,
     PricingCacheUpdateTask,
     PushgatewayTask,
     StatsPrintingTask,
@@ -31,6 +32,19 @@ async def setup_scheduler_tasks(scheduler: Scheduler, settings: Settings) -> Non
         logger.info("scheduler_disabled")
         return
 
+    # Log network features status
+    logger.info(
+        "network_features_status",
+        pricing_updates_enabled=scheduler_config.pricing_update_enabled,
+        version_check_enabled=scheduler_config.version_check_enabled,
+        message=(
+            "Network features disabled by default for privacy"
+            if not scheduler_config.pricing_update_enabled
+            and not scheduler_config.version_check_enabled
+            else "Some network features are enabled"
+        ),
+    )
+
     # Add pushgateway task if enabled
     if scheduler_config.pushgateway_enabled:
         try:
@@ -123,21 +137,32 @@ async def setup_scheduler_tasks(scheduler: Scheduler, settings: Settings) -> Non
             )
 
 
-def _register_default_tasks() -> None:
-    """Register default task types in the global registry."""
+def _register_default_tasks(settings: Settings) -> None:
+    """Register default task types in the global registry based on configuration."""
     from .registry import get_task_registry
 
     registry = get_task_registry()
+    scheduler_config = settings.scheduler
 
-    # Only register if not already registered
-    if not registry.is_registered("pushgateway"):
+    # Only register pushgateway task if enabled
+    if scheduler_config.pushgateway_enabled and not registry.is_registered(
+        "pushgateway"
+    ):
         register_task("pushgateway", PushgatewayTask)
-    if not registry.is_registered("stats_printing"):
+
+    # Only register stats printing task if enabled
+    if scheduler_config.stats_printing_enabled and not registry.is_registered(
+        "stats_printing"
+    ):
         register_task("stats_printing", StatsPrintingTask)
+
+    # Always register core tasks (not metrics-related)
     if not registry.is_registered("pricing_cache_update"):
         register_task("pricing_cache_update", PricingCacheUpdateTask)
     if not registry.is_registered("version_update_check"):
         register_task("version_update_check", VersionUpdateCheckTask)
+    if not registry.is_registered("pool_stats"):
+        register_task("pool_stats", PoolStatsTask)
 
 
 async def start_scheduler(settings: Settings) -> Scheduler | None:
@@ -156,7 +181,7 @@ async def start_scheduler(settings: Settings) -> Scheduler | None:
             return None
 
         # Register task types (only when actually starting scheduler)
-        _register_default_tasks()
+        _register_default_tasks(settings)
 
         # Create scheduler with settings
         scheduler = Scheduler(

ccproxy/scheduler/tasks.py

@@ -483,6 +483,128 @@ class PricingCacheUpdateTask(BaseScheduledTask):
             return False
 
 
+class PoolStatsTask(BaseScheduledTask):
+    """Task for displaying pool statistics periodically."""
+
+    def __init__(
+        self,
+        name: str,
+        interval_seconds: float,
+        enabled: bool = True,
+        pool_manager: Any | None = None,
+    ):
+        """
+        Initialize pool stats task.
+
+        Args:
+            name: Task name
+            interval_seconds: Interval between stats display
+            enabled: Whether task is enabled
+            pool_manager: Injected pool manager instance
+        """
+        super().__init__(
+            name=name,
+            interval_seconds=interval_seconds,
+            enabled=enabled,
+        )
+        self._pool_manager = pool_manager
+
+    async def setup(self) -> None:
+        """Initialize pool manager instance if not injected."""
+        if self._pool_manager is None:
+            logger.warning(
+                "pool_stats_task_no_manager",
+                task_name=self.name,
+                message="Pool manager not injected, task will be disabled",
+            )
+
+    async def run(self) -> bool:
+        """Display pool statistics."""
+        try:
+            if not self._pool_manager:
+                return True  # Not an error, just no pool manager available
+
+            # Get general pool stats (if available)
+            general_pool = getattr(self._pool_manager, "_pool", None)
+            general_stats = None
+            if general_pool:
+                general_stats = general_pool.get_stats()
+
+            # Get session pool stats
+            session_pool = getattr(self._pool_manager, "_session_pool", None)
+            session_stats = None
+            if session_pool:
+                session_stats = await session_pool.get_stats()
+
+            # Log pool statistics
+            logger.debug(
+                "pool_stats_report",
+                task_name=self.name,
+                general_pool={
+                    "enabled": bool(general_pool),
+                    "total_clients": general_stats.total_clients
+                    if general_stats
+                    else 0,
+                    "available_clients": general_stats.available_clients
+                    if general_stats
+                    else 0,
+                    "active_clients": general_stats.active_clients
+                    if general_stats
+                    else 0,
+                    "connections_created": general_stats.connections_created
+                    if general_stats
+                    else 0,
+                    "connections_closed": general_stats.connections_closed
+                    if general_stats
+                    else 0,
+                    "acquire_count": general_stats.acquire_count
+                    if general_stats
+                    else 0,
+                    "release_count": general_stats.release_count
+                    if general_stats
+                    else 0,
+                    "health_check_failures": general_stats.health_check_failures
+                    if general_stats
+                    else 0,
+                }
+                if general_pool
+                else None,
+                session_pool={
+                    "enabled": session_stats.get("enabled", False)
+                    if session_stats
+                    else False,
+                    "total_sessions": session_stats.get("total_sessions", 0)
+                    if session_stats
+                    else 0,
+                    "active_sessions": session_stats.get("active_sessions", 0)
+                    if session_stats
+                    else 0,
+                    "max_sessions": session_stats.get("max_sessions", 0)
+                    if session_stats
+                    else 0,
+                    "total_messages": session_stats.get("total_messages", 0)
+                    if session_stats
+                    else 0,
+                    "session_ttl": session_stats.get("session_ttl", 0)
+                    if session_stats
+                    else 0,
+                }
+                if session_pool
+                else None,
+            )
+
+            return True
+
+        except Exception as e:
+            logger.error(
+                "pool_stats_task_error",
+                task_name=self.name,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return False
+
+
 class VersionUpdateCheckTask(BaseScheduledTask):
     """Task for checking version updates periodically."""