gcmon 0.2.0__py3-none-any.whl

gcmon/__init__.py

@@ -0,0 +1,19 @@
+__version__ = "0.1.0"
+
+from .child_process_runner import ChildProcess, ChildProcessRunner
+from .exporters import EventsExporter, JsonlExporter, StdoutExporter, TraceExporter
+from .monitor import EventsMonitor, create_monitor
+from .monitor_thread import MonitorThread
+
+__all__ = [
+    "ChildProcess",
+    "ChildProcessRunner",
+    "EventsExporter",
+    "EventsMonitor",
+    "JsonlExporter",
+    "MonitorThread",
+    "StdoutExporter",
+    "TraceExporter",
+    "__version__",
+    "create_monitor",
+]

gcmon/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gcmon/_env.py

@@ -0,0 +1,223 @@
+"""Environment variable helpers for CLI defaults."""
+
+import os
+from pathlib import Path
+
+from .stats_output import TableFormat
+
+# Environment variable names for CLI options
+ENV_PREFIX = "GCMON"
+ENV_OUTPUT = f"{ENV_PREFIX}_OUTPUT"
+ENV_RATE = f"{ENV_PREFIX}_RATE"
+ENV_DURATION = f"{ENV_PREFIX}_DURATION"
+ENV_VERBOSE = f"{ENV_PREFIX}_VERBOSE"
+ENV_FORMAT = f"{ENV_PREFIX}_FORMAT"
+ENV_THREAD_ID = f"{ENV_PREFIX}_THREAD_ID"
+ENV_FLUSH_THRESHOLD = f"{ENV_PREFIX}_FLUSH_THRESHOLD"
+ENV_SERVER_HOST = f"{ENV_PREFIX}_SERVER_HOST"
+ENV_SERVER_PORT = f"{ENV_PREFIX}_SERVER_PORT"
+ENV_STATS = f"{ENV_PREFIX}_STATS"
+ENV_TABLE_FORMAT = f"{ENV_PREFIX}_TABLE_FORMAT"
+ENV_CONTROL_NAME = f"{ENV_PREFIX}_CONTROL_NAME"
+
+__all__ = [
+    "ENV_CONTROL_NAME",
+    "ENV_DURATION",
+    "ENV_FLUSH_THRESHOLD",
+    "ENV_FORMAT",
+    "ENV_OUTPUT",
+    "ENV_PREFIX",
+    "ENV_RATE",
+    "ENV_SERVER_HOST",
+    "ENV_SERVER_PORT",
+    "ENV_STATS",
+    "ENV_TABLE_FORMAT",
+    "ENV_THREAD_ID",
+    "ENV_VERBOSE",
+    "get_env_control_name",
+    "get_env_duration",
+    "get_env_flush_threshold",
+    "get_env_format",
+    "get_env_output",
+    "get_env_rate",
+    "get_env_server_host",
+    "get_env_server_port",
+    "get_env_stats",
+    "get_env_table_format",
+    "get_env_thread_id",
+    "get_env_verbose",
+]
+
+
+def get_env_output() -> Path:
+    """Get output path from environment variable.
+
+    Returns:
+        Path from GCMON_OUTPUT env var, or default Path("gcmon.json").
+    """
+    output_str = os.environ.get(ENV_OUTPUT)
+    if output_str:
+        return Path(output_str)
+    # Check format for default filename
+    format_str = os.environ.get(ENV_FORMAT)
+    if format_str and format_str.lower() == "jsonl":
+        return Path("gcmon.jsonl")
+    return Path("gcmon.json")
+
+
+def get_env_rate() -> float:
+    """Get polling rate from environment variable.
+
+    Returns:
+        Rate from GCMON_RATE env var, or default 0.1.
+    """
+    rate_str = os.environ.get(ENV_RATE)
+    if rate_str:
+        try:
+            return float(rate_str)
+        except ValueError:
+            pass
+    return 0.1
+
+
+def get_env_duration() -> float | None:
+    """Get monitoring duration from environment variable.
+
+    Returns:
+        Duration from GCMON_DURATION env var, or None (run until interrupted).
+    """
+    duration_str = os.environ.get(ENV_DURATION)
+    if duration_str:
+        try:
+            return float(duration_str)
+        except ValueError:
+            pass
+    return None
+
+
+def get_env_verbose() -> int:
+    """Get verbose count from environment variable.
+
+    Returns:
+        Verbose count: 0 for no verbose, 1 for INFO, 2+ for DEBUG.
+        GCMON_VERBOSE can be set to a number (e.g., "2") or
+        truthy value ("1", "true", "yes", "on" -> 1).
+    """
+    verbose_str = os.environ.get(ENV_VERBOSE, "").lower()
+    if not verbose_str:
+        return 0
+    # Try to parse as integer first
+    try:
+        return int(verbose_str)
+    except ValueError:
+        pass
+    # Fall back to boolean interpretation
+    if verbose_str in ("1", "true", "yes", "on"):
+        return 1
+    return 0
+
+
+def get_env_format() -> str:
+    """Get output format from environment variable.
+
+    Returns:
+        Format from GCMON_FORMAT env var, or default "chrome".
+    """
+    format_str = os.environ.get(ENV_FORMAT)
+    if format_str:
+        format_lower = format_str.lower()
+        if format_lower in ("chrome", "stdout", "jsonl"):
+            return format_lower
+    return "chrome"
+
+
+def get_env_thread_id() -> int:
+    """Get thread ID from environment variable.
+
+    Returns:
+        Thread ID from GCMON_THREAD_ID env var, or default 0.
+    """
+    thread_id_str = os.environ.get(ENV_THREAD_ID)
+    if thread_id_str:
+        try:
+            return int(thread_id_str)
+        except ValueError:
+            pass
+    return 0
+
+
+def get_env_flush_threshold() -> int:
+    """Get flush threshold from environment variable.
+
+    Returns:
+        Flush threshold from GCMON_FLUSH_THRESHOLD env var, or default 100.
+    """
+    threshold_str = os.environ.get(ENV_FLUSH_THRESHOLD)
+    if threshold_str:
+        try:
+            return int(threshold_str)
+        except ValueError:
+            pass
+    return 100
+
+
+def get_env_server_host() -> str:
+    """Get server host from environment variable.
+
+    Returns:
+        Host from GCMON_SERVER_HOST env var, or default "localhost".
+    """
+    host_str = os.environ.get(ENV_SERVER_HOST)
+    if host_str:
+        return host_str
+    return "localhost"
+
+
+def get_env_server_port() -> int:
+    """Get server port from environment variable.
+
+    Returns:
+        Port from GCMON_SERVER_PORT env var, or default 9999.
+    """
+    port_str = os.environ.get(ENV_SERVER_PORT)
+    if port_str:
+        try:
+            return int(port_str)
+        except ValueError:
+            pass
+    return 9999
+
+
+def get_env_stats() -> bool:
+    """Get stats flag from environment variable.
+
+    Returns:
+        True if GCMON_STATS is set to a truthy value ("1", "true", "yes", "on").
+    """
+    stats_str = os.environ.get(ENV_STATS, "").lower()
+    if not stats_str:
+        return False
+    return stats_str in ("1", "true", "yes", "on")
+
+
+def get_env_control_name() -> str | None:
+    """Get control plane name from environment variable.
+
+    Returns:
+        Name from GCMON_CONTROL_NAME env var, or None.
+    """
+    return os.environ.get(ENV_CONTROL_NAME) or None
+
+
+def get_env_table_format() -> TableFormat:
+    """Get table format from environment variable.
+
+    Returns:
+        TableFormat from GCMON_TABLE_FORMAT env var, or TableFormat.PLAIN.
+    """
+    val = os.environ.get(ENV_TABLE_FORMAT)
+    if val:
+        val = val.lower()
+        if val == "md" or val == "markdown":
+            return TableFormat.MARKDOWN
+    return TableFormat.PLAIN

