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

ccproxy/plugins/access_log/logger.py

@@ -0,0 +1,254 @@
+"""Utility functions for comprehensive access logging.
+
+This module provides logging utilities adapted from the observability
+module for use within the access_log plugin.
+"""
+
+import time
+from typing import Any
+
+from ccproxy.core.logging import get_plugin_logger
+
+
+logger = get_plugin_logger(__name__)
+
+
+async def log_request_access(
+    request_id: str,
+    method: str | None = None,
+    path: str | None = None,
+    status_code: int | None = None,
+    duration_ms: float | None = None,
+    client_ip: str | None = None,
+    user_agent: str | None = None,
+    query: str | None = None,
+    error_message: str | None = None,
+    **additional_metadata: Any,
+) -> None:
+    """Log comprehensive access information for a request.
+
+    This function generates a unified access log entry with complete request
+    metadata including timing, tokens, costs, and any additional context.
+
+    Args:
+        request_id: Request identifier
+        method: HTTP method
+        path: Request path
+        status_code: HTTP status code
+        duration_ms: Request duration in milliseconds
+        client_ip: Client IP address
+        user_agent: User agent string
+        query: Query parameters
+        error_message: Error message if applicable
+        **additional_metadata: Any additional fields to include
+    """
+    # Prepare basic log data (always included)
+    log_data: dict[str, Any] = {
+        "request_id": request_id,
+        "method": method,
+        "path": path,
+        "query": query,
+        "client_ip": client_ip,
+        "user_agent": user_agent,
+    }
+
+    # Add response-specific fields
+    log_data.update(
+        {
+            "status_code": status_code,
+            "duration_ms": duration_ms,
+            "duration_seconds": duration_ms / 1000 if duration_ms else None,
+            "error_message": error_message,
+        }
+    )
+
+    # Add token and cost metrics if available in metadata
+    token_fields = [
+        "tokens_input",
+        "tokens_output",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "cost_usd",
+        "num_turns",
+    ]
+
+    for field in token_fields:
+        value = additional_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
+    # Add service and endpoint info
+    service_fields = ["endpoint", "model", "streaming", "service_type", "provider"]
+
+    for field in service_fields:
+        value = additional_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
+    # Add session context metadata if available
+    session_fields = [
+        "session_id",
+        "session_type",
+        "session_status",
+        "session_age_seconds",
+        "session_message_count",
+        "session_pool_enabled",
+        "session_idle_seconds",
+        "session_error_count",
+        "session_is_new",
+    ]
+
+    for field in session_fields:
+        value = additional_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
+    # Add rate limit headers if available
+    rate_limit_fields = [
+        "x-ratelimit-limit",
+        "x-ratelimit-remaining",
+        "x-ratelimit-reset",
+        "anthropic-ratelimit-requests-limit",
+        "anthropic-ratelimit-requests-remaining",
+        "anthropic-ratelimit-requests-reset",
+        "anthropic-ratelimit-tokens-limit",
+        "anthropic-ratelimit-tokens-remaining",
+        "anthropic-ratelimit-tokens-reset",
+        "anthropic_request_id",
+    ]
+
+    for field in rate_limit_fields:
+        value = additional_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
+    # Add any additional metadata provided
+    log_data.update(additional_metadata)
+
+    # Remove None values to keep log clean
+    log_data = {k: v for k, v in log_data.items() if v is not None}
+
+    # Log with appropriate level
+    bound_logger = logger.bind(**log_data)
+
+    if error_message:
+        bound_logger.warning("access_log", exc_info=additional_metadata.get("error"))
+    else:
+        is_streaming = additional_metadata.get("streaming", False)
+        is_streaming_complete = (
+            additional_metadata.get("event_type", "") == "streaming_complete"
+        )
+
+        if not is_streaming or is_streaming_complete:
+            bound_logger.info("access_log")
+        else:
+            # If streaming is true, and not streaming_complete log as debug
+            bound_logger.info("access_log_streaming_start")
+
+
+def log_request_start(
+    request_id: str,
+    method: str,
+    path: str,
+    client_ip: str | None = None,
+    user_agent: str | None = None,
+    query: str | None = None,
+    **additional_metadata: Any,
+) -> None:
+    """Log request start event with basic information.
+
+    This is used for early/hook logging when full context isn't available yet.
+
+    Args:
+        request_id: Request identifier
+        method: HTTP method
+        path: Request path
+        client_ip: Client IP address
+        user_agent: User agent string
+        query: Query parameters
+        **additional_metadata: Any additional fields to include
+    """
+    log_data: dict[str, Any] = {
+        "request_id": request_id,
+        "method": method,
+        "path": path,
+        "client_ip": client_ip,
+        "user_agent": user_agent,
+        "query": query,
+        "event_type": "request_start",
+        "timestamp": time.time(),
+    }
+
+    # Add any additional metadata
+    log_data.update(additional_metadata)
+
+    # Remove None values
+    log_data = {k: v for k, v in log_data.items() if v is not None}
+
+    logger.debug("access_log_start", **log_data)
+
+
+async def log_provider_access(
+    request_id: str,
+    provider: str,
+    method: str,
+    url: str,
+    status_code: int | None = None,
+    duration_ms: float | None = None,
+    error_message: str | None = None,
+    **additional_metadata: Any,
+) -> None:
+    """Log provider access information.
+
+    Args:
+        request_id: Request identifier
+        provider: Provider name
+        method: HTTP method
+        url: Provider URL
+        status_code: Response status code
+        duration_ms: Request duration in milliseconds
+        error_message: Error message if applicable
+        **additional_metadata: Any additional fields to include
+    """
+    log_data: dict[str, Any] = {
+        "request_id": request_id,
+        "provider": provider,
+        "method": method,
+        "url": url,
+        "status_code": status_code,
+        "duration_ms": duration_ms,
+        "duration_seconds": duration_ms / 1000 if duration_ms else None,
+        "error_message": error_message,
+        "event_type": "provider_access",
+    }
+
+    # Add token and cost metrics if available
+    token_fields = [
+        "tokens_input",
+        "tokens_output",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "cost_usd",
+        "model",
+    ]
+
+    for field in token_fields:
+        value = additional_metadata.get(field)
+        if value is not None:
+            log_data[field] = value
+
+    # Add any additional metadata
+    log_data.update(additional_metadata)
+
+    # Remove None values
+    log_data = {k: v for k, v in log_data.items() if v is not None}
+
+    # Log with appropriate level
+    bound_logger = logger.bind(**log_data)
+
+    if error_message:
+        bound_logger.warning(
+            "provider_access_log", exc_info=additional_metadata.get("error")
+        )
+    else:
+        bound_logger.info("provider_access_log")

