sgrud 0.1.0__py3-none-any.whl

sgrud/__init__.py

@@ -0,0 +1,45 @@
+"""sgrud: inspect a running CPython process from the outside.
+
+Quick start::
+
+    from sgrud import Monitor
+
+    with Monitor.attach(pid) as m:
+        snap = m.snapshot()
+        print(snap.process.memory.rss, snap.process.cpu_percent)
+        for t in snap.threads:
+            print(t.tid, t.name, t.status.describe(), t.frames[:1])
+"""
+
+from .errors import AttachError, NotSupported, ProcessExited, SgrudError
+from .models import (
+    Awaiter,
+    Frame,
+    GCCollection,
+    GCGeneration,
+    Memory,
+    Process,
+    Snapshot,
+    Task,
+    Thread,
+    ThreadStatus,
+)
+from .monitor import Monitor
+
+__all__ = [
+    "AttachError",
+    "Awaiter",
+    "Frame",
+    "GCCollection",
+    "GCGeneration",
+    "Memory",
+    "Monitor",
+    "NotSupported",
+    "Process",
+    "ProcessExited",
+    "SgrudError",
+    "Snapshot",
+    "Task",
+    "Thread",
+    "ThreadStatus",
+]

sgrud/cli.py

@@ -0,0 +1,198 @@
+"""Command line interface.
+
+    sgrud PID                 one text snapshot
+    sgrud PID -n 0.5          keep printing snapshots every 0.5 s
+    sgrud PID --json          JSON lines instead of text
+    sgrud PID --profile 5     sample stacks for 5 s and print the hottest functions
+    sgrud run -- python app.py    spawn the target as a child, then inspect it
+    sgrud tui PID             interactive Textual interface
+    sgrud tui run -- python app.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+import time
+from collections.abc import Sequence
+
+from . import __name__ as _pkg
+from .errors import SgrudError
+from .format import format_snapshot
+from .monitor import Monitor
+
+
+def _add_target(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "target",
+        help="a pid, or `run -- CMD [ARGS...]` to spawn the target as a child",
+    )
+
+
+def _add_sections(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--no-stacks", action="store_true", help="skip stack traces")
+    parser.add_argument("--no-tasks", action="store_true", help="skip asyncio tasks")
+    parser.add_argument("--no-gc", action="store_true", help="skip GC statistics")
+    parser.add_argument("--no-native", action="store_true", help="hide <native> marker frames")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=_pkg, description=__doc__.split("\n\n")[0])
+    sub = parser.add_subparsers(dest="command")
+
+    dump = sub.add_parser("dump", help="print snapshots (default command)")
+    _add_target(dump)
+    _add_sections(dump)
+    dump.add_argument("-n", "--interval", type=float, default=None,
+                      help="repeat every N seconds until the target exits")
+    dump.add_argument("-c", "--count", type=int, default=None, help="stop after N snapshots")
+    dump.add_argument("--json", action="store_true", help="emit one JSON object per line")
+    dump.add_argument("--max-frames", type=int, default=None, help="frames per thread to show")
+    dump.add_argument("--profile", type=float, metavar="SECONDS", default=None,
+                      help="sample stacks for SECONDS and print a hotspot table instead")
+    dump.add_argument("--rate", type=float, default=200.0, help="samples per second for --profile")
+    dump.add_argument("--sort", choices=("self", "total"), default="self",
+                      help="hotspot ordering for --profile")
+    dump.add_argument("--mode", choices=("wall", "gil"), default="wall",
+                      help="count every thread (wall) or only the GIL holder (gil)")
+
+    tui = sub.add_parser("tui", help="interactive terminal interface")
+    _add_target(tui)
+    _add_sections(tui)
+    tui.add_argument("-n", "--interval", type=float, default=1.0, help="refresh interval")
+    tui.add_argument("--rate", type=float, default=100.0,
+                     help="background stack samples per second for the Hotspots tab, 0 to disable")
+    tui.add_argument("--mode", choices=("wall", "gil"), default="wall",
+                     help="initial hotspot mode, toggle with `m` in the TUI")
+    return parser
+
+
+def open_monitor(target: str, command: Sequence[str], **options) -> Monitor:
+    if target == "run":
+        if not command:
+            raise SgrudError("`run` needs a command after `--`")
+        return Monitor.spawn(list(command), **options)
+    if command:
+        raise SgrudError("a command after `--` only makes sense with `run`")
+    if not target.isdigit():
+        raise SgrudError(f"expected a pid or `run -- CMD`, got {target!r}")
+    return Monitor.attach(int(target), **options)
+
+
+def _dump(args: argparse.Namespace) -> int:
+    sections = dict(stacks=not args.no_stacks, tasks=not args.no_tasks, gc=not args.no_gc)
+    try:
+        monitor = open_monitor(args.target, args.command_argv, native_frames=not args.no_native)
+    except SgrudError as e:
+        print(f"sgrud: {e}", file=sys.stderr)
+        return 1
+    produced = 0
+    if monitor.limited is not None:
+        print(f"sgrud: limited mode, only /proc data is available. {monitor.limited}",
+              file=sys.stderr)
+    try:
+        with monitor:
+            if args.profile is not None:
+                if monitor.limited is not None:
+                    print("sgrud: --profile needs access to the target's memory", file=sys.stderr)
+                    return 1
+                return _profile(monitor, args)
+            if args.interval is None:
+                # A second sample a moment later gives meaningful CPU percentages.
+                monitor.snapshot(stacks=False, tasks=False, gc=False)
+                time.sleep(0.1)
+                snaps = iter([monitor.snapshot(**sections)])
+            else:
+                snaps = monitor.stream(args.interval, **sections)
+            for snap in snaps:
+                if args.json:
+                    print(json.dumps(snap.to_dict(), default=str), flush=True)
+                else:
+                    if produced:
+                        print()
+                    print(
+                        format_snapshot(
+                            snap,
+                            frames=sections["stacks"],
+                            tasks=sections["tasks"],
+                            gc=sections["gc"],
+                            max_frames=args.max_frames,
+                        ),
+                        flush=True,
+                    )
+                produced += 1
+                if args.count is not None and produced >= args.count:
+                    break
+    except SgrudError as e:
+        print(f"sgrud: {e}", file=sys.stderr)
+        return 1 if not produced else 0
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def _profile(monitor: Monitor, args: argparse.Namespace) -> int:
+    from .format import format_hotspots
+    from .sampler import Sampler
+
+    sampler = Sampler(monitor, rate=args.rate, mode=args.mode)
+    with sampler:
+        deadline = time.monotonic() + args.profile
+        while time.monotonic() < deadline and sampler.exited is None:
+            time.sleep(0.05)
+    hot = sampler.hotspots
+    if args.json:
+        rows = [dataclasses.asdict(r) for r in hot.rows(sort=args.sort)]
+        print(json.dumps({"samples": hot.samples, "rate": hot.rate(), "mode": hot.mode,
+                          "errors": sampler.errors, "rows": rows}))
+    else:
+        print(format_hotspots(hot.rows(sort=args.sort), samples=hot.samples, rate=hot.rate(),
+                              mode=hot.mode))
+        if sampler.errors:
+            print(f"({sampler.errors} samples failed, last: {sampler.last_error})")
+    if sampler.exited is not None:
+        print(f"sgrud: {sampler.exited}", file=sys.stderr)
+    return 0
+
+
+def _tui(args: argparse.Namespace) -> int:
+    from .tui import run_tui
+
+    try:
+        monitor = open_monitor(args.target, args.command_argv, native_frames=not args.no_native)
+    except SgrudError as e:
+        print(f"sgrud: {e}", file=sys.stderr)
+        return 1
+    return run_tui(
+        monitor,
+        interval=args.interval,
+        stacks=not args.no_stacks,
+        tasks=not args.no_tasks,
+        gc=not args.no_gc,
+        sample_rate=args.rate,
+        sample_mode=args.mode,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    command_argv: list[str] = []
+    if "--" in argv:
+        cut = argv.index("--")
+        argv, command_argv = argv[:cut], argv[cut + 1 :]
+    if argv and argv[0] not in {"dump", "tui", "-h", "--help"}:
+        argv.insert(0, "dump")
+    args = build_parser().parse_args(argv)
+    args.command_argv = command_argv
+    if args.command == "tui":
+        return _tui(args)
+    if args.command == "dump":
+        return _dump(args)
+    build_parser().print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sgrud/errors.py

@@ -0,0 +1,42 @@
+"""Exceptions raised by sgrud."""
+
+from __future__ import annotations
+
+
+class SgrudError(Exception):
+    """Base class for all sgrud errors."""
+
+
+class ProcessExited(SgrudError):
+    """The target process is gone."""
+
+    def __init__(self, pid: int, returncode: int | None = None):
+        self.pid = pid
+        self.returncode = returncode
+        msg = f"process {pid} has exited"
+        if returncode is not None:
+            msg += f" with code {returncode}"
+        super().__init__(msg)
+
+
+class AttachError(SgrudError):
+    """Could not attach to the target process.
+
+    ``hint`` carries a human readable suggestion on how to fix it.
+    """
+
+    def __init__(
+        self, pid: int, message: str, hint: str | None = None, *, transient: bool = False
+    ):
+        self.pid = pid
+        self.hint = hint
+        #: True when the target may simply still be starting up.
+        self.transient = transient
+        text = f"cannot attach to process {pid}: {message}"
+        if hint:
+            text += f"\n{hint}"
+        super().__init__(text)
+
+
+class NotSupported(SgrudError):
+    """The platform or interpreter lacks a required feature."""

sgrud/format.py

@@ -0,0 +1,168 @@
+"""Plain text rendering of snapshots, shared by the CLI and usable in tests."""
+
+from __future__ import annotations
+
+import math
+import os
+from collections.abc import Iterable
+
+from .models import Frame, Snapshot, Task, Thread
+
+
+def human_bytes(n: int) -> str:
+    value = float(n)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if abs(value) < 1024 or unit == "TiB":
+            return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1024
+    return f"{value:.1f} TiB"
+
+
+def human_duration(seconds: float) -> str:
+    if math.isnan(seconds):
+        return "?"
+    if seconds < 1e-3:
+        return f"{seconds * 1e6:.0f}µs"
+    if seconds < 1:
+        return f"{seconds * 1e3:.1f}ms"
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes, sec = divmod(int(seconds), 60)
+    hours, minutes = divmod(minutes, 60)
+    if hours:
+        return f"{hours}h{minutes:02d}m"
+    return f"{minutes}m{sec:02d}s"
+
+
+def short_path(path: str, keep: int = 2) -> str:
+    if not path or path.startswith("<"):
+        return path
+    parts = path.replace("\\", "/").split("/")
+    return "/".join(parts[-keep:]) if len(parts) > keep else path
+
+
+def percent(value: float | None) -> str:
+    return "  -  " if value is None else f"{value:5.1f}"
+
+
+def format_frames(frames: Iterable[Frame], indent: str = "    ") -> list[str]:
+    lines = []
+    for f in frames:
+        if f.synthetic:
+            lines.append(f"{indent}{f.funcname}")
+        else:
+            lines.append(f"{indent}{f.funcname}  {short_path(f.filename)}:{f.lineno}")
+    return lines
+
+
+def format_thread(t: Thread, *, frames: bool = True, max_frames: int | None = None) -> list[str]:
+    head = (
+        f"[{t.tid}] {t.name:<16} {t.status.describe():<12} state={t.state} "
+        f"cpu={percent(t.cpu_percent)}%  utime={t.user_time:.2f}s stime={t.system_time:.2f}s"
+    )
+    lines = [head]
+    if frames:
+        shown = t.frames if max_frames is None else t.frames[:max_frames]
+        lines.extend(format_frames(shown))
+        if max_frames is not None and len(t.frames) > max_frames:
+            lines.append(f"    ... {len(t.frames) - max_frames} more")
+    return lines
+
+
+def format_task_tree(snap: Snapshot) -> list[str]:
+    children = snap.task_children()
+    by_id = {t.id: t for t in snap.tasks}
+    lines: list[str] = []
+
+    def label(t: Task) -> str:
+        top = t.frames[0].funcname if t.frames else "?"
+        chain = " <- ".join(f.funcname for f in t.frames[:4])
+        return f"{t.name} (0x{t.id:x}) [tid {t.thread_id}] {chain or top}"
+
+    def walk(t: Task, prefix: str, last: bool, seen: set[int]) -> None:
+        branch = "└─ " if last else "├─ "
+        lines.append(f"{prefix}{branch}{label(t)}")
+        if t.id in seen:
+            lines.append(f"{prefix}{'   ' if last else '│  '}(cycle)")
+            return
+        seen = seen | {t.id}
+        kids = children.get(t.id, [])
+        for i, k in enumerate(kids):
+            walk(k, prefix + ("   " if last else "│  "), i == len(kids) - 1, seen)
+
+    roots = children.get(None, [])
+    for i, root in enumerate(roots):
+        walk(root, "", i == len(roots) - 1, set())
+    if not roots and by_id:
+        lines.append("(all tasks are in await cycles)")
+    return lines
+
+
+def format_gc(snap: Snapshot) -> list[str]:
+    lines = []
+    for g in snap.gc:
+        lines.append(
+            f"gen{g.generation}: {g.collections} collections, {g.collected} collected, "
+            f"{g.uncollectable} uncollectable, total {human_duration(g.total_duration)}, "
+            f"heap {g.heap_size}"
+        )
+        for c in g.history[:3]:
+            lines.append(
+                f"    last: {human_duration(c.duration)} collected={c.collected} "
+                f"candidates={c.candidates} heap={c.heap_size}"
+            )
+    return lines
+
+
+def format_snapshot(
+    snap: Snapshot,
+    *,
+    threads: bool = True,
+    frames: bool = True,
+    tasks: bool = True,
+    gc: bool = True,
+    max_frames: int | None = None,
+) -> str:
+    p = snap.process
+    m = p.memory
+    lines = [
+        f"pid {p.pid}  {os.path.basename(p.exe) or '?'}  {' '.join(p.cmdline)[:80]}",
+        f"state={p.state} threads={p.num_threads} uptime={human_duration(p.uptime)} "
+        f"cpu={percent(p.cpu_percent)}%  utime={p.user_time:.2f}s stime={p.system_time:.2f}s",
+        f"rss={human_bytes(m.rss)} vms={human_bytes(m.vms)} hwm={human_bytes(m.hwm)} "
+        f"swap={human_bytes(m.swap)} data={human_bytes(m.data)} shared={human_bytes(m.shared)}",
+    ]
+    if threads:
+        lines.append("")
+        lines.append(f"threads ({len(snap.threads)}):")
+        for t in snap.threads:
+            lines.extend(format_thread(t, frames=frames, max_frames=max_frames))
+    if tasks:
+        lines.append("")
+        lines.append(f"asyncio tasks ({len(snap.tasks)}):")
+        lines.extend(format_task_tree(snap))
+    if gc:
+        lines.append("")
+        lines.append("gc:")
+        lines.extend(format_gc(snap))
+    for section, err in snap.errors.items():
+        lines.append(f"! {section}: {err}")
+    return "\n".join(lines)
+
+
+def format_hotspots(
+    rows, *, samples: int, rate: float | None = None, mode: str = "wall", limit: int = 25
+) -> str:
+    """Render hotspot rows (see :meth:`sgrud.profile.Hotspots.rows`) as a table."""
+    head = f"hotspots ({mode}): {samples} samples"
+    if rate:
+        head += f" at {rate:.0f}/s"
+    lines = [head, f"{'self%':>6} {'total%':>7} {'self':>7} {'total':>7}  function  file"]
+    for r in rows[:limit]:
+        lines.append(
+            f"{r.self_percent:6.1f} {r.total_percent:7.1f} {r.self_samples:7d} "
+            f"{r.total_samples:7d}  {r.funcname}  {short_path(r.filename)}"
+        )
+    if not rows:
+        lines.append("(no samples)")
+    return "\n".join(lines)

sgrud/models.py

@@ -0,0 +1,203 @@
+"""Plain data model for a snapshot of a remote Python process.
+
+Everything here is a frozen dataclass so snapshots can be compared, cached,
+serialized with :func:`dataclasses.asdict` and consumed by any front end
+(CLI, TUI, tests) without touching ``_remote_debugging`` or ``/proc``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class ThreadStatus(enum.IntFlag):
+    """Bit flags reported by ``_remote_debugging`` for each thread."""
+
+    NONE = 0
+    HAS_GIL = 1 << 0
+    ON_CPU = 1 << 1
+    UNKNOWN = 1 << 2
+    GIL_REQUESTED = 1 << 3
+    HAS_EXCEPTION = 1 << 4
+    MAIN_THREAD = 1 << 5
+
+    def describe(self) -> str:
+        """Short human readable label such as ``"gil,cpu"``."""
+        parts = []
+        if self & ThreadStatus.MAIN_THREAD:
+            parts.append("main")
+        if self & ThreadStatus.HAS_GIL:
+            parts.append("gil")
+        elif self & ThreadStatus.GIL_REQUESTED:
+            parts.append("wait-gil")
+        if self & ThreadStatus.ON_CPU:
+            parts.append("cpu")
+        if self & ThreadStatus.HAS_EXCEPTION:
+            parts.append("exc")
+        if self & ThreadStatus.UNKNOWN:
+            parts.append("?")
+        return ",".join(parts) or "idle"
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    """One Python stack frame, or a synthetic ``<native>`` / ``<GC>`` marker."""
+
+    funcname: str
+    filename: str
+    lineno: int | None = None
+    end_lineno: int | None = None
+    col_offset: int | None = None
+    end_col_offset: int | None = None
+
+    @property
+    def synthetic(self) -> bool:
+        return self.lineno is None
+
+    def format(self) -> str:
+        if self.synthetic:
+            return self.funcname
+        return f"{self.funcname} ({self.filename}:{self.lineno})"
+
+
+@dataclass(frozen=True, slots=True)
+class Thread:
+    """An OS thread that belongs to the target interpreter."""
+
+    tid: int
+    name: str
+    interpreter_id: int
+    status: ThreadStatus
+    #: Kernel scheduler state letter from ``/proc`` (R, S, D, ...), or "".
+    state: str
+    user_time: float
+    system_time: float
+    #: CPU usage since the previous snapshot in percent of one core.
+    #: ``None`` for the first snapshot of a monitor.
+    cpu_percent: float | None
+    #: Leaf frame first.
+    frames: tuple[Frame, ...] = ()
+
+    @property
+    def is_main(self) -> bool:
+        return bool(self.status & ThreadStatus.MAIN_THREAD)
+
+
+@dataclass(frozen=True, slots=True)
+class Awaiter:
+    """A task waiting on another task, with the frames of the awaiting coroutine."""
+
+    task_id: int
+    frames: tuple[Frame, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    """An asyncio task discovered in the target process."""
+
+    id: int
+    name: str
+    thread_id: int
+    #: Coroutine call stack, leaf first.
+    frames: tuple[Frame, ...] = ()
+    awaited_by: tuple[Awaiter, ...] = ()
+
+    @property
+    def parent_ids(self) -> tuple[int, ...]:
+        return tuple(a.task_id for a in self.awaited_by)
+
+
+@dataclass(frozen=True, slots=True)
+class GCCollection:
+    """One garbage collection recorded in the target's GC history ring."""
+
+    generation: int
+    interpreter_id: int
+    started_at: int
+    stopped_at: int
+    duration: float
+    collected: int
+    uncollectable: int
+    candidates: int
+    heap_size: int
+
+
+@dataclass(frozen=True, slots=True)
+class GCGeneration:
+    generation: int
+    collections: int
+    collected: int
+    uncollectable: int
+    total_duration: float
+    heap_size: int
+    #: Most recent first.
+    history: tuple[GCCollection, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class Memory:
+    """Process memory figures from ``/proc/<pid>/status``, in bytes."""
+
+    rss: int
+    vms: int
+    hwm: int
+    swap: int
+    data: int
+    shared: int
+
+
+@dataclass(frozen=True, slots=True)
+class Process:
+    pid: int
+    exe: str
+    cmdline: tuple[str, ...]
+    state: str
+    num_threads: int
+    memory: Memory
+    user_time: float
+    system_time: float
+    #: Seconds since the process started.
+    uptime: float
+    #: CPU usage since the previous snapshot in percent of one core.
+    cpu_percent: float | None
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    """A consistent-as-practical picture of the target at one instant."""
+
+    timestamp: float
+    process: Process
+    threads: tuple[Thread, ...] = ()
+    tasks: tuple[Task, ...] = ()
+    gc: tuple[GCGeneration, ...] = ()
+    #: Sections that could not be collected, mapped to the error text.
+    errors: dict[str, str] = field(default_factory=dict)
+
+    def thread(self, tid: int) -> Thread | None:
+        for t in self.threads:
+            if t.tid == tid:
+                return t
+        return None
+
+    def task(self, task_id: int) -> Task | None:
+        for t in self.tasks:
+            if t.id == task_id:
+                return t
+        return None
+
+    def task_children(self) -> dict[int | None, list[Task]]:
+        """Map parent task id (``None`` for roots) to its child tasks."""
+        known = {t.id for t in self.tasks}
+        children: dict[int | None, list[Task]] = {}
+        for t in self.tasks:
+            parents = [p for p in t.parent_ids if p in known] or [None]
+            for p in parents:
+                children.setdefault(p, []).append(t)
+        return children
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)