finchvox 0.0.1__py3-none-any.whl

finchvox/server.py

@@ -0,0 +1,201 @@
+"""
+Unified FinchVox server combining collector and UI functionality.
+
+This module provides a single server that handles both data collection
+(audio, logs, exceptions, OTLP traces) and the web UI for viewing traces.
+"""
+
+import asyncio
+import signal
+import grpc
+import uvicorn
+from concurrent import futures
+from pathlib import Path
+from fastapi import FastAPI
+from loguru import logger
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2_grpc import (
+    add_TraceServiceServicer_to_server
+)
+
+from finchvox.collector.service import TraceCollectorServicer
+from finchvox.collector.writer import SpanWriter
+from finchvox.collector.audio_handler import AudioHandler
+from finchvox.collector.collector_routes import register_collector_routes
+from finchvox.ui_routes import register_ui_routes
+from finchvox.collector.config import (
+    GRPC_PORT,
+    MAX_WORKERS,
+    get_default_data_dir,
+    get_traces_base_dir
+)
+
+
+class UnifiedServer:
+    """
+    Unified server managing both gRPC (OTLP traces) and HTTP (collector + UI).
+
+    This server provides:
+    - gRPC endpoint for OpenTelemetry trace collection (default port 4317)
+    - HTTP endpoints for audio/logs/exceptions collection (under /collector prefix)
+    - Web UI and REST API for viewing traces (at root /)
+    """
+
+    def __init__(self, port: int = 3000, grpc_port: int = GRPC_PORT, host: str = "0.0.0.0", data_dir: Path = None):
+        """
+        Initialize the unified server.
+
+        Args:
+            port: HTTP server port (default: 3000)
+            grpc_port: gRPC server port (default: 4317)
+            host: Host to bind to (default: "0.0.0.0")
+            data_dir: Base data directory (default: ~/.finchvox)
+        """
+        self.port = port
+        self.grpc_port = grpc_port
+        self.host = host
+        self.data_dir = data_dir if data_dir else get_default_data_dir()
+
+        # Initialize shared writer instances
+        self.span_writer = SpanWriter(self.data_dir)
+        self.audio_handler = AudioHandler(self.data_dir)
+
+        # Server instances
+        self.grpc_server = None
+        self.http_server = None
+        self.shutdown_event = asyncio.Event()
+        self._is_shutting_down = False
+
+        # Create unified FastAPI app
+        self.app = self._create_app()
+
+    def _create_app(self) -> FastAPI:
+        """
+        Create unified FastAPI application with both collector and UI routes.
+
+        Returns:
+            Configured FastAPI application
+        """
+        app = FastAPI(
+            title="FinchVox Unified Server",
+            description="Combined collector and UI server for voice AI observability",
+            version="0.1.0",
+        )
+
+        # Register UI routes first (includes static file mounts)
+        register_ui_routes(app, self.data_dir)
+
+        # Register collector routes with /collector prefix
+        register_collector_routes(
+            app,
+            self.audio_handler,
+            prefix="/collector"
+        )
+
+        return app
+
+    async def start_grpc(self):
+        """Start the gRPC server for OTLP trace collection."""
+        logger.info(f"Starting OTLP gRPC collector on port {self.grpc_port}")
+
+        # Create gRPC server with thread pool
+        self.grpc_server = grpc.server(
+            futures.ThreadPoolExecutor(max_workers=MAX_WORKERS)
+        )
+
+        # Register our service implementation
+        servicer = TraceCollectorServicer(self.span_writer)
+        add_TraceServiceServicer_to_server(servicer, self.grpc_server)
+
+        # Bind to port (insecure for PoC - no TLS)
+        self.grpc_server.add_insecure_port(f'[::]:{self.grpc_port}')
+
+        # Start serving
+        self.grpc_server.start()
+        logger.info(f"OTLP collector listening on port {self.grpc_port}")
+        logger.info(f"Writing traces to: {get_traces_base_dir(self.data_dir).absolute()}")
+
+    async def start_http(self):
+        """Start the HTTP server using uvicorn."""
+        logger.info(f"Starting HTTP server on {self.host}:{self.port}")
+
+        # Configure uvicorn server
+        config = uvicorn.Config(
+            self.app,
+            host=self.host,
+            port=self.port,
+            log_level="info",
+            access_log=True,
+        )
+        self.http_server = uvicorn.Server(config)
+
+        logger.info(f"HTTP server listening on http://{self.host}:{self.port}")
+        logger.info(f"  - UI: http://{self.host}:{self.port}")
+        logger.info(f"  - Collector: http://{self.host}:{self.port}/collector")
+        logger.info(f"Data directory: {self.data_dir.absolute()}")
+
+        # Run server until shutdown event
+        await self.http_server.serve()
+
+    async def start(self):
+        """Start both gRPC and HTTP servers concurrently."""
+        # Start gRPC server
+        await self.start_grpc()
+
+        # Start HTTP server (this blocks until shutdown)
+        await self.start_http()
+
+    async def stop(self, grace_period: int = 5):
+        """
+        Gracefully stop both servers.
+
+        Args:
+            grace_period: Seconds to wait for in-flight requests to complete
+        """
+        # Prevent multiple shutdown attempts
+        if self._is_shutting_down:
+            return
+
+        self._is_shutting_down = True
+        logger.info(f"Shutting down servers (grace period: {grace_period}s)")
+
+        # Stop HTTP server
+        if self.http_server:
+            logger.info("Stopping HTTP server...")
+            self.http_server.should_exit = True
+            await asyncio.sleep(0.1)  # Give it time to process shutdown
+
+        # Stop gRPC server
+        if self.grpc_server:
+            logger.info("Stopping gRPC server...")
+            self.grpc_server.stop(grace_period)
+
+        logger.info("All servers stopped")
+
+    def run(self):
+        """
+        Blocking entry point for running the unified server.
+
+        Sets up signal handlers and runs the event loop until shutdown.
+        """
+        async def run_with_signals():
+            loop = asyncio.get_running_loop()
+
+            def handle_shutdown(signum):
+                if not self._is_shutting_down:
+                    logger.info(f"Received signal {signum}")
+                    # Remove signal handlers to prevent duplicate calls
+                    for sig in (signal.SIGINT, signal.SIGTERM):
+                        loop.remove_signal_handler(sig)
+                    # Create shutdown task
+                    asyncio.create_task(self.stop())
+
+            # Register signal handlers
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, lambda s=sig: handle_shutdown(s))
+
+            try:
+                await self.start()
+            except (KeyboardInterrupt, asyncio.CancelledError):
+                await self.stop()
+
+        asyncio.run(run_with_signals())

