proctrace 0.1.0__tar.gz

proctrace-0.1.0/.cargo/config.toml

@@ -0,0 +1,9 @@
+[build]
+# On macOS, the linker needs this to correctly set the install name of the .dylib
+# so Python can find it regardless of where the venv is installed.
+# On Linux this has no effect.
+[target.x86_64-apple-darwin]
+rustflags = ["-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup"]
+
+[target.aarch64-apple-darwin]
+rustflags = ["-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup"]

proctrace-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Rust (stable)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: Cache Rust build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.toml') }}
+
+      - name: Install Python build tools
+        run: pip install maturin>=1.5 pytest>=8 pytest-asyncio twine
+
+      - name: Build and install (maturin develop)
+        run: maturin develop --release
+
+      - name: Install package in editable mode
+        run: pip install -e ".[dev]"
+
+      - name: Run Clippy (Rust linter)
+        run: cargo clippy -- -D warnings
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Build release wheel
+        run: maturin build --release
+
+      - name: Check wheel
+        run: python -m twine check target/wheels/*.whl

proctrace-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Rust build artifacts
+target/
+Cargo.lock
+
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# maturin build output
+*.so
+*.pyd
+*.dylib
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+/research-doc
+
+# proctrace runtime files
+proctrace.log
+/tmp/proctrace-*.pipe
+
+# macOS
+.DS_Store

proctrace-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.1.0] — 2026-08-12
+
+### Added
+- `proctrace.watch()` context manager: monitor memory, fd, thread, child process deltas
+- `@proctrace.probe()` decorator: wraps sync and async functions
+- `proctrace.install_signal_handler()`: SIGUSR1-triggered thread + asyncio dump
+- `proctrace.trace_ipc(queue)`: latency and depth tracking for queues
+- `proctrace.trace_pipe(r, w)`: latency tracking for pipe pairs
+- `proctrace.trace_socket(sock)`: send latency + recv buffer utilization for sockets
+- `proctrace.ipc_report()`: human-readable IPC channel summary
+- `ProctraceLogger`: JSONL structured logging for ResourceDelta events
+- `pytest-proctrace` plugin: per-test resource tracking via `--proctrace`
+- `proctrace` CLI: `run`, `dump`, `watch` subcommands
+- Linux backend: `/proc/self/status`, `/proc/self/fd`
+- macOS backend: `proc_pidinfo(PROC_PIDTASKINFO)`, `fcntl(F_GETPATH)`
+- Background Rust sampler thread for peak RSS tracking
+- Zero runtime Python dependencies
+
+### Platform support
+- Linux: ✓ (primary development platform)
+- macOS: ✓ (tested on arm64 and x86_64)
+- Windows: ✗ (no `/proc`, no `POSIX signals`)

proctrace-0.1.0/Cargo.lock

@@ -0,0 +1,165 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tap"
+version = "0.1.0"
+dependencies = [
+ "libc",
+ "pyo3",
+ "thiserror",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"

proctrace-0.1.0/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "tap"
+version = "0.1.0"
+edition = "2021"
+authors = ["arif39x,aliarif1168@gmail.com"]
+description = "Process introspection for humans."
+license = "MIT"
+readme = "README.md"
+
+[lib]
+name = "_proctrace_core"
+crate-type = ["cdylib"]
+
+[dependencies]
+libc = "0.2"
+pyo3 = { version = "0.29", features = ["extension-module"] }
+thiserror = "2"
+
+[profile.release]
+lto = true
+opt-level = 3
+codegen-units = 1

proctrace-0.1.0/GUIDE.md

@@ -0,0 +1,323 @@
+# proctrace — Developer Guide
+
+> Non-invasive process and OS-state introspection for Python.  
+> Diagnose memory leaks, FD leaks, race conditions, and IPC bottlenecks with a single import.
+
+---
+
+## Table of Contents
+
+1. [Architecture](#architecture)
+2. [How to Use proctrace](#how-to-use-proctrace)
+   - [Installation](#installation)
+   - [Context Manager (watch)](#context-manager-watch)
+   - [Decorator (@probe)](#decorator-probe)
+   - [IPC Tracing](#ipc-tracing)
+   - [On-demand Stack Dumps](#on-demand-stack-dumps)
+   - [CLI](#cli)
+3. [API Reference](#api-reference)
+4. [Code Snippets](#code-snippets)
+
+---
+
+## Architecture
+
+proctrace is a **two-layer library**: a compiled Rust extension provides the low-level OS sampling, and a pure-Python layer offers the ergonomic API surface developers actually interact with.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Your Python Code                         │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │  import proctrace
+┌─────────────────────────▼───────────────────────────────────────┐
+│                  Python Public API Layer                        │
+│                                                                 │
+│   watch() / ResourceWatcher       @probe decorator              │
+│   trace_ipc / trace_pipe / trace_socket / ipc_report            │
+│   install_signal_handler()                                      │
+│                                                                 │
+│   proctrace/__init__.py                                         │
+│   proctrace/watch.py          proctrace/decorators.py           │
+│   proctrace/ipc.py            proctrace/snapshot.py             │
+│   proctrace/_types.py         (ResourceDelta dataclass)         │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │  PyO3 FFI boundary
+┌─────────────────────────▼───────────────────────────────────────┐
+│                  Rust Core Extension                            │
+│              (_proctrace_core.cpython-*.so)                     │
+│                                                                 │
+│   resources.rs    — snapshot_resources(), list_open_fds()       │
+│   sampler.rs      — BackgroundSampler (peak RSS thread)         │
+│   ipc_probe.rs    — IpcStats, SocketStats                       │
+│   signal.rs       — register_signal_pipe()                      │
+│   lib.rs          — PyO3 module root                            │
+└─────────────────────────────────────────────────────────────────┘
+                          │
+                     Linux /proc
+                     (macOS sysctl)
+```
+
+### Component Breakdown
+
+| Component | File | Responsibility |
+|---|---|---|
+| `ResourceWatcher` | `watch.py` | Context manager; snapshots resources before/after a block; runs `BackgroundSampler` in the background |
+| `BackgroundSampler` | `sampler.rs` | Rust thread that polls RSS on a configurable interval to capture the **peak** |
+| `ResourceDelta` | `_types.py` | Pure-Python dataclass holding all measurements; serialises to/from dict/JSON |
+| `@probe` decorator | `decorators.py` | Wraps sync and async functions with a `ResourceWatcher`; optionally stores result on `fn.last_probe_result` |
+| IPC tracers | `ipc.py` | Thin wrappers around `queue.Queue`, OS pipes, and `socket` that record latency and throughput via `IpcStats`/`SocketStats` |
+| Signal handler | `snapshot.py` | Installs a self-pipe trick via `register_signal_pipe()` (Rust); a daemon thread reads it and dumps all Python thread stacks + asyncio tasks |
+| CLI | `cli.py` | `proctrace run / watch / dump` subcommands |
+| Rust extension | `src/` | Compiled `.so`; exposes `snapshot_resources`, `list_open_fds`, `BackgroundSampler`, `IpcStats`, `SocketStats`, `register_signal_pipe`, `probe_version` |
+
+### Data Flow — `watch()` block
+
+```
+__enter__
+  │
+  ├─ snapshot_resources()         ← Rust: reads /proc/self/status
+  ├─ list_open_fds()              ← Rust: reads /proc/self/fd/
+  ├─ threading.enumerate()        ← Python stdlib
+  ├─ _count_children()            ← /proc/.../children or pgrep
+  └─ BackgroundSampler.start()    ← Rust thread spawned
+
+  [ your code runs ]
+
+__exit__
+  │
+  ├─ BackgroundSampler.stop()     → returns peak_rss_bytes
+  ├─ snapshot_resources()         ← after snapshot
+  ├─ list_open_fds()              ← after FD list
+  ├─ threading.enumerate()        ← after thread list
+  └─ ResourceDelta(...)           ← computed and stored on .result
+```
+
+---
+
+## How to Use proctrace
+
+### Installation
+
+```bash
+pip install proctrace
+```
+
+Build from source (requires Rust + `maturin`):
+
+```bash
+pip install maturin
+maturin develop --release
+```
+
+**Requirements:** Python >= 3.10 · Linux or macOS
+
+---
+
+### Context Manager (`watch`)
+
+The simplest entry point. Wrap any block to measure its resource footprint.
+
+```python
+import proctrace
+
+with proctrace.watch() as probe:
+    do_work()
+
+print(probe.result.report())
+```
+
+**Parameters of `proctrace.watch()`:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `memory` | `bool` | `True` | Track RSS and VMS memory |
+| `fds` | `bool` | `True` | Track open file descriptors |
+| `threads` | `bool` | `True` | Track thread count and names |
+| `children` | `bool` | `True` | Track child process count |
+| `sample_interval` | `float` | `0.1` | Background peak-RSS poll interval (seconds) |
+
+After the `with` block, `probe.result` is a `ResourceDelta`.
+
+---
+
+### Decorator (`@probe`)
+
+Attach resource tracking to any function — sync or async — without changing its call site.
+
+```python
+from proctrace.decorators import probe
+
+@probe(memory=True, fds=True, output="stderr")
+def load_dataset(path: str) -> list:
+    ...
+
+load_dataset("data.csv")
+
+# Access the result afterwards
+delta = load_dataset.last_probe_result
+print(f"RSS grew by {delta.rss_delta_mb:.2f} MB")
+```
+
+**Parameters of `@probe()`:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `memory` | `bool` | `True` | Track RSS / VMS |
+| `fds` | `bool` | `True` | Track file descriptors |
+| `threads` | `bool` | `True` | Track threads |
+| `children` | `bool` | `False` | Track child processes |
+| `sample_interval` | `float` | `0.05` | Background sampler interval |
+| `output` | `"stderr"` or `"none"` | `"stderr"` | Print report automatically |
+| `store` | `bool` | `True` | Store result on `fn.last_probe_result` |
+
+Works identically on `async def` functions.
+
+---
+
+### IPC Tracing
+
+Wrap queues, pipes, and sockets to collect latency and throughput metrics.
+
+```python
+import queue, os, socket
+from proctrace.ipc import trace_ipc, trace_pipe, trace_socket, ipc_report
+
+# Queues
+q = trace_ipc(queue.Queue(), name="task-queue")
+q.put(item)
+item = q.get()
+
+# OS pipes
+r_fd, w_fd = os.pipe()
+pipe = trace_pipe(r_fd, w_fd, name="my-pipe")
+pipe.write(b"hello")
+data = pipe.read(5)
+
+# Sockets
+raw_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+sock = trace_socket(raw_sock, name="worker-conn")
+sock.sendall(b"ping")
+resp = sock.recv(1024)
+
+# Print aggregated report for all traced channels
+print(ipc_report())
+```
+
+All traced wrappers are transparent — they support the same interface as their underlying object.
+
+---
+
+### On-demand Stack Dumps
+
+Install a signal handler so you can trigger a full thread + asyncio task dump at any time without stopping the process.
+
+```python
+import proctrace
+
+proctrace.install_signal_handler(sig="SIGUSR1")
+
+# From another terminal:
+#   kill -USR1 <pid>
+```
+
+**Parameters of `install_signal_handler()`:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `sig` | `str` | `"SIGUSR1"` | Signal to listen for (`SIGUSR1`, `SIGUSR2`, `SIGALRM`) |
+| `output` | `str` or `IO` | `"stderr"` | `"stderr"`, a file path string, or a file-like object |
+| `include_asyncio` | `bool` | `True` | Also dump asyncio tasks |
+| `loop` | `EventLoop or None` | `None` | Specific loop to inspect; auto-detected if `None` |
+
+The dump includes a timestamped header, each thread's last 10 stack frames, and up to 5 frames per asyncio task.
+
+---
+
+### CLI
+
+```
+proctrace <subcommand> [options]
+```
+
+#### `proctrace run` — measure a subprocess
+
+```bash
+proctrace run -- python myscript.py
+proctrace run --json -- python myscript.py   # JSON to stdout
+```
+
+#### `proctrace watch` — live memory polling
+
+```bash
+proctrace watch --pid <PID> --interval 1.0 --duration 30
+```
+
+Prints a live-updating table of RSS and VMS (MB) for the target process.
+
+#### `proctrace dump` — trigger a stack dump
+
+```bash
+proctrace dump --pid <PID> --signal SIGUSR1
+```
+
+Sends a signal to a running proctrace-instrumented process to trigger a thread dump on its stderr.
+
+---
+
+## API Reference
+
+### `ResourceDelta`
+
+A dataclass produced after every measurement. All fields reflect the **delta** between entry and exit of the watched block.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `rss_delta_bytes` | `int` | RSS change in bytes (can be negative) |
+| `vms_delta_bytes` | `int` | Virtual memory size change |
+| `fd_delta` | `int` | Open file descriptor count change |
+| `peak_rss_bytes` | `int` | Highest RSS observed by the background sampler |
+| `thread_delta` | `int` | Thread count change |
+| `child_delta` | `int` | Child process count change |
+| `elapsed_ns` | `int` | Wall-clock time of block in nanoseconds |
+| `leaked_fds` | `list[str]` | FD paths open at exit but not at entry |
+| `new_thread_names` | `list[str]` | Names of threads created during the block |
+
+**Convenience properties:**
+
+| Property | Returns |
+|---|---|
+| `.rss_delta_mb` | `float` — RSS delta in megabytes |
+| `.vms_delta_mb` | `float` — VMS delta in megabytes |
+| `.peak_rss_mb` | `float` — Peak RSS in megabytes |
+| `.elapsed_ms` | `float` — Elapsed time in milliseconds |
+
+**Serialization:**
+
+```python
+d    = delta.to_dict()           # -> dict[str, Any]
+j    = delta.to_json(indent=2)   # -> JSON string
+copy = ResourceDelta.from_dict(d)
+```
+
+**Formatted report:**
+
+```python
+print(delta.report())   # colour-coded when stderr is a TTY
+```
+
+---
+
+## Code Snippets
+
+See the [`guide-codesnippet/`](./guide-codesnippet/) folder for runnable examples:
+
+| File | What it demonstrates |
+|---|---|
+| [`01_basic_watch.py`](./guide-codesnippet/01_basic_watch.py) | Minimal `watch()` context manager |
+| [`02_selective_tracking.py`](./guide-codesnippet/02_selective_tracking.py) | Enabling only specific metrics |
+| [`03_probe_decorator.py`](./guide-codesnippet/03_probe_decorator.py) | `@probe` on sync and async functions |
+| [`04_json_export.py`](./guide-codesnippet/04_json_export.py) | Serialising results to JSON / dict |
+| [`05_fd_leak_detection.py`](./guide-codesnippet/05_fd_leak_detection.py) | Detecting file descriptor leaks |
+| [`06_ipc_tracing.py`](./guide-codesnippet/06_ipc_tracing.py) | Tracing queues, pipes, and sockets |
+| [`07_signal_dump.py`](./guide-codesnippet/07_signal_dump.py) | On-demand thread + asyncio dump via signal |
+| [`08_cli_usage.sh`](./guide-codesnippet/08_cli_usage.sh) | CLI `run`, `watch`, and `dump` commands |