ccproxy/plugins/access_log/plugin.py

@@ -0,0 +1,137 @@
+from typing import Any
+
+from ccproxy.core.logging import get_plugin_logger
+from ccproxy.core.plugins import (
+    PluginManifest,
+    SystemPluginFactory,
+    SystemPluginRuntime,
+)
+from ccproxy.core.plugins.hooks import HookRegistry
+from ccproxy.plugins.analytics.ingest import AnalyticsIngestService
+from ccproxy.services.container import ServiceContainer
+
+from .config import AccessLogConfig
+from .hook import AccessLogHook
+
+
+logger = get_plugin_logger()
+
+
+class AccessLogRuntime(SystemPluginRuntime):
+    """Runtime for access log plugin.
+
+    Integrates with the Hook system to receive and log events.
+    """
+
+    def __init__(self, manifest: PluginManifest):
+        super().__init__(manifest)
+        self.hook: AccessLogHook | None = None
+        self.config: AccessLogConfig | None = None
+
+    async def _on_initialize(self) -> None:
+        """Initialize the access logger."""
+        if not self.context:
+            raise RuntimeError("Context not set")
+
+        # Get configuration
+        config: AccessLogConfig | None = self.context.get("config")
+        if config is None or not isinstance(config, AccessLogConfig):
+            config = AccessLogConfig()
+        self.config = config
+
+        if not config.enabled:
+            return
+
+        self.hook = AccessLogHook(config)
+
+        hook_registry = self.context.get(HookRegistry)
+
+        if hook_registry is None or not isinstance(hook_registry, HookRegistry):
+            raise RuntimeError("Hook registry not found in context")
+
+        hook_registry.register(self.hook)
+
+        # Try to wire analytics ingest service if available
+        try:
+            registry = self.context.get(ServiceContainer)
+            self.hook.ingest_service = registry.get_service(AnalyticsIngestService)
+            if not self.hook.ingest_service:
+                # optional service
+                logger.debug("access_log_analytics_service_not_found")
+        except Exception as e:
+            logger.warning(
+                "access_log_ingest_service_connect_failed", error=str(e), exc_info=e
+            )
+        #
+        # Consolidated ready summary at INFO
+        logger.trace(
+            "access_log_ready",
+            client_enabled=config.client_enabled,
+            provider_enabled=config.provider_enabled,
+            client_format=config.client_format,
+            client_log_file=config.client_log_file,
+            provider_log_file=config.provider_log_file,
+        )
+
+    async def _on_shutdown(self) -> None:
+        """Cleanup on shutdown."""
+        # Unregister hook from registry
+        if self.hook:
+            # Try to get hook registry
+            hook_registry = None
+            if self.context:
+                hook_registry = self.context.get("hook_registry")
+                if not hook_registry:
+                    app = self.context.get("app")
+                    if (
+                        app
+                        and hasattr(app, "state")
+                        and hasattr(app.state, "hook_registry")
+                    ):
+                        hook_registry = app.state.hook_registry
+
+            if hook_registry and isinstance(hook_registry, HookRegistry):
+                hook_registry.unregister(self.hook)
+                logger.trace("access_log_hook_unregistered")
+
+            # Close hook (flushes writers)
+            await self.hook.close()
+            logger.trace("access_log_shutdown")
+
+    async def _get_health_details(self) -> dict[str, Any]:
+        """Get health check details."""
+        config = self.config
+
+        return {
+            "type": "system",
+            "initialized": self.initialized,
+            "enabled": config.enabled if config else False,
+            "client_enabled": config.client_enabled if config else False,
+            "provider_enabled": config.provider_enabled if config else False,
+        }
+
+    def get_hook(self) -> AccessLogHook | None:
+        """Get the hook instance (for testing or manual integration)."""
+        return self.hook
+
+
+class AccessLogFactory(SystemPluginFactory):
+    """Factory for access log plugin."""
+
+    def __init__(self) -> None:
+        manifest = PluginManifest(
+            name="access_log",
+            version="0.1.0",
+            description="Simple access logging with Common, Combined, and Structured formats",
+            is_provider=False,
+            config_class=AccessLogConfig,
+            # dependencies=["analytics"], # optional, handled at runtime
+        )
+        super().__init__(manifest)
+
+    def create_runtime(self) -> AccessLogRuntime:
+        return AccessLogRuntime(self.manifest)
+
+
+# Export the factory instance
+factory = AccessLogFactory()

