Resolve #18 -- Add worker pool telemetry to inspector

Author: codingjoe

.github/agents/superjoe.agent.md

@@ -10,48 +10,43 @@ description: CodingJoe's digital clone following his coding guidelines and best
 
 ## Planning
 
-You MUST ALWAYS follow the `naming-things` guidelines. Use the following command to access the guidelines:
+MUST follow the `naming-things` guidelines:
 
 ```console
 curl -sSL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md | cat
 ```
 
-You MUST ALWAYS read the `CONTRIBUTING.md` file before planning or writing any code.
-You MUST ALWAYS search the documentation and update it as necessary.
-You MUST ALWAYS check for pre-commit hooks and run them before committing code.
-You MUST ALWAYS ensure that all new code is fully tested with 100% coverage. Unreachable code branches MUST be removed.
+MUST read `CONTRIBUTING.md` before planning or writing code.
+MUST search the documentation and update it as necessary.
+MUST check pre-commit hooks and run them before committing.
+MUST cover all new code with 100% coverage; remove unreachable branches.
 
 ## Writing Code
 
-Less code is more! Use the latest language features and libraries to achieve more with less code.
+Less code is more. Use the latest language features and libraries to do more with less.
 
-Do not add new dependencies, but if you do, they must be widely adopted and well-maintained in the open-source community.
+Do not add new dependencies; if unavoidable, prefer widely adopted, well-maintained FOSS with permissive licenses (BSD or MIT).
 
-You are a strong FOSS advocate with a preference for permissive licenses like BSD or MIT.
+Use class syntax for object-oriented code.
+Use named functions over anonymous functions.
+Break complex functions into smaller ones.
+Use generators over building lists or arrays, and prefer them over loops for large data sets.
+Avoid nested functions.
+Prefer `match`/`switch` or polymorphism over `if` chains.
+Do not name values returned on the next line.
 
-Use generators instead of adding items to lists or arrays.
+### Docstrings
 
-Use class syntax for all object-oriented code.
-Use named functions instead of anonymous functions whenever possible.
-Avoid overly complex functions. Break them into smaller functions if necessary.
-Docstrings should be written in present tense imperative mood.
-They must start with a capital letter and end with a period.
-Docstrings must describe the external behavior of the function, class, or method.
-Docstrings should avoid redundant phrases like "This function" or "This method".
-Class docstrings must not repeat the class name or start with a verb since they don't do anything themselves.
-Avoid code comments unless they describe behavior of 3rd party code or complex algorithms.
-Avoid loops in favor of recursive functions or generator functions.
-Avoid functions or other code inside functions.
-Avoid if-statements in favor of switch/match-statements or polymorphism.
-Do not assign names to objects which are returned in the next line.
+Present tense, imperative mood, capital letter start, period end.
+Describe external behavior; avoid "This function" or "This method".
+Class docstrings must not repeat the class name or start with a verb.
+Avoid code comments unless they describe third-party behavior or complex algorithms.
 
 ## Python
 
-Follow PEP 8 guidelines for code style.
-EAFP (Easier to Ask Forgiveness than Permission) is preferred over LBYL (Look Before You Leap).
-Use type hints for all public functions, classes, and methods.
+Follow PEP 8. Prefer EAFP over LBYL.
+Use type hints on all public functions, classes, and methods.
 Use dataclasses for simple data structures.
 Use context managers for resource management.
-Use list/set/dict comprehensions instead of loops for creating collections.
-Use generators for large data sets to save memory.
-Use the walrus operator (`:=`) for inline assignments when it improves readability.
+Use comprehensions over loops for building collections.
+Use the walrus operator (`:=`) when it improves readability.

.github/workflows/release.yml

@@ -8,8 +8,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
       - uses: astral-sh/setup-uv@v7
       - run: uvx --from build pyproject-build --sdist --wheel
       - uses: actions/upload-artifact@v7

AGENTS.md

@@ -18,7 +18,7 @@ uv run pytest -m "integration and benchmark"
 uv run pytest --benchmark-compare          # compare vs main baseline (run main first)
 uvx prek run --all-files
 uv run manage.py threadmill worker         # run the worker pool
