loopsentry 0.1.0__tar.gz

loopsentry-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+uv.lock
+original_ideaa
+idea
+sentry_logs

loopsentry-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

loopsentry-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: loopsentry
+Version: 0.1.0
+Summary: asyncio Eventloop Blockers Detector/Analyzer.
+Project-URL: Homepage, https://github.com/amzker/loopsentry
+Project-URL: Repository, https://github.com/amzker/loopsentry
+Project-URL: Issues, https://github.com/amzker/loopsentry/issues
+Author-email: amzker <amzker@proton.me>
+Requires-Python: >=3.12
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: aiohttp; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LoopSentry
+
+### **Asyncio Event Loop Blockers Detector & Analyzer**
+- utility for detecting blocking calls in asyncio event loops
+
+![Demo](images/loopsentry_report.png)
+
+### **Installation**
+
+```bash
+uv add loopsentry
+```
+pip way
+
+```bash
+pip install loopsentry
+```
+
+### **Usage**
+1. Basic Usage
+
+```python
+import asyncio
+from loopsentry import LoopSentry
+
+async def main():
+    # start monitoring (default threshold: 0.1s) ie: if blocks is >= 0.1 , it is logged
+    sentry = LoopSentry(threshold=0.1)
+    sentry.start()
+
+    print("Running...")
+    ... # rest of your application
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+2. Use inside Uvicorn/gunicorn workers in fastapi
+- you need to put it inside a `lifespan` context manager , so if you use multiple workers eachh gets their own LoopSentry instance
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from loopsentry import LoopSentry
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    sentry = LoopSentry()
+    sentry.start()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root():
+    return {"message": "I am being monitored!"}
+```
+
+### **Log Analysis**
+
+```bash
+uv run loopsentry analyze -d log_directory
+```
+NOTE: if you used pip to install then
+
+```bash
+loopsentry analyze -d log_directory
+```

loopsentry-0.1.0/README.md

@@ -0,0 +1,68 @@
+# LoopSentry
+
+### **Asyncio Event Loop Blockers Detector & Analyzer**
+- utility for detecting blocking calls in asyncio event loops
+
+![Demo](images/loopsentry_report.png)
+
+### **Installation**
+
+```bash
+uv add loopsentry
+```
+pip way
+
+```bash
+pip install loopsentry
+```
+
+### **Usage**
+1. Basic Usage
+
+```python
+import asyncio
+from loopsentry import LoopSentry
+
+async def main():
+    # start monitoring (default threshold: 0.1s) ie: if blocks is >= 0.1 , it is logged
+    sentry = LoopSentry(threshold=0.1)
+    sentry.start()
+
+    print("Running...")
+    ... # rest of your application
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+2. Use inside Uvicorn/gunicorn workers in fastapi
+- you need to put it inside a `lifespan` context manager , so if you use multiple workers eachh gets their own LoopSentry instance
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from loopsentry import LoopSentry
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    sentry = LoopSentry()
+    sentry.start()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root():
+    return {"message": "I am being monitored!"}
+```
+
+### **Log Analysis**
+
+```bash
+uv run loopsentry analyze -d log_directory
+```
+NOTE: if you used pip to install then
+
+```bash
+loopsentry analyze -d log_directory
+```

loopsentry-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loopsentry"
+version = "0.1.0"
+description = "asyncio Eventloop Blockers Detector/Analyzer."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "amzker", email = "amzker@proton.me" }]
+dependencies = [
+    "psutil>=6.0.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+loopsentry = "loopsentry.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "requests",
+    "aiohttp",
+]
+
+[project.urls]
+Homepage = "https://github.com/amzker/loopsentry"
+Repository = "https://github.com/amzker/loopsentry"
+Issues = "https://github.com/amzker/loopsentry/issues"
+
+[tool.uv.workspace]
+members = [
+    ".",
+]
+
+[tool.uv.sources]
+loopsentry = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "loopsentry",
+]