ccproxy/plugins/access_log/writer.py

@@ -0,0 +1,109 @@
+import asyncio
+import time
+from pathlib import Path
+
+import aiofiles
+
+from ccproxy.core.logging import get_plugin_logger
+
+
+logger = get_plugin_logger(__name__)
+
+
+class AccessLogWriter:
+    """Simple async file writer for access logs.
+
+    Features:
+    - Async file I/O for performance
+    - Optional buffering to reduce I/O operations
+    - Thread-safe with asyncio.Lock
+    - Auto-creates parent directories
+    """
+
+    def __init__(
+        self,
+        log_file: str,
+        buffer_size: int = 100,
+        flush_interval: float = 1.0,
+    ):
+        """Initialize the writer.
+
+        Args:
+            log_file: Path to the log file
+            buffer_size: Number of entries to buffer before writing
+            flush_interval: Time in seconds between automatic flushes
+        """
+        self.log_file = Path(log_file)
+        self.buffer_size = buffer_size
+        self.flush_interval = flush_interval
+
+        self._buffer: list[str] = []
+        self._lock = asyncio.Lock()
+        self._flush_task: asyncio.Task[None] | None = None
+        self._last_flush = time.time()
+
+        # Ensure parent directory exists
+        self.log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    async def write(self, line: str) -> None:
+        """Write a line to the log file.
+
+        Lines are buffered and written in batches for performance.
+
+        Args:
+            line: The formatted log line to write
+        """
+        async with self._lock:
+            self._buffer.append(line)
+
+            # Flush if buffer is full
+            if len(self._buffer) >= self.buffer_size:
+                await self._flush()
+            else:
+                # Schedule a flush if not already scheduled
+                self._schedule_flush()
+
+    async def _flush(self) -> None:
+        """Flush the buffer to disk.
+
+        This method assumes the lock is already held.
+        """
+        if not self._buffer:
+            return
+
+        try:
+            # Write all buffered lines at once
+            async with aiofiles.open(self.log_file, "a") as f:
+                await f.write("\n".join(self._buffer) + "\n")
+
+            self._buffer.clear()
+            self._last_flush = time.time()
+
+        except Exception as e:
+            logger.error(
+                "access_log_write_error",
+                error=str(e),
+                log_file=str(self.log_file),
+                buffer_size=len(self._buffer),
+            )
+
+    def _schedule_flush(self) -> None:
+        """Schedule an automatic flush after the flush interval."""
+        if self._flush_task and not self._flush_task.done():
+            return  # Already scheduled
+
+        self._flush_task = asyncio.create_task(self._auto_flush())
+
+    async def _auto_flush(self) -> None:
+        """Automatically flush the buffer after the flush interval."""
+        await asyncio.sleep(self.flush_interval)
+        async with self._lock:
+            await self._flush()
+
+    async def close(self) -> None:
+        """Close the writer and flush any remaining data."""
+        async with self._lock:
+            await self._flush()
+
+        if self._flush_task and not self._flush_task.done():
+            self._flush_task.cancel()

