auratrace-sdk 2.0.0__tar.gz

auratrace_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: auratrace-sdk
+Version: 2.0.0
+Summary: Official Python Telemetry & AI Diagnostic SDK for AuraTrace Autonomous Backend Diagnostics
+Author-email: Sunil Singh <sunilsinghrajput192@gmail.com>
+Project-URL: Homepage, https://github.com/sunilsingh175/auratrace
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+
+# Trace Python SDK
+
+Official Python telemetry and unhandled crash diagnostics SDK for Trace.
+
+## Quickstart
+
+```python
+from trace_sdk import Trace, TraceMiddleware
+
+# Initialize Trace Client
+trace = Trace(
+    service_id="payment-service",
+    api_key="trace_payment_secret_456",
+    endpoint="http://localhost:8000"
+)
+
+# 1. Log metrics & structured messages
+trace.info("User checkout initiated", latency_ms=45.2, metadata={"user_id": "usr_99"})
+
+# 2. Capture and report caught exceptions
+try:
+    process_payment()
+except Exception as e:
+    trace.capture_exception(e, message="Payment processing failure")
+
+# 3. Use as a FastAPI / Starlette middleware
+# Automatically records latency and reports unhandled exceptions
+app.add_middleware(TraceMiddleware, client=trace)
+```

auratrace_sdk-2.0.0/README.md

@@ -0,0 +1,29 @@
+# Trace Python SDK
+
+Official Python telemetry and unhandled crash diagnostics SDK for Trace.
+
+## Quickstart
+
+```python
+from trace_sdk import Trace, TraceMiddleware
+
+# Initialize Trace Client
+trace = Trace(
+    service_id="payment-service",
+    api_key="trace_payment_secret_456",
+    endpoint="http://localhost:8000"
+)
+
+# 1. Log metrics & structured messages
+trace.info("User checkout initiated", latency_ms=45.2, metadata={"user_id": "usr_99"})
+
+# 2. Capture and report caught exceptions
+try:
+    process_payment()
+except Exception as e:
+    trace.capture_exception(e, message="Payment processing failure")
+
+# 3. Use as a FastAPI / Starlette middleware
+# Automatically records latency and reports unhandled exceptions
+app.add_middleware(TraceMiddleware, client=trace)
+```

auratrace_sdk-2.0.0/auratrace/__init__.py

@@ -0,0 +1,57 @@
+"""
+AutoTrace Python SDK
+"""
+
+from typing import Optional
+from .client import AutoTrace, AuraTrace, TraceClient, Trace, AutomaticBackendDetection
+
+_default_client: Optional[AutoTrace] = None
+
+def init(
+    api_key: Optional[str] = None,
+    service_name: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    environment: Optional[str] = None,
+    version: Optional[str] = None,
+    batch_size: int = 50,
+    flush_interval_seconds: float = 1.0,
+    install_global_hook: bool = True,
+) -> AutoTrace:
+    global _default_client
+    _default_client = AutoTrace(
+        api_key=api_key,
+        service_name=service_name,
+        endpoint=endpoint,
+        environment=environment,
+        version=version,
+        batch_size=batch_size,
+        flush_interval_seconds=flush_interval_seconds,
+        install_global_hook=install_global_hook,
+    )
+    return _default_client
+
+def capture_message(message: str, metadata: Optional[dict] = None) -> None:
+    if _default_client is None:
+        init()
+    _default_client.capture_message(message, metadata=metadata)
+
+def capture_exception(exception: BaseException, metadata: Optional[dict] = None) -> None:
+    if _default_client is None:
+        init()
+    _default_client.capture_exception(exception, metadata=metadata)
+
+def flush() -> None:
+    if _default_client is not None:
+        _default_client.flush()
+
+__all__ = [
+    "AutoTrace",
+    "AuraTrace",
+    "TraceClient",
+    "Trace",
+    "AutomaticBackendDetection",
+    "init",
+    "capture_message",
+    "capture_exception",
+    "flush",
+]

auratrace_sdk-2.0.0/auratrace/client.py

