emergent-translator 1.1.0__py3-none-any.whl

emergent_translator/metrics.py

@@ -0,0 +1,436 @@
+"""
+Emergent Language Translator - Metrics & Event Emission
+
+Real-time metrics collection and event broadcasting for stress testing.
+Supports:
+- Structured logging with JSON output
+- PartyKit WebSocket event emission
+- Prometheus-compatible metrics
+- Real-time dashboard updates
+
+Usage:
+    from .metrics import MetricsCollector, emit_event
+
+    metrics = MetricsCollector()
+    metrics.record_request(latency_ms=15.2, success=True, compression_ratio=0.016)
+
+    await emit_event("stress_test", {"instance": "vps-1", "rps": 150})
+"""
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Dict, Any, Optional, List
+from collections import deque
+import os
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RequestMetric:
+    """Single request metric."""
+    timestamp: float
+    latency_ms: float
+    success: bool
+    original_size: int = 0
+    compressed_size: int = 0
+    compression_ratio: float = 0.0
+    endpoint: str = "/translate"
+    client_ip: str = "unknown"
+    error: Optional[str] = None
+    cache_hit: bool = False
+
+
+@dataclass
+class AggregatedMetrics:
+    """Aggregated metrics for a time window."""
+    window_start: float
+    window_end: float
+    total_requests: int
+    successful_requests: int
+    failed_requests: int
+    requests_per_second: float
+
+    latency_min_ms: float
+    latency_max_ms: float
+    latency_avg_ms: float
+    latency_p50_ms: float
+    latency_p95_ms: float
+    latency_p99_ms: float
+
+    avg_compression_ratio: float
+    total_bytes_in: int
+    total_bytes_out: int
+    bandwidth_savings_percent: float
+
+
+class MetricsCollector:
+    """
+    Collects and aggregates metrics for stress testing.
+
+    Features:
+    - Rolling window metrics
+    - Real-time event emission
+    - PartyKit integration
+    - Prometheus export
+    """
+
+    def __init__(
+        self,
+        window_size: int = 60,  # seconds
+        partykit_url: Optional[str] = None,
+        instance_id: str = "primary"
+    ):
+        self.window_size = window_size
+        self.partykit_url = partykit_url or os.getenv("PARTYKIT_URL")
+        self.instance_id = instance_id
+
+        # Rolling metrics storage
+        self.recent_requests: deque = deque(maxlen=10000)
+        self.start_time = time.time()
+
+        # Counters
+        self.total_requests = 0
+        self.total_successful = 0
+        self.total_failed = 0
+        self.total_bytes_in = 0
+        self.total_bytes_out = 0
+
+        # HTTP client for PartyKit
+        self._http_client: Optional[httpx.AsyncClient] = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create HTTP client."""
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(timeout=5.0)
+        return self._http_client
+
+    async def close(self):
+        """Close HTTP client."""
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    def record_request(
+        self,
+        latency_ms: float,
+        success: bool,
+        original_size: int = 0,
+        compressed_size: int = 0,
+        compression_ratio: float = 0.0,
+        endpoint: str = "/translate",
+        client_ip: str = "unknown",
+        error: Optional[str] = None,
+        cache_hit: bool = False
+    ):
+        """Record a single request metric."""
+        metric = RequestMetric(
+            timestamp=time.time(),
+            latency_ms=latency_ms,
+            success=success,
+            original_size=original_size,
+            compressed_size=compressed_size,
+            compression_ratio=compression_ratio,
+            endpoint=endpoint,
+            client_ip=client_ip,
+            error=error,
+            cache_hit=cache_hit
+        )
+
+        self.recent_requests.append(metric)
+        self.total_requests += 1
+
+        if success:
+            self.total_successful += 1
+            self.total_bytes_in += original_size
+            self.total_bytes_out += compressed_size
+        else:
+            self.total_failed += 1
+
+    def get_window_metrics(self, window_seconds: Optional[int] = None) -> AggregatedMetrics:
+        """Get aggregated metrics for a time window."""
+        window = window_seconds or self.window_size
+        now = time.time()
+        cutoff = now - window
+
+        # Filter to window
+        window_requests = [r for r in self.recent_requests if r.timestamp >= cutoff]
+
+        if not window_requests:
+            return AggregatedMetrics(
+                window_start=cutoff,
+                window_end=now,
+                total_requests=0,
+                successful_requests=0,
+                failed_requests=0,
+                requests_per_second=0,
+                latency_min_ms=0,
+                latency_max_ms=0,
+                latency_avg_ms=0,
+                latency_p50_ms=0,
+                latency_p95_ms=0,
+                latency_p99_ms=0,
+                avg_compression_ratio=0,
+                total_bytes_in=0,
+                total_bytes_out=0,
+                bandwidth_savings_percent=0
+            )
+
+        successful = [r for r in window_requests if r.success]
+        failed = [r for r in window_requests if not r.success]
+
+        # Latency percentiles
+        latencies = sorted([r.latency_ms for r in window_requests])
+        n = len(latencies)
+
+        bytes_in = sum(r.original_size for r in successful)
+        bytes_out = sum(r.compressed_size for r in successful)
+
+        return AggregatedMetrics(
+            window_start=cutoff,
+            window_end=now,
+            total_requests=len(window_requests),
+            successful_requests=len(successful),
+            failed_requests=len(failed),
+            requests_per_second=len(window_requests) / window,
+            latency_min_ms=min(latencies),
+            latency_max_ms=max(latencies),
+            latency_avg_ms=sum(latencies) / n,
+            latency_p50_ms=latencies[int(n * 0.5)],
+            latency_p95_ms=latencies[int(n * 0.95)] if n > 1 else latencies[-1],
+            latency_p99_ms=latencies[int(n * 0.99)] if n > 1 else latencies[-1],
+            avg_compression_ratio=sum(r.compression_ratio for r in successful) / len(successful) if successful else 0,
+            total_bytes_in=bytes_in,
+            total_bytes_out=bytes_out,
+            bandwidth_savings_percent=((bytes_in - bytes_out) / bytes_in * 100) if bytes_in > 0 else 0
+        )
+
+    def get_lifetime_stats(self) -> Dict[str, Any]:
+        """Get lifetime statistics."""
+        uptime = time.time() - self.start_time
+        return {
+            "instance_id": self.instance_id,
+            "uptime_seconds": uptime,
+            "total_requests": self.total_requests,
+            "total_successful": self.total_successful,
+            "total_failed": self.total_failed,
+            "success_rate": (self.total_successful / self.total_requests * 100) if self.total_requests > 0 else 0,
+            "requests_per_second": self.total_requests / uptime if uptime > 0 else 0,
+            "total_bytes_in": self.total_bytes_in,
+            "total_bytes_out": self.total_bytes_out,
+            "bandwidth_savings_percent": ((self.total_bytes_in - self.total_bytes_out) / self.total_bytes_in * 100) if self.total_bytes_in > 0 else 0
+        }
+
+    async def emit_to_partykit(self, event_type: str, data: Dict[str, Any]):
+        """Emit event to PartyKit room."""
+        if not self.partykit_url:
+            return
+
+        try:
+            client = await self._get_client()
+
+            event = {
+                "type": event_type,
+                "instance_id": self.instance_id,
+                "timestamp": datetime.utcnow().isoformat(),
+                "data": data
+            }
+
+            # POST to PartyKit HTTP endpoint
+            await client.post(
+                f"{self.partykit_url}/parties/main/stress-test",
+                json=event
+            )
+
+        except Exception as e:
+            logger.debug(f"PartyKit emit failed: {e}")
+
+    def to_prometheus(self) -> str:
+        """Export metrics in Prometheus format."""
+        stats = self.get_lifetime_stats()
+        window = self.get_window_metrics(60)
+
+        lines = [
+            f'# HELP emergent_requests_total Total number of translation requests',
+            f'# TYPE emergent_requests_total counter',
+            f'emergent_requests_total{{instance="{self.instance_id}"}} {stats["total_requests"]}',
+            f'',
+            f'# HELP emergent_requests_successful_total Successful requests',
+            f'# TYPE emergent_requests_successful_total counter',
+            f'emergent_requests_successful_total{{instance="{self.instance_id}"}} {stats["total_successful"]}',
+            f'',
+            f'# HELP emergent_requests_failed_total Failed requests',
+            f'# TYPE emergent_requests_failed_total counter',
+            f'emergent_requests_failed_total{{instance="{self.instance_id}"}} {stats["total_failed"]}',
+            f'',
+            f'# HELP emergent_latency_ms Request latency in milliseconds',
+            f'# TYPE emergent_latency_ms summary',
+            f'emergent_latency_ms{{instance="{self.instance_id}",quantile="0.5"}} {window.latency_p50_ms}',
+            f'emergent_latency_ms{{instance="{self.instance_id}",quantile="0.95"}} {window.latency_p95_ms}',
+            f'emergent_latency_ms{{instance="{self.instance_id}",quantile="0.99"}} {window.latency_p99_ms}',
+            f'',
+            f'# HELP emergent_compression_ratio Average compression ratio',
+            f'# TYPE emergent_compression_ratio gauge',
+            f'emergent_compression_ratio{{instance="{self.instance_id}"}} {window.avg_compression_ratio}',
+            f'',
+            f'# HELP emergent_rps Requests per second (60s window)',
+            f'# TYPE emergent_rps gauge',
+            f'emergent_rps{{instance="{self.instance_id}"}} {window.requests_per_second}',
+            f'',
+            f'# HELP emergent_bytes_in_total Total bytes received',
+            f'# TYPE emergent_bytes_in_total counter',
+            f'emergent_bytes_in_total{{instance="{self.instance_id}"}} {stats["total_bytes_in"]}',
+            f'',
+            f'# HELP emergent_bytes_out_total Total bytes sent (compressed)',
+            f'# TYPE emergent_bytes_out_total counter',
+            f'emergent_bytes_out_total{{instance="{self.instance_id}"}} {stats["total_bytes_out"]}',
+        ]
+
+        return '\n'.join(lines)
+
+
+# Global metrics instance
+_metrics: Optional[MetricsCollector] = None
+
+
+def get_metrics() -> MetricsCollector:
+    """Get or create global metrics collector."""
+    global _metrics
+    if _metrics is None:
+        _metrics = MetricsCollector(
+            instance_id=os.getenv("FLY_ALLOC_ID", "local")[:8]
+        )
+    return _metrics
+
+
+async def emit_event(event_type: str, data: Dict[str, Any]):
+    """Emit event to PartyKit (convenience function)."""
+    metrics = get_metrics()
+    await metrics.emit_to_partykit(event_type, data)
+
+
+# Structured logging setup
+
+class JSONFormatter(logging.Formatter):
+    """JSON log formatter for structured logging."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_data = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "instance": os.getenv("FLY_ALLOC_ID", "local")[:8],
+            "region": os.getenv("FLY_REGION", "local"),
+        }
+
+        # Add extra fields
+        if hasattr(record, "request_id"):
+            log_data["request_id"] = record.request_id
+        if hasattr(record, "latency_ms"):
+            log_data["latency_ms"] = record.latency_ms
+        if hasattr(record, "compression_ratio"):
+            log_data["compression_ratio"] = record.compression_ratio
+        if hasattr(record, "client_ip"):
+            log_data["client_ip"] = record.client_ip
+
+        # Add exception info
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        return json.dumps(log_data)
+
+
+def setup_structured_logging(level: str = "INFO"):
+    """Configure structured JSON logging."""
+    root_logger = logging.getLogger()
+    root_logger.setLevel(getattr(logging, level.upper()))
+
+    # Remove existing handlers
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    # Add JSON handler
+    handler = logging.StreamHandler()
+    handler.setFormatter(JSONFormatter())
+    root_logger.addHandler(handler)
+
+    logger.info("Structured logging configured", extra={"level": level})
+
+
+# Stress test event types
+
+class StressTestEvents:
+    """Event types for stress test monitoring."""
+
+    TEST_STARTED = "stress_test.started"
+    TEST_PROGRESS = "stress_test.progress"
+    TEST_COMPLETED = "stress_test.completed"
+
+    INSTANCE_JOINED = "instance.joined"
+    INSTANCE_HEARTBEAT = "instance.heartbeat"
+    INSTANCE_LEFT = "instance.left"
+
+    METRICS_UPDATE = "metrics.update"
+    ERROR_OCCURRED = "error.occurred"
+
+    SCALING_EVENT = "scaling.event"
+
+
+async def emit_test_started(
+    instance_id: str,
+    target_url: str,
+    num_clients: int,
+    requests_per_client: int
+):
+    """Emit stress test started event."""
+    await emit_event(StressTestEvents.TEST_STARTED, {
+        "instance_id": instance_id,
+        "target_url": target_url,
+        "num_clients": num_clients,
+        "requests_per_client": requests_per_client,
+        "total_requests": num_clients * requests_per_client
+    })
+
+
+async def emit_test_progress(
+    instance_id: str,
+    completed: int,
+    total: int,
+    current_rps: float,
+    avg_latency_ms: float
+):
+    """Emit stress test progress event."""
+    await emit_event(StressTestEvents.TEST_PROGRESS, {
+        "instance_id": instance_id,
+        "completed": completed,
+        "total": total,
+        "percent": (completed / total * 100) if total > 0 else 0,
+        "current_rps": current_rps,
+        "avg_latency_ms": avg_latency_ms
+    })
+
+
+async def emit_test_completed(
+    instance_id: str,
+    report: Dict[str, Any]
+):
+    """Emit stress test completed event."""
+    await emit_event(StressTestEvents.TEST_COMPLETED, {
+        "instance_id": instance_id,
+        "report": report
+    })
+
+
+async def emit_metrics_update(window_seconds: int = 10):
+    """Emit current metrics update."""
+    metrics = get_metrics()
+    window = metrics.get_window_metrics(window_seconds)
+
+    await emit_event(StressTestEvents.METRICS_UPDATE, asdict(window))