-uv run manage.py threadmill inspector    # launch the textual TUI inspector
+uv run manage.py threadmill inspector      # launch the textual TUI inspector
 ```
 
 CI additionally pins Django per matrix step: `uv run --with django~=6.1a1 pytest -m "not benchmark"`.
@@ -28,8 +28,8 @@ Run a single test by node ID, e.g. `uv run pytest tests/test_command.py::TestCom
 ## Setup
 
 - Install pre-commit hooks before first commit: `uvx prek install` (not `pre-commit install`).
-- `DJANGO_SETTINGS_MODULE=tests.testapp.settings` is already set in `.env` and in `pyproject.toml`. Pytest auto-loads it.
-- CI's Linux job starts a Redis service and sets `REDIS_URL`; some integration tests may rely on it. Local runs of `-m integration` may need Redis if a backend test targets it.
+- `DJANGO_SETTINGS_MODULE=tests.testapp.settings` is set in `.env` and `pyproject.toml`; pytest auto-loads it.
+- CI's Linux job starts Redis and sets `REDIS_URL`; some integration tests rely on it. Local `-m integration` runs may need Redis.
 
 ## Code & style (repo-specific, beyond PEP 8)
 
@@ -50,15 +50,15 @@ Codecov requires 100% patch coverage on PRs (`pyproject.toml`, `.codecov.yml`).
 
 ## Architecture notes
 
-- Entry point for end users: `threadmill/management/commands/threadmill.py` (Django management command with `worker` and `inspector` subcommands).
+- Entry point: `threadmill/management/commands/threadmill.py` (management command with `worker` and `inspector` subcommands).
 - Core runtime: `threadmill/executor.py` (`TaskExecutor`) — process/thread pool, graceful shutdown, worker recycling, task timeout/backlog.
-- Integration point for queue authors: `threadmill/backends.py` (`AcknowledgeableTaskBackend`) — subclasses implement `acquire` (lock-without-remove) and `acknowledge` (remove + publish). Requires late-ack support from the underlying queue.
+- Queue author integration point: `threadmill/backends/base.py` (`ThreadmillTaskBackend`) — subclasses implement `acquire` (lock-without-remove) and `acknowledge` (remove + publish); requires late-ack support from the underlying queue.
 - Test app backend `tests/testapp/backends.py` (`GeneratingTaskBackend`) generates tasks in-process for benchmarks; reset between runs via `default_task_backend.reset()`.
 
 ## Pre-commit
 
-`.pre-commit-config.yaml` runs ruff (check + format), django-upgrade, pyupgrade, mdformat (excludes `.github/agents/`), yamlfmt, and `no-commit-to-branch` (protects `main`). Hooks auto-fix; ruff is configured `--exit-non-zero-on-fix`, so commit any fixes before pushing.
+`.pre-commit-config.yaml` runs ruff (check + format), django-upgrade, pyupgrade, mdformat (excludes `.github/agents/`), yamlfmt, and `no-commit-to-branch` (protects `main`). Hooks auto-fix; ruff uses `--exit-non-zero-on-fix`, so commit fixes before pushing.
 
 ## PR / release
 
-CI runs on `main` pushes and PRs. Releases are published to PyPI via `.github/workflows/release.yml` on GitHub release. Commits to `main` are blocked by `no-commit-to-branch`; work on a branch.
+CI runs on `main` pushes and PRs. Releases publish to PyPI via `.github/workflows/release.yml` on GitHub release. `no-commit-to-branch` blocks commits to `main`; work on a branch.

CONTRIBUTING.md

@@ -15,35 +15,21 @@ curl -sSL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/m
 
 ## Testing
 
-We have unit tests, integration tests, and benchmarks. Avoid mocking if possible.
-
-To run the tests, use the following command:
-
-```bash
-uv run pytest
-```
-
-To run only integration tests:
-
-```bash
-uv run pytest -m integration
-```
-
-To run only integration benchmarks:
+The suite has unit tests, integration tests, and benchmarks. Avoid mocking where possible.
 
 ```bash
+uv run pytest                              # full suite
+uv run pytest -m integration               # integration tests only
 uv run pytest -m "integration and benchmark"
 ```
 