loopsentry-0.1.0/src/loopsentry/__init__.py

@@ -0,0 +1,3 @@
+from .monitor import LoopSentry
+
+__all__ = ["LoopSentry"]

loopsentry-0.1.0/src/loopsentry/analyzer.py

@@ -0,0 +1,204 @@
+import json
+import time
+import re
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich import box
+from rich.prompt import Prompt
+
+console = Console()
+
+class Analyzer:
+    def __init__(self, path):
+        self.path = Path(path)
+        self.blocks = []
+        self.stats = {"total_time": 0.0, "count": 0, "crashes": 0}
+
+    def _analyze_heuristics(self, stack_list):
+        stack_str = "".join(stack_list).lower()
+        if "time.sleep" in stack_str: return "Blocking Sleep"
+        if "requests." in stack_str: return "Sync HTTP (requests)"
+        if "subprocess.run" in stack_str: return "Sync Subprocess"
+        if "while" in stack_str and "sleep" not in stack_str: return "⚠ CPU Loop?"
+        return "LOGIC_BLOCK: Review Logic"
+
+    def run(self):
+        files = [self.path] if self.path.is_file() else list(self.path.rglob("*.jsonl"))
+        
+        for f in files:
+            with open(f, 'r', encoding="utf-8") as handle:
+                current_block = None
+                for line in handle:
+                    try:
+                        entry = json.loads(line)
+                        if entry['type'] == 'block_started':
+                            if current_block:
+                                current_block['total_duration'] = "TRANSITION"
+                                current_block['resolved'] = True
+                                self.blocks.append(current_block)
+                            current_block = entry
+                        elif entry['type'] == 'block_resolved' and current_block:
+                            current_block['total_duration'] = entry['duration_current']
+                            current_block['resolved'] = True
+                            current_block['hint'] = self._analyze_heuristics(current_block['stack'])
+                            self.blocks.append(current_block)
+                            
+                            if isinstance(entry['duration_current'], float):
+                                self.stats['total_time'] += entry['duration_current']
+                            self.stats['count'] += 1
+                            current_block = None
+                    except Exception:
+                        continue
+                
+                if current_block:
+                    current_block['total_duration'] = "CRASH"
+                    current_block['resolved'] = False
+                    current_block['hint'] = "Crash/Kill"
+                    self.blocks.append(current_block)
+                    self.stats['crashes'] += 1
+
+        self.blocks.sort(key=lambda x: x['timestamp'], reverse=True)
+
+    def _parse_location(self, trigger_str):
+        match = re.search(r'File "(.*?)", line (\d+)', trigger_str)
+        if match:
+            # abs path for IDE clickability
+            fname = match.group(1)
+            lineno = match.group(2)
+            return f"{Path(fname).name}:{lineno}", fname
+        return "Unknown", ""
+
+    def interactive_tui(self):
+        filter_term = ""
+        
+        while True:
+            console.clear()
+            title = f"[bold cyan]LoopSentry Analysis[/]"
+            if filter_term:
+                title += f" [bold yellow](Filter: '{filter_term}')[/]"
+            
+            console.rule(title)
+            
+            display_blocks = []
+            for idx, b in enumerate(self.blocks):
+                b['_id'] = idx + 1
+                searchable_text = (b.get('hint', '') + "".join(b['stack']) + b.get('trigger', '')).lower()
+                if not filter_term or filter_term in searchable_text:
+                    display_blocks.append(b)
+
+            grid = Table.grid(expand=True)
+            grid.add_column(justify="center", ratio=1)
+            grid.add_column(justify="center", ratio=1)
+            grid.add_column(justify="center", ratio=1)
+            grid.add_row(
+                Panel(f"[bold red]{len(display_blocks)}/{self.stats['count']}[/]", title="Blocks Shown"),
+                Panel(f"[bold yellow]{self.stats['total_time']:.2f}s[/]", title="Total Lost Time"),
+                Panel(f"[bold magenta]{self.stats['crashes']}[/]", title="Crashes"),
+            )
+            console.print(grid)
+            
+            table = Table(title="Event Log", box=box.SIMPLE_HEAD, expand=True)
+            table.add_column("ID", style="bold white", width=4, justify="right")
+            table.add_column("Time", style="cyan", width=10)
+            table.add_column("Dur", style="red", width=10)
+            table.add_column("Hint", style="yellow")
+            table.add_column("Location", style="blue")
+
+            for b in display_blocks[:100]:
+                dur = b['total_duration']
+                dur_fmt = f"{dur:.4f}s" if isinstance(dur, float) else "CRASH"
+                short_loc, full_path = self._parse_location(b.get('trigger', ''))
+                
+                table.add_row(str(b['_id']), b['timestamp'][11:19], dur_fmt, b.get('hint', ''), short_loc)
+            
+            if len(display_blocks) > 15:
+                table.add_row("...", "...", "...", "...", f"And {len(display_blocks)-15} more...")
+
+            console.print(table)
+            console.print("\n[dim]Commands: [white]<ID>[/] for detail | [white]<text>[/] to search | [white]reset[/] | [white]q[/]uit[/dim]")
+            
+            choice = Prompt.ask("Action")
+            
+            if choice.lower() in ('q', 'quit', 'exit'): break
+            if choice.lower() in ('reset', 'clean', 'clear'): 
+                filter_term = ""
+                continue
+            
+            if choice.isdigit():
+                selected_id = int(choice)
+                if 1 <= selected_id <= len(self.blocks):
+                    self._show_detail(self.blocks[selected_id - 1])
+                else:
+                    console.print("[red]ID out of range[/red]")
+                    time.sleep(0.5)
+            else:
+                filter_term = choice.lower()
+
+    def _show_detail(self, block):
+        console.clear()
+        dur = block['total_duration']
+        dur_str = f"{dur:.4f}s" if isinstance(dur, float) else "CRASH"
+        
+        console.rule(f"[bold red]Event Detail - {dur_str}")
+        
+        info_table = Table(show_header=False, box=None)
+        info_table.add_column(style="bold cyan")
+        info_table.add_column()
+        info_table.add_row("Timestamp:", block['timestamp'])
+        info_table.add_row("PID:", str(block['pid']))
+        info_table.add_row("Hint:", f"[yellow]{block.get('hint')}[/yellow]")
+        
+        _, full_path = self._parse_location(block.get('trigger', ''))
+        info_table.add_row("Trigger File:", f"file://{full_path}" if full_path else "Unknown")
+        
+        console.print(Panel(info_table, title="Metadata", border_style="blue"))
+        
+        stack_code = "".join(block['stack'])
+        syntax = Syntax(stack_code, "python", theme="monokai", line_numbers=True, word_wrap=True)
+        console.print(Panel(syntax, title="Stack Trace", border_style="red"))
+        
+        Prompt.ask("\n[dim]Press [bold]Enter[/] to return...[/dim]")
+
+    def render_html(self):
+        json_data = json.dumps(self.blocks)
+        html_template = f"""
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>LoopSentry Report</title>
+    <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <style> [v-cloak] {{ display: none; }} body {{ background: #0f172a; color: #e2e8f0; }} pre {{ font-family: 'Fira Code', monospace; }} </style>
+</head>
+<body class="p-6">
+    <div id="app" v-cloak class="max-w-7xl mx-auto">
+        <h1 class="text-3xl font-bold text-blue-400 mb-8">LoopSentry Report</h1>
+        <input v-model="search" placeholder="Filter logs..." class="w-full bg-slate-800 border border-slate-700 rounded p-3 mb-6">
+        <div class="space-y-4">
+            <div v-for="(b, i) in filteredBlocks" :key="i" class="bg-slate-800 rounded border-l-4 p-4" :class="b.resolved ? 'border-yellow-500' : 'border-red-600'">
+                <div class="flex justify-between font-mono text-sm mb-2 cursor-pointer" @click="b.expanded = !b.expanded">
+                    <span :class="b.resolved ? 'text-yellow-400' : 'text-red-400'">{{{{ typeof b.total_duration === 'number' ? b.total_duration.toFixed(4) + 's' : b.total_duration }}}}</span>
+                    <span class="text-slate-500">{{{{ b.timestamp.split('T')[1].slice(0,8) }}}}</span>
+                </div>
+                <div class="text-slate-400 text-xs mb-2">{{{{ b.hint }}}}</div>
+                <pre v-if="b.expanded" class="bg-black/30 p-2 rounded text-xs text-slate-300 overflow-x-auto">{{{{ b.stack.join('') }}}}</pre>
+            </div>
+        </div>
+    </div>
+    <script>
+        const {{ createApp }} = Vue;
+        createApp({{
+            data() {{ return {{ blocks: {json_data}.map(b => ({{...b, expanded: false}})), search: '' }} }},
+            computed: {{ filteredBlocks() {{ return this.blocks.filter(b => (b.trigger+b.hint+b.stack.join('')).toLowerCase().includes(this.search.toLowerCase())) }} }}
+        }}).mount('#app');
+    </script>
+</body>
+</html>
+        """
+        with open("loopsentry_report.html", "w", encoding="utf-8") as f: f.write(html_template)
+        console.print(f"[green]Report: loopsentry_report.html[/green]")