gcmon/child_process_runner.py

@@ -0,0 +1,237 @@
+import logging
+import os
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Self, override
+
+from .control.control_server import set_control_env
+from .target_process import TargetProcess
+from .utils.process_terminator import log_process_output, terminate_process
+
+__all__ = ["ChildProcess", "ChildProcessRunner"]
+
+logger = logging.getLogger("gcmon")
+
+
+class ChildProcess(TargetProcess):
+    def __init__(self, pid: int):
+        self._pid = pid
+
+    @property
+    @override
+    def pid(self) -> int:
+        return self._pid
+
+class ChildProcessRunner:
+    def __init__(
+        self,
+        target: str,
+        is_module: bool = False,
+        passthrough_args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        control_address: str | None = None,
+    ) -> None:
+        self._target = target
+        self._is_module = is_module
+        self._passthrough_args = passthrough_args or []
+        self._env = env
+        self._control_address = control_address
+        self._process: subprocess.Popen[bytes] | None = None
+        self._stdout_thread: ProcessStdoutReader | None = None
+
+    def _validate_target(self) -> None:
+        if self._is_module:
+            # Module mode: validate module name is not empty
+            if not self._target.strip():
+                raise ValueError("Module name cannot be empty")
+        else:
+            # Script mode: validate file exists and is readable
+            script_path = Path(self._target)
+            if not script_path.exists():
+                raise FileNotFoundError(f"Script not found: {self._target}")
+            if not script_path.is_file():
+                raise ValueError(f"Target is not a file: {self._target}")
+
+    def _build_command(self) -> list[str]:
+        cmd = [sys.executable, "-u"]
+
+        if self._is_module:
+            # Module mode: python -m module_name [args...]
+            cmd.append("-m")
+            cmd.append(self._target)
+        else:
+            # Script mode: python script_path [args...]
+            # Resolve to absolute path to ensure correct execution
+            script_path = str(Path(self._target).resolve())
+            cmd.append(script_path)
+
+        # Add passthrough arguments
+        cmd.extend(self._passthrough_args)
+
+        return cmd
+
+    def _build_env(self) -> dict[str, str]:
+        """Build the environment for the subprocess.
+
+        Returns:
+            Environment dictionary for subprocess
+        """
+        # Start with current environment
+        env = os.environ.copy()
+
+        # Merge custom environment variables
+        if self._env:
+            env.update(self._env)
+
+        # Inject control plane address for child processes
+        if self._control_address is not None:
+            set_control_env(env, self._control_address)
+
+        return env
+
+    def start(self) -> ChildProcess:
+        """Spawn the subprocess and return its PID.
+
+        Returns:
+            Process ID of spawned subprocess
+
+        Raises:
+            FileNotFoundError: If target script doesn't exist (script mode)
+            ValueError: If target is invalid
+            RuntimeError: If subprocess fails to start
+        """
+        # Validate target before spawning
+        self._validate_target()
+
+        # Build command and environment
+        cmd = self._build_command()
+        env = self._build_env()
+
+        logger.debug("Subprocess cmd: %s", " ".join(cmd))
+
+        # Configure subprocess creation flags for cross-platform compatibility
+        creationflags = 0
+        if sys.platform == "win32":
+            # Windows: Create new process group for proper signal handling
+            creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
+
+        try:
+            self._process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                creationflags=creationflags,
+                env=env,
+            )
+        except OSError as e:
+            raise RuntimeError(f"Failed to start subprocess: {e}") from e
+
+        if self._process.poll() is not None:
+            stdout_data, _ = self._process.communicate()
+            stdout_str = stdout_data.decode("utf-8", errors="replace").strip()
+
+            logger.debug("Subprocess exited immediately: %s", stdout_str)
+            raise RuntimeError("Subprocess exited immediately.")
+
+        self._stdout_thread = ProcessStdoutReader(self._process)
+        self._stdout_thread.start()
+        return ChildProcess(self._process.pid)
+
+    @property
+    def process(self) -> subprocess.Popen[bytes] | None:
+        """Return the subprocess handle, or None if not started."""
+        return self._process
+
+    @property
+    def pid(self) -> int | None:
+        """Return the process ID, or None if not started."""
+        return self._process.pid if self._process is not None else None
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the subprocess is still running."""
+        if self._process is not None:
+            return self._process.poll() is None
+
+        return False
+
+    @property
+    def returncode(self) -> int | None:
+        """Return the subprocess exit code, or None if still running."""
+        if self._process is not None:
+            return self._process.poll()
+
+        return None
+
+    def terminate(
+        self,
+        graceful_timeout: float = 5.0,
+        force_timeout: float = 2.0,
+    ) -> bytes:
+        """Terminate the subprocess gracefully.
+
+        Uses escalating signals for graceful shutdown:
+        - SIGINT → SIGTERM → SIGKILL
+        """
+        if self._stdout_thread is not None:
+            self._stdout_thread.stop()
+            self._stdout_thread = None
+
+        if self._process is None:
+            return b""
+
+        # Use the shared terminate_process utility
+        stdout_data, _ = terminate_process(
+            process=self._process,
+            graceful_timeout=graceful_timeout,
+            force_timeout=force_timeout,
+        )
+
+        # Log process output
+        log_process_output(
+            process=self._process,
+            stdout_data=stdout_data,
+        )
+
+        return stdout_data
+
+    def close(self) -> None:
+        self.terminate()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.terminate()
+
+
+class ProcessStdoutReader:
+    def __init__(self, process: subprocess.Popen[bytes]):
+        self._process = process
+        self._stop_event = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run,
+            name=type(self).__qualname__,
+            daemon=True,
+        )
+
+    def start(self) -> None:
+        self._stop_event.clear()
+        self._thread.start()
+
+    def stop(self, timeout: float = 1.0) -> None:
+        self._stop_event.set()
+        self._thread.join(timeout=timeout)
+
+    def _run(self) -> None:
+        pipe = self._process.stdout
+        if pipe is None:
+            return
+
+        for line in iter(pipe.readline, b""):
+            if line:
+                print(line.decode("utf-8", errors="replace"), end="", flush=True)
+            if self._stop_event.is_set():
+                break

gcmon/cli.py

@@ -0,0 +1,127 @@
+"""Command-line interface for gcmon."""
+
+import argparse
+import logging
+import sys
+
+from .commands import (
+    add_combine_parser,
+    add_monitor_parser,
+    add_run_parser,
+)
+
+logger = logging.getLogger("gcmon")
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser with subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="gcmon",
+        description="Monitor Python's garbage collector and export statistics.",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    add_monitor_parser(subparsers.add_parser)
+    add_combine_parser(subparsers.add_parser)
+    add_run_parser(subparsers.add_parser)
+
+    return parser
+
+
+def _setup_logging(verbose_count: int) -> None:
+    """Configure logging for the CLI.
+
+    Args:
+        verbose_count: Verbose level count:
+            0 = WARNING (default)
+            1 = INFO (-v)
+            2+ = DEBUG (-vv or more)
+    """
+    if verbose_count >= 2:
+        level = logging.DEBUG
+    elif verbose_count == 1:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+    logger = logging.getLogger("gcmon")
+    logger.setLevel(level)
+
+    # Only add handler if none exists
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setLevel(level)
+        formatter = logging.Formatter("[%(name)s] %(levelname)s: %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    else:
+        # Update existing handlers
+        for handler in logger.handlers:  # type: ignore[assignment]
+            handler.setLevel(level)
+
+
+def _split_run_args(argv: list[str]) -> tuple[list[str], list[str]]:
+    """Split run command args at the first target option (-m/-s/--module/--script).
+
+    Everything up to and including the target option + value goes to gcmon.
+    Everything after is passed verbatim to the script.
+
+    Args:
+        argv: Command-line arguments starting with "run"
+
+    Returns:
+        Tuple of (gcmon args, script args)
+    """
+    target_options = {"-m", "--module", "-s", "--script"}
+    for i, arg in enumerate(argv):
+        if arg in target_options:
+            # -m value or -s value → split after the value
+            return argv[: i + 2], argv[i + 2 :]
+        if arg.startswith("--module=") or arg.startswith("--script="):
+            # --module=value or --script=value → split after this arg
+            return argv[: i + 1], argv[i + 1 :]
+    # No target option found — all args go to gcmon
+    return argv, []
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for the CLI.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code (0 for success, non-zero for failure)
+    """
+    parser = _create_parser()
+
+    # Check if "run" command is being used - need special handling for script args
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # For run command, split args at the first target option (-m/-s/--module/--script)
+    # Everything before goes to gcmon, everything after goes to the script
+    if argv and argv[0] == "run":
+        gc_args, script_args = _split_run_args(argv)
+        args = parser.parse_args(gc_args)
+        args.script_args = script_args
+    else:
+        args = parser.parse_args(argv)
+
+    # Setup logging before any logging calls
+    _setup_logging(args.verbose)
+
+    # Dispatch via args.func (set by each subparser's set_defaults)
+    if hasattr(args, "func"):
+        return int(args.func(args))
+
+    # No command specified — default to monitor
+    if args.command is None:
+        return main(["monitor", *argv])
+
+    # Unknown command (should not happen due to argparse)
+    logger.error("Unknown command: %s", args.command)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gcmon/commands/__init__.py

@@ -0,0 +1,9 @@
+from .convert_cmd import add_parser as add_combine_parser
+from .monitor_cmd import add_parser as add_monitor_parser
+from .run_cmd import add_parser as add_run_parser
+
+__all__ = [
+    "add_combine_parser",
+    "add_monitor_parser",
+    "add_run_parser",
+]