-Benchmarking snapshots are created automatically.
-To compare your feature branch against the main branch,
-run the test suite on main, followed by:
+Benchmark snapshots are created automatically. To compare a feature branch against main, run the suite on main first, then:
 
 ```
 uv run pytest --benchmark-compare
 ```
 
-Before your first commit, ensure that the pre-commit hooks are installed by running:
+Install pre-commit hooks before your first commit:
 
 ```bash
 uvx prek install

README.md

@@ -1,8 +1,10 @@
+# Threadmill
+
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://github.com/codingjoe/threadmill/raw/main/docs/images/logo-dark.svg">
     <source media="(prefers-color-scheme: light)" srcset="https://github.com/codingjoe/threadmill/raw/main/docs/images/logo-light.svg">
-    <img alt="Threadmill: Durable high-performance backend for Django's task framework." src="https://github.com/codingjoe/threadmill/raw/main/docs/images/logo-light.svg">
+    <img alt="Threadmill: A queue agnostic worker for Django's task framework." src="https://github.com/codingjoe/threadmill/raw/main/docs/images/logo-light.svg">
   </picture>
 <br>
   <a href="https://github.com/codingjoe/threadmill/">Documentation</a> |
@@ -11,15 +13,24 @@
   <a href="https://github.com/sponsors/codingjoe">Funding</a> 💚
 </p>
 
-# Threadmill [![PyPi Version](https://img.shields.io/pypi/v/threadmill.svg)](https://pypi.python.org/pypi/threadmill/) [![Test Coverage](https://codecov.io/gh/codingjoe/threadmill/branch/main/graph/badge.svg)](https://codecov.io/gh/codingjoe/threadmill) [![GitHub License](https://img.shields.io/github/license/codingjoe/threadmill)](https://raw.githubusercontent.com/codingjoe/threadmill/master/LICENSE)
-
-**Durable high-performance backend for Django's task framework.**
+**A queue agnostic worker for Django's task framework.**
 
 ## Design Principles
 
-- **Durability** – Recover from any failures, even poorly written tasks.
-- **Consistency** – Never lose data, even if someone unplugs the power or network.
-- **Utilization** – Keep the CPU saturated with tasks, not with idle time or waiting for locks.
+- **Durability** – We recover from any failures, even poorly written tasks.
+- **Consistency** – We never lose data, even if someone unplugs the power or network.
+- **Utilization** – We keep the CPU saturated with tasks, not with idle time or waiting for locks.
+
+> [!WARNING]
+> Threadmill requires a development version of Django and is in a preview stage.
+
+[![PyPi Version](https://img.shields.io/pypi/v/threadmill.svg)](https://pypi.python.org/pypi/threadmill/)
+[![Test Coverage](https://codecov.io/gh/codingjoe/threadmill/branch/main/graph/badge.svg)](https://codecov.io/gh/codingjoe/threadmill)
+[![GitHub License](https://img.shields.io/github/license/codingjoe/threadmill)](https://raw.githubusercontent.com/codingjoe/threadmill/master/LICENSE)
+
+## Sponsors
+
+[![Sponsors](https://django.the-box.sh/sponsors/codingjoe/threadmill.svg)](https://github.com/sponsors/codingjoe)
 
 ## Setup
 
@@ -50,7 +61,7 @@ TASKS = {
 }
 ```
 