loopsentry-0.1.0/src/loopsentry/cli.py

@@ -0,0 +1,48 @@
+import argparse
+import sys
+import shutil
+from pathlib import Path
+from rich.console import Console
+from .analyzer import Analyzer
+
+console = Console()
+
+def main():
+    parser = argparse.ArgumentParser(description="LoopSentry: Asyncio Event Loop Monitor")
+    subparsers = parser.add_subparsers(dest="command")
+    
+    subparsers.add_parser("clean", help="Clear logs")
+    
+    an_parser = subparsers.add_parser("analyze", help="Analyze logs")
+    an_parser.add_argument("-d", "--dir")
+    an_parser.add_argument("-f", "--file")
+    an_parser.add_argument("--html", action="store_true")
+
+    args = parser.parse_args()
+
+    if args.command == "clean":
+        if Path("sentry_logs").exists():
+            shutil.rmtree("sentry_logs")
+            console.print("[green]✔ Logs cleared.[/green]")
+        else:
+            console.print("[yellow]No logs found.[/yellow]")
+
+    elif args.command == "analyze":
+        target = args.file if args.file else args.dir
+        if not target:
+            dirs = sorted(Path("sentry_logs").glob("*"))
+            if dirs: target = dirs[-1]
+            else: 
+                console.print("[red]No logs found.[/red]")
+                return
+
+        analyzer = Analyzer(target)
+        analyzer.run()
+        if args.html: analyzer.render_html()
+        else: analyzer.interactive_tui()
+    
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