finchvox/trace.py

@@ -0,0 +1,115 @@
+"""Trace metadata and utilities."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+class Trace:
+    """
+    Represents a trace and provides calculated metadata.
+
+    Loads span data from a trace JSONL file and calculates:
+    - Start time (earliest span start)
+    - End time (latest span end)
+    - Duration in milliseconds
+    - Span count
+    """
+
+    def __init__(self, trace_file: Path):
+        """
+        Initialize trace from a trace file path.
+
+        Args:
+            trace_file: Path to trace_{trace_id}.jsonl file
+        """
+        self.trace_file = trace_file
+        self.trace_id = trace_file.stem.replace("trace_", "")
+        self._span_count: Optional[int] = None
+        self._min_start_nano: Optional[int] = None
+        self._max_end_nano: Optional[int] = None
+        self._service_name: Optional[str] = None
+        self._load_metadata()
+
+    def _load_metadata(self):
+        """Load span metadata from trace file."""
+        span_count = 0
+        min_start = None
+        max_end = None
+        service_name = None
+
+        try:
+            with open(self.trace_file, 'r') as f:
+                for line in f:
+                    if line.strip():
+                        span = json.loads(line)
+                        span_count += 1
+
+                        if "start_time_unix_nano" in span:
+                            start_nano = int(span["start_time_unix_nano"])
+                            if min_start is None or start_nano < min_start:
+                                min_start = start_nano
+
+                        if "end_time_unix_nano" in span:
+                            end_nano = int(span["end_time_unix_nano"])
+                            if max_end is None or end_nano > max_end:
+                                max_end = end_nano
+
+                        # Extract service name from first span with resource attributes
+                        if service_name is None and "resource" in span:
+                            resource = span["resource"]
+                            if "attributes" in resource:
+                                for attr in resource["attributes"]:
+                                    if attr.get("key") == "service.name":
+                                        value = attr.get("value", {})
+                                        service_name = value.get("string_value")
+                                        break
+        except Exception as e:
+            print(f"Error loading trace {self.trace_file}: {e}")
+
+        self._span_count = span_count
+        self._min_start_nano = min_start
+        self._max_end_nano = max_end
+        self._service_name = service_name
+
+    @property
+    def span_count(self) -> int:
+        """Get total span count."""
+        return self._span_count or 0
+
+    @property
+    def start_time(self) -> Optional[float]:
+        """Get trace start time in seconds (Unix timestamp)."""
+        if self._min_start_nano:
+            return self._min_start_nano / 1_000_000_000
+        return None
+
+    @property
+    def end_time(self) -> Optional[float]:
+        """Get trace end time in seconds (Unix timestamp)."""
+        if self._max_end_nano:
+            return self._max_end_nano / 1_000_000_000
+        return None
+
+    @property
+    def duration_ms(self) -> Optional[float]:
+        """Get trace duration in milliseconds."""
+        if self._min_start_nano and self._max_end_nano:
+            return (self._max_end_nano - self._min_start_nano) / 1_000_000
+        return None
+
+    @property
+    def service_name(self) -> Optional[str]:
+        """Get service name from first span with resource attributes."""
+        return self._service_name
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for API response."""
+        return {
+            "trace_id": self.trace_id,
+            "service_name": self.service_name,
+            "span_count": self.span_count,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "duration_ms": self.duration_ms,
+        }