@@ -0,0 +1,265 @@
+"""
+AuraTrace Python SDK
+Zero-configuration telemetry, automatic service discovery, and AI root cause capture.
+"""
+
+import os
+import sys
+import time
+import queue
+import threading
+import traceback
+import json
+from datetime import datetime, timezone
+from typing import Optional, Dict, Any, List
+import urllib.request
+import urllib.error
+
+try:
+    import httpx
+except ImportError:
+    httpx = None
+
+
+def auto_detect_service_name() -> str:
+    """Auto-detects the service identifier from environment variables or running script."""
+    name = (
+        os.getenv("AUTOTRACE_SERVICE_NAME")
+        or os.getenv("AURATRACE_SERVICE_NAME")
+        or os.getenv("SERVICE_NAME")
+        or os.getenv("APP_NAME")
+    )
+    if name:
+        return name.strip()
+
+    if sys.argv and sys.argv[0]:
+        base = os.path.basename(sys.argv[0])
+        clean = os.path.splitext(base)[0]
+        if clean and clean not in ("python", "python3", "pytest", "uvicorn", "gunicorn", "__main__", "-c"):
+            return clean
+
+def _sanitize_stack_trace(trace_str: str) -> str:
+    if not trace_str:
+        return ""
+    import re
+    def _clean_path(match):
+        full_path = match.group(1).replace("\\", "/")
+        parts = full_path.split("/")
+        for marker in ["scripts", "app", "backend", "services", "controllers", "models", "workers"]:
+            if marker in parts:
+                idx = parts.index(marker)
+                return f'File "{"/".join(parts[idx:])}"'
+        if len(parts) > 1:
+            return f'File "{"/".join(parts[-2:])}"'
+        return f'File "{parts[-1]}"'
+    return re.sub(r'File "([^"]+)"', _clean_path, trace_str)
+
+
+class AutoTrace:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        service_name: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        environment: Optional[str] = None,
+        version: Optional[str] = None,
+        batch_size: int = 50,
+        flush_interval_seconds: float = 1.0,
+        install_global_hook: bool = True,
+    ):
+        self.api_key = (
+            api_key
+            or os.getenv("AUTOTRACE_API_KEY")
+            or os.getenv("AURATRACE_API_KEY")
+            or os.getenv("AURA_MASTER_API_KEY")
+            or ""
+        )
+        self.service_name = service_name or auto_detect_service_name()
+        self.endpoint = (
+            endpoint
+            or os.getenv("AUTOTRACE_ENDPOINT")
+            or os.getenv("AURATRACE_ENDPOINT")
+            or "http://localhost:8000"
+        ).rstrip("/")
+        self.environment = environment or os.getenv("ENV") or os.getenv("ENVIRONMENT") or "production"
+        self.version = version or os.getenv("APP_VERSION") or "1.0.0"
+        self.runtime = "python"
+        self.batch_size = batch_size
+        self.flush_interval_seconds = flush_interval_seconds
+
+        self._queue: queue.Queue = queue.Queue(maxsize=10000)
+        self._is_running = True
+        self._worker_thread = threading.Thread(target=self._flusher_loop, daemon=True)
+        self._worker_thread.start()
+
+        if install_global_hook:
+            self._install_excepthook()
+
+    def log(
+        self,
+        level: str,
+        message: str,
+        latency_ms: float = 0.0,
+        status_code: int = 200,
+        error_type: Optional[str] = None,
+        stack_trace: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Enqueues a telemetry log for non-blocking background dispatch."""
+        item = {
+            "service_id": self.service_name,
+            "runtime": self.runtime,
+            "environment": self.environment,
+            "version": self.version,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": level.upper(),
+            "latency_ms": float(latency_ms),
+            "status_code": int(status_code),
+            "error_type": error_type,
+            "message": message,
+            "stack_trace": stack_trace,
+            "raw_stack_trace": stack_trace,
+            "metadata": metadata or {},
+        }
+        try:
+            self._queue.put_nowait(item)
+        except queue.Full:
+            pass  # Drop under extreme backpressure to protect host app
+
+    def capture_message(
+        self,
+        message: str,
+        level: str = "INFO",
+        latency_ms: float = 0.0,
+        status_code: int = 200,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Dispatches a custom log message with metadata tags."""
+        self.log(
+            level=level,
+            message=message,
+            latency_ms=latency_ms,
+            status_code=status_code,
+            metadata=metadata,
+        )
+
+    def info(self, message: str, latency_ms: float = 0.0, **metadata):
+        self.log("INFO", message, latency_ms=latency_ms, metadata=metadata)
+
+    def warn(self, message: str, latency_ms: float = 0.0, **metadata):
+        self.log("WARN", message, latency_ms=latency_ms, metadata=metadata)
+
+    def error(self, message: str, error_type: str = "ServerError", stack_trace: Optional[str] = None, **metadata):
+        self.log("ERROR", message, error_type=error_type, stack_trace=stack_trace, status_code=500, metadata=metadata)
+
+    def critical(self, message: str, error_type: str = "CriticalFailure", stack_trace: Optional[str] = None, **metadata):
+        self.log("CRITICAL", message, error_type=error_type, stack_trace=stack_trace, status_code=500, metadata=metadata)
+
+
+    def capture_exception(
+        self,
+        exc: BaseException,
+        message: Optional[str] = None,
+        latency_ms: float = 0.0,
+        status_code: int = 500,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Extracts stack trace and error type from an Exception instance and dispatches it."""
+        tb_lines = traceback.format_exception(type(exc), exc, exc.__traceback__)
+        formatted_trace = _sanitize_stack_trace("".join(tb_lines))
+        error_type = exc.__class__.__name__
+        msg = message or str(exc) or error_type
+
+        self.log(
+            level="ERROR",
+            message=msg,
+            latency_ms=latency_ms,
+            status_code=status_code,
+            error_type=error_type,
+            stack_trace=formatted_trace,
+            metadata=metadata,
+        )
+
+    def _install_excepthook(self):
+        """Installs unhandled exception hook to automatically report fatal crashes."""
+        original_hook = sys.excepthook
+
+        def unhandled_handler(exc_type, exc_value, exc_traceback):
+            try:
+                formatted_trace = _sanitize_stack_trace(
+                    "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
+                )
+                self.critical(
+                    message=f"Unhandled crash: {exc_value}",
+                    error_type=exc_type.__name__,
+                    stack_trace=formatted_trace,
+                )
+                time.sleep(0.3)  # Allow flusher thread to flush before shutdown
+            except Exception:
+                pass
+            original_hook(exc_type, exc_value, exc_traceback)
+
+        sys.excepthook = unhandled_handler
+
+    def _send_batch(self, batch: List[Dict[str, Any]]):
+        if not batch:
+            return
+        url = f"{self.endpoint}/api/v1/telemetry/batch"
+        headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": self.api_key,
+            "X-Project-Key": self.api_key,
+        }
+        try:
+            if httpx is not None:
+                with httpx.Client(timeout=5.0) as client:
+                    client.post(url, json={"events": batch}, headers=headers)
+            else:
+                req_data = json.dumps({"events": batch}).encode("utf-8")
+                req = urllib.request.Request(url, data=req_data, headers=headers, method="POST")
+                with urllib.request.urlopen(req, timeout=5.0) as resp:
+                    pass
+        except Exception:
+            pass  # Fail silent to avoid degrading host application
+
+    def flush(self, timeout: float = 2.0):
+        """Flushes all queued items synchronously."""
+        batch = []
+        while not self._queue.empty():
+            try:
+                item = self._queue.get_nowait()
+                batch.append(item)
+            except queue.Empty:
+                break
+        if batch:
+            self._send_batch(batch)
+
+    def _flusher_loop(self):
+        """Background daemon sending buffered logs to AuraTrace Ingestion Gateway."""
+        while self._is_running:
+            batch = []
+            try:
+                item = self._queue.get(timeout=self.flush_interval_seconds)
+                batch.append(item)
+                while len(batch) < self.batch_size:
+                    try:
+                        batch.append(self._queue.get_nowait())
+                    except queue.Empty:
+                        break
+            except queue.Empty:
+                pass
+
+            if batch:
+                self._send_batch(batch)
+
+    def shutdown(self):
+        self._is_running = False
+        if self._worker_thread.is_alive():
+            self._worker_thread.join(timeout=1.0)
+
+
+# Backward compatibility & ergonomic aliases
+AuraTrace = AutoTrace
+TraceClient = AutoTrace
+Trace = AutoTrace
+AutomaticBackendDetection = AutoTrace

auratrace_sdk-2.0.0/auratrace_sdk.egg-info/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: auratrace-sdk
+Version: 2.0.0
+Summary: Official Python Telemetry & AI Diagnostic SDK for AuraTrace Autonomous Backend Diagnostics
+Author-email: Sunil Singh <sunilsinghrajput192@gmail.com>
+Project-URL: Homepage, https://github.com/sunilsingh175/auratrace
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+
+# Trace Python SDK
+
+Official Python telemetry and unhandled crash diagnostics SDK for Trace.
+
+## Quickstart
+
+```python
+from trace_sdk import Trace, TraceMiddleware
+
+# Initialize Trace Client
+trace = Trace(
+    service_id="payment-service",
+    api_key="trace_payment_secret_456",
+    endpoint="http://localhost:8000"
+)
+
+# 1. Log metrics & structured messages
+trace.info("User checkout initiated", latency_ms=45.2, metadata={"user_id": "usr_99"})
+
+# 2. Capture and report caught exceptions
+try:
+    process_payment()
+except Exception as e:
+    trace.capture_exception(e, message="Payment processing failure")
+
+# 3. Use as a FastAPI / Starlette middleware
+# Automatically records latency and reports unhandled exceptions
+app.add_middleware(TraceMiddleware, client=trace)
+```

auratrace_sdk-2.0.0/auratrace_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+auratrace/__init__.py
+auratrace/client.py
+auratrace_sdk.egg-info/PKG-INFO
+auratrace_sdk.egg-info/SOURCES.txt
+auratrace_sdk.egg-info/dependency_links.txt
+auratrace_sdk.egg-info/requires.txt
+auratrace_sdk.egg-info/top_level.txt
+autotrace/__init__.py
+autotrace/client.py
+trace_sdk/__init__.py
+trace_sdk/client.py
+trace_sdk/interceptor.py

auratrace_sdk-2.0.0/auratrace_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

auratrace_sdk-2.0.0/auratrace_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24.0

auratrace_sdk-2.0.0/auratrace_sdk.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+auratrace
+autotrace
+trace_sdk

auratrace_sdk-2.0.0/autotrace/__init__.py

@@ -0,0 +1,18 @@
+"""
+AutoTrace Python SDK
+"""
+
+from auratrace.client import AutoTrace, AuraTrace, TraceClient, Trace, AutomaticBackendDetection
+from auratrace import init, capture_message, capture_exception, flush
+
+__all__ = [
+    "AutoTrace",
+    "AuraTrace",
+    "TraceClient",
+    "Trace",
+    "AutomaticBackendDetection",
+    "init",
+    "capture_message",
+    "capture_exception",
+    "flush",
+]

auratrace_sdk-2.0.0/autotrace/client.py

@@ -0,0 +1,21 @@
+"""
+AutoTrace Python SDK Client Module
+"""
+
+from auratrace.client import (
+    AutoTrace,
+    AuraTrace,
+    TraceClient,
+    Trace,
+    AutomaticBackendDetection,
+    auto_detect_service_name,
+)
+
+__all__ = [
+    "AutoTrace",
+    "AuraTrace",
+    "TraceClient",
+    "Trace",
+    "AutomaticBackendDetection",
+    "auto_detect_service_name",
+]

auratrace_sdk-2.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auratrace-sdk"
+version = "2.0.0"
+authors = [{ name="Sunil Singh", email="sunilsinghrajput192@gmail.com" }]
+description = "Official Python Telemetry & AI Diagnostic SDK for AuraTrace Autonomous Backend Diagnostics"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[tool.setuptools]
+packages = ["autotrace", "auratrace", "trace_sdk"]
+
+[project.urls]
+"Homepage" = "https://github.com/sunilsingh175/auratrace"

auratrace_sdk-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auratrace_sdk-2.0.0/trace_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""
+Trace SDK backward-compatibility module
+"""
+
+from auratrace.client import AuraTrace, TraceClient, Trace, AutomaticBackendDetection
+
+__all__ = ["AuraTrace", "TraceClient", "Trace", "AutomaticBackendDetection"]

auratrace_sdk-2.0.0/trace_sdk/client.py

@@ -0,0 +1,179 @@
+"""
+Trace Python Telemetry Client
+Provides non-blocking async batching, structured logging, and unhandled exception capture.
+"""
+
+import sys
+import time
+import queue
+import threading
+import traceback
+import json
+from datetime import datetime, timezone
+from typing import Optional, Dict, Any, List
+import urllib.request
+import urllib.error
+try:
+    import httpx
+except ImportError:
+    httpx = None
+
+
+
+def _sanitize_stack_trace(trace_str: str) -> str:
+    if not trace_str:
+        return ""
+    import re
+    def _clean_path(match):
+        full_path = match.group(1).replace("\\", "/")
+        parts = full_path.split("/")
+        for marker in ["scripts", "app", "backend", "services", "controllers", "models", "workers"]:
+            if marker in parts:
+                idx = parts.index(marker)
+                return f'File "{"/".join(parts[idx:])}"'
+        if len(parts) > 1:
+            return f'File "{"/".join(parts[-2:])}"'
+        return f'File "{parts[-1]}"'
+    return re.sub(r'File "([^"]+)"', _clean_path, trace_str)
+
+
+class Trace:
+    def __init__(
+        self,
+        service_id: str,
+        api_key: str,
+        endpoint: str = "http://localhost:8000",
+        batch_size: int = 50,
+        flush_interval_seconds: float = 1.0,
+        install_global_hook: bool = True,
+    ):
+        self.service_id = service_id
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.batch_size = batch_size
+        self.flush_interval_seconds = flush_interval_seconds
+
+        self._queue: queue.Queue = queue.Queue(maxsize=10000)
+        self._is_running = True
+        self._worker_thread = threading.Thread(target=self._flusher_loop, daemon=True)
+        self._worker_thread.start()
+
+        if install_global_hook:
+            self._install_excepthook()
+
+    def log(
+        self,
+        level: str,
+        message: str,
+        latency_ms: float = 0.0,
+        error_type: Optional[str] = None,
+        stack_trace: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Enqueues a telemetry log for non-blocking background dispatch."""
+        item = {
+            "service_id": self.service_id,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": level.upper(),
+            "latency_ms": float(latency_ms),
+            "error_type": error_type,
+            "message": message,
+            "stack_trace": stack_trace,
+            "metadata": metadata or {},
+        }
+        try:
+            self._queue.put_nowait(item)
+        except queue.Full:
+            pass  # Drop under extreme backpressure to protect host app
+
+    def info(self, message: str, latency_ms: float = 0.0, **metadata):
+        self.log("INFO", message, latency_ms=latency_ms, metadata=metadata)
+
+    def warn(self, message: str, latency_ms: float = 0.0, **metadata):
+        self.log("WARN", message, latency_ms=latency_ms, metadata=metadata)
+
+    def error(self, message: str, error_type: str = "ServerError", stack_trace: Optional[str] = None, **metadata):
+        self.log("ERROR", message, error_type=error_type, stack_trace=stack_trace, metadata=metadata)
+
+    def critical(self, message: str, error_type: str = "CriticalFailure", stack_trace: Optional[str] = None, **metadata):
+        self.log("CRITICAL", message, error_type=error_type, stack_trace=stack_trace, metadata=metadata)
+
+    def capture_exception(
+        self,
+        exc: BaseException,
+        message: Optional[str] = None,
+        latency_ms: float = 0.0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Extracts stack trace and error type from an Exception instance and dispatches it."""
+        tb_lines = traceback.format_exception(type(exc), exc, exc.__traceback__)
+        formatted_trace = _sanitize_stack_trace("".join(tb_lines))
+        error_type = exc.__class__.__name__
+        msg = message or str(exc) or error_type
+
+        self.log(
+            level="ERROR",
+            message=msg,
+            latency_ms=latency_ms,
+            error_type=error_type,
+            stack_trace=formatted_trace,
+            metadata=metadata,
+        )
+
+    def _install_excepthook(self):
+        """Installs unhandled exception hook to automatically report fatal crashes."""
+        original_hook = sys.excepthook
+
+        def unhandled_handler(exc_type, exc_value, exc_traceback):
+            try:
+                formatted_trace = _sanitize_stack_trace(
+                    "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
+                )
+                self.critical(
+                    message=f"Unhandled crash: {exc_value}",
+                    error_type=exc_type.__name__,
+                    stack_trace=formatted_trace,
+                )
+                time.sleep(0.2)  # Allow flusher thread to flush before shutdown
+            except Exception:
+                pass
+            original_hook(exc_type, exc_value, exc_traceback)
+
+        sys.excepthook = unhandled_handler
+
+    def _flusher_loop(self):
+        """Background daemon sending buffered logs to Trace Ingestion Gateway."""
+        client = httpx.Client(timeout=5.0) if httpx is not None else None
+        url = f"{self.endpoint}/api/v1/telemetry/batch"
+        headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": self.api_key,
+        }
+
+        while self._is_running:
+            batch = []
+            deadline = time.time() + self.flush_interval_seconds
+
+            while len(batch) < self.batch_size and time.time() < deadline:
+                try:
+                    item = self._queue.get(timeout=0.1)
+                    batch.append(item)
+                except queue.Empty:
+                    break
+
+            if batch:
+                try:
+                    if client is not None:
+                        client.post(url, json={"events": batch}, headers=headers)
+                    else:
+                        req_data = json.dumps({"events": batch}).encode("utf-8")
+                        req = urllib.request.Request(url, data=req_data, headers=headers, method="POST")
+                        with urllib.request.urlopen(req, timeout=5.0) as resp:
+                            pass
+                except Exception:
+                    pass  # Fail silent to avoid degrading primary service
+
+    def shutdown(self):
+        self._is_running = False
+        if self._worker_thread.is_alive():
+            self._worker_thread.join(timeout=1.0)

auratrace_sdk-2.0.0/trace_sdk/interceptor.py

@@ -0,0 +1,58 @@
+"""
+Trace Middleware Interceptors for FastAPI / Starlette / Flask
+"""
+
+import time
+import traceback
+from typing import Callable
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from .client import Trace
+
+
+class TraceMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI / Starlette middleware that times requests, captures latency metrics,
+    and reports unhandled 500 exceptions directly to Trace.
+    """
+
+    def __init__(self, app, client: Trace):
+        super().__init__(app)
+        self.client = client
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        start_time = time.perf_counter()
+        method = request.method
+        path = request.url.path
+
+        try:
+            response = await call_next(request)
+            latency_ms = (time.perf_counter() - start_time) * 1000.0
+
+            level = "ERROR" if response.status_code >= 500 else "WARN" if response.status_code >= 400 else "INFO"
+            self.client.log(
+                level=level,
+                message=f"{method} {path} - {response.status_code}",
+                latency_ms=latency_ms,
+                metadata={
+                    "status_code": response.status_code,
+                    "method": method,
+                    "path": path,
+                },
+            )
+            return response
+
+        except Exception as exc:
+            latency_ms = (time.perf_counter() - start_time) * 1000.0
+            tb_str = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+            self.client.critical(
+                message=f"Unhandled Exception in {method} {path}: {str(exc)}",
+                error_type=exc.__class__.__name__,
+                stack_trace=tb_str,
+                latency_ms=latency_ms,
+                path=path,
+                method=method,
+            )
+            raise exc from None