ccproxy/plugins/analytics/README.md

@@ -0,0 +1,24 @@
+# Analytics Plugin
+
+Persists structured access logs and serves query APIs for observability data.
+
+## Highlights
+- Ensures DuckDB schemas exist and registers the `access_logs` SQLModel table
+- Publishes an ingest service consumed by the access log hook
+- Adds `/logs` routes for querying, streaming, and inspecting request history
+
+## Configuration
+- `AnalyticsPluginConfig` toggles collection, retention, and debug logging
+- Requires the `duckdb_storage` plugin to supply the underlying engine
+- Generate defaults with `python3 scripts/generate_config_from_model.py \
+  --format toml --plugin analytics --config-class AnalyticsPluginConfig`
+
+```toml
+[plugins.analytics]
+# enabled = true
+```
+
+## Related Components
+- `plugin.py`: runtime initialization and service registration
+- `ingest.py`: writes events into DuckDB using SQLModel
+- `routes.py`: FastAPI router for analytics and log queries

ccproxy/plugins/analytics/__init__.py

@@ -0,0 +1 @@
+"""Analytics plugin (logs query/analytics/stream endpoints)."""

ccproxy/plugins/analytics/config.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, Field
+
+
+class AnalyticsPluginConfig(BaseModel):
+    enabled: bool = Field(default=True, description="Enable analytics routes")

ccproxy/plugins/analytics/ingest.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import datetime
+from typing import Any
+
+from sqlmodel import Session
+
+from .models import AccessLog
+
+
+class AnalyticsIngestService:
+    """Ingest access logs directly via SQLModel.
+
+    This service accepts a SQLAlchemy/SQLModel engine and writes AccessLog rows
+    without delegating to a storage-specific `store_request` API.
+    """
+
+    def __init__(self, engine: Any | None):
+        self._engine = engine
+
+    async def ingest(self, log_data: dict[str, Any]) -> bool:
+        """Normalize payload and persist using SQLModel.
+
+        Args:
+            log_data: Access log fields captured by hooks
+
+        Returns:
+            True on success, False otherwise
+        """
+        if not self._engine:
+            return False
+
+        # Normalize timestamp to datetime
+        ts_value = log_data.get("timestamp", time.time())
+        if isinstance(ts_value, int | float):
+            ts_dt = datetime.fromtimestamp(ts_value)
+        else:
+            ts_dt = ts_value
+
+        # Prefer explicit endpoint then path
+        endpoint = log_data.get("endpoint", log_data.get("path", ""))
+
+        # Map incoming dict to AccessLog fields; defaults keep schema stable
+        row = AccessLog(
+            request_id=str(log_data.get("request_id", "")),
+            timestamp=ts_dt,
+            method=str(log_data.get("method", "")),
+            endpoint=str(endpoint),
+            path=str(log_data.get("path", "")),
+            query=str(log_data.get("query", "")),
+            client_ip=str(log_data.get("client_ip", "")),
+            user_agent=str(log_data.get("user_agent", "")),
+            service_type=str(log_data.get("service_type", "access_log")),
+            provider=str(log_data.get("provider", "")),
+            model=str(log_data.get("model", "")),
+            streaming=bool(log_data.get("streaming", False)),
+            status_code=int(log_data.get("status_code", 200)),
+            duration_ms=float(log_data.get("duration_ms", 0.0)),
+            duration_seconds=float(
+                log_data.get("duration_seconds", log_data.get("duration_ms", 0.0))
+            )
+            / 1000.0
+            if "duration_seconds" not in log_data
+            else float(log_data.get("duration_seconds", 0.0)),
+            tokens_input=int(log_data.get("tokens_input", 0)),
+            tokens_output=int(log_data.get("tokens_output", 0)),
+            cache_read_tokens=int(log_data.get("cache_read_tokens", 0)),
+            cache_write_tokens=int(log_data.get("cache_write_tokens", 0)),
+            cost_usd=float(log_data.get("cost_usd", 0.0)),
+            cost_sdk_usd=float(log_data.get("cost_sdk_usd", 0.0)),
+        )
+
+        try:
+            # Execute the DB write in a thread to avoid blocking the event loop
+            return await asyncio.to_thread(self._insert_sync, row)
+        except Exception:
+            return False
+
+    def _insert_sync(self, row: AccessLog) -> bool:
+        with Session(self._engine) as session:
+            session.add(row)
+            session.commit()
+        return True