-Optionally, install the inspector dependency if you want the TUI:
+Optionally, add the inspector extra for the TUI:
 
 ```console
 uv add threadmill[inspector]
@@ -70,39 +81,33 @@ The workers are inspired by Gunicorn, and the CLI is very similar.
 
 #### Utilization
 
-Depending on your workload, you can tweak the number of processes and threads.
-Processes allow for parallel compute (no GIL) while threads are great for low-memory concurrent IO.
+Tune processes and threads to your workload. Processes bypass the GIL for parallel compute; threads suit low-memory concurrent IO.
 
 ```console
 uv run manage.py threadmill worker --processes 4 --threads 2
 ```
 
 #### Health
 
-If your tasks leak memory, you can recycle (restart) the workers after a certain number of tasks have been processed:
+Recycle workers after a number of tasks to reclaim leaked memory:
 
 ```console
 uv run manage.py threadmill worker --max-tasks 1000 --max-tasks-jitter 100
 ```
 
-This will restart the workers after 1000 tasks have been processed, with a random jitter of up to 100 tasks to avoid all workers restarting at the same time.
-
-Should a worker crash or be killed, the pool will automatically restart it.
+Jitter spreads restarts so workers do not recycle all at once. Crashed or killed workers are restarted automatically.
 
 #### Shutdown
 
-A graceful shutdown is possible with the `SIGTERM` or a keyboard interrupt.
-All workers will finish the tasks they acquired and acknowledge them.
+`SIGTERM` or a keyboard interrupt triggers a graceful shutdown: workers finish and acknowledge their in-flight tasks.
 
-You can use `--exit-empty` to exit immediately after all tasks have been processed,
-which might be useful for draining a one-off queue.
+Use `--exit-empty` to exit once the queue is drained, useful for one-off queue processing.
 
 ### Inspector
 
 ![Inspector TUI screenshot](https://github.com/codingjoe/threadmill/raw/main/docs/images/TUI-screenshot.svg)
 
-The optional TUI inspector lets you watch queues, tasks, and task details in real-time.
-Install it with the `inspector` extra and launch it from a separate terminal:
+The optional TUI inspector shows queues, tasks, and task details in real-time. Install the `inspector` extra and launch it from a separate terminal:
 
 ```console
 uv add threadmill[inspector]
@@ -111,8 +116,7 @@ uv run manage.py threadmill inspector
 
 ### Redis Backend Options
 
-The `RedisTaskBackend` accepts the following options under `OPTIONS` in your
-`TASKS` configuration:
+The `RedisTaskBackend` accepts the following options under `OPTIONS` in your `TASKS` configuration:
 
 | Option            | Default                | Description                                                  |
 | ----------------- | ---------------------- | ------------------------------------------------------------ |
@@ -121,17 +125,8 @@ The `RedisTaskBackend` accepts the following options under `OPTIONS` in your
 | `broker_interval` | `timedelta(seconds=1)` | Interval between background broker maintenance passes.       |
 | `batch_size`      | `100`                  | Max tasks to move or requeue per broker pass.                |
 
-A task that is started but never acknowledged (lease expired) is marked FAILED
-with an `AcknowledgementTimeout` error. Set `lease_ttl` comfortably above your
-worst-case task runtime.
-
-All keys for one backend alias share a Redis Cluster hash tag (`{alias}`), so
-every multi-key operation — including the cross-queue acquire — runs on a single
-shard. Scale horizontally by running additional backend aliases, not by relying
-on cross-slot operations.
+A started task that is never acknowledged (lease expired) is marked FAILED with an `AcknowledgementTimeout` error. Set `lease_ttl` above your worst-case task runtime.
 
-## Sponsors
-
-[![Sponsors](https://django.the-box.sh/sponsors/codingjoe/threadmill.svg)](https://github.com/sponsors/codingjoe)
+All keys for one backend alias share a Redis Cluster hash tag (`{alias}`), so every multi-key operation — including cross-queue acquire — runs on a single shard. Scale horizontally with additional backend aliases, not cross-slot operations.
 
 [django-tasks]: https://docs.djangoproject.com/en/stable/topics/tasks/

docs/images/logo-dark.svg

@@ -41,6 +41,9 @@ redis = ["redis>=5.0"]
 inspector = [
     "textual>=8.2.7",
 ]
+worker = [
+    "psutil>=7.2.2",
+]
 
 [project.urls]
 # https://packaging.python.org/en/latest/specifications/well-known-project-urls/#well-known-labels