loopsentry-0.1.0/src/loopsentry/monitor.py

@@ -0,0 +1,146 @@
+import asyncio
+import time
+import threading
+import sys
+import traceback
+import json
+import os
+import signal
+from datetime import datetime
+from pathlib import Path
+from rich.console import Console
+
+console = Console()
+
+try:
+    import psutil
+    PSUTIL_AVAILABLE = True
+except ImportError:
+    PSUTIL_AVAILABLE = False
+
+class LoopSentry:
+    def __init__(self, base_dir="sentry_logs", threshold=0.1):
+        self.threshold = threshold
+        self.running = False
+        self._last_tick = 0
+        self._is_blocking = False
+        self._stop_event = threading.Event()
+        
+        self._segment_start_time = 0
+        self._last_stack_signature = None
+        
+        date_str = datetime.now().strftime("%Y-%m-%d")
+        self.log_dir = Path(base_dir) / date_str
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        
+        self.pid = os.getpid()
+        self.log_file = self.log_dir / f"sentry_{self.pid}.jsonl"
+        self._file_handle = open(self.log_file, "a", encoding="utf-8")
+        
+        self.process = psutil.Process(self.pid) if PSUTIL_AVAILABLE else None
+
+    def start(self):
+        if self.running: return
+        self.running = True
+        self._last_tick = time.time()
+        
+        try:
+            signal.signal(signal.SIGINT, self._signal_handler)
+            signal.signal(signal.SIGTERM, self._signal_handler)
+        except ValueError:
+            pass
+
+        asyncio.get_event_loop().call_soon(self._ticker)
+        
+        self.thread = threading.Thread(target=self._watchdog, daemon=True, name="LoopSentry-Watchdog")
+        self.thread.start()
+        
+        console.print(f"[green]✔ LoopSentry Pro Active.[/green] [dim]PID: {self.pid} | Log: {self.log_file}[/dim]")
+
+    def _signal_handler(self, signum, frame):
+        self.running = False
+        self._stop_event.set()
+        if self._file_handle:
+            self._file_handle.flush()
+            self._file_handle.close()
+        sys.exit(0)
+
+    def _ticker(self):
+        self._last_tick = time.time()
+        if self.running:
+            asyncio.get_event_loop().call_later(self.threshold / 2, self._ticker)
+
+    def _watchdog(self):
+        while self.running and not self._stop_event.is_set():
+            time.sleep(self.threshold)
+            now = time.time()
+            delta = now - self._last_tick
+            
+            if delta > self.threshold:
+                snapshot = self._capture_state()
+                current_signature = "".join(snapshot['stack'])
+                
+                if not self._is_blocking:
+                    self._is_blocking = True
+                    self._segment_start_time = now - self.threshold
+                    self._last_stack_signature = current_signature
+                    self._write_event("block_started", snapshot, duration=delta)
+                    console.print(f"[bold red] Block Detected![/bold red] ({delta:.2f}s)")
+                
+                elif current_signature != self._last_stack_signature:
+                    segment_duration = now - self._segment_start_time
+                    self._write_event("block_resolved", {}, duration=segment_duration)
+                    
+                    self._segment_start_time = now
+                    self._last_stack_signature = current_signature
+                    self._write_event("block_started", snapshot, duration=delta)
+                    console.print(f"[bold red]>>> Block Shift Detected![/bold red]")
+
+            else:
+                if self._is_blocking:
+                    self._is_blocking = False
+                    segment_duration = now - self._segment_start_time
+                    self._write_event("block_resolved", {}, duration=segment_duration)
+                    console.print(f"[green]✔ Recovered.[/green]")
+                    self._last_stack_signature = None
+
+    def _capture_state(self):
+        data = {
+            "timestamp": datetime.now().isoformat(),
+            "stack": [],
+            "trigger": "Unknown",
+            "sys": { "cpu_percent": 0.0, "memory_mb": 0.0, "thread_count": threading.active_count() }
+        }
+        try:
+            main_id = threading.main_thread().ident
+            frames = sys._current_frames()
+            frame = frames.get(main_id)
+            if frame:
+                stack = traceback.format_stack(frame)
+                data["stack"] = stack
+                data["trigger"] = stack[-1].strip() if stack else "Unknown"
+        except Exception:
+            data["stack"] = ["Error capturing stack"]
+
+        if self.process:
+            try:
+                with self.process.oneshot():
+                    data["sys"]["cpu_percent"] = self.process.cpu_percent()
+                    data["sys"]["memory_mb"] = self.process.memory_info().rss / 1024 / 1024
+            except Exception:
+                pass     
+        return data
+
+    def _write_event(self, event_type, data, duration=0.0):
+        entry = {
+            "type": event_type,
+            "pid": self.pid,
+            "timestamp": datetime.now().isoformat(),
+            "duration_current": duration,
+            **data
+        }
+        try:
+            self._file_handle.write(json.dumps(entry) + "\n")
+            self._file_handle.flush()
+        except Exception:
+            pass