stemtrace 0.1.1__tar.gz → 0.2.0__tar.gz

{stemtrace-0.1.1 → stemtrace-0.2.0}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.1.1"
+current_version = "0.2.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true

{stemtrace-0.1.1 → stemtrace-0.2.0}/.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
         run: uv sync --all-extras
 
       - name: Run tests
-        run: uv run pytest --cov=stemtrace --cov-branch --cov-report=xml --cov-fail-under=80
+        run: uv run pytest --cov=stemtrace --cov-branch --cov-report=xml --cov-fail-under=95
 
       - name: Upload coverage
         uses: codecov/codecov-action@v5

{stemtrace-0.1.1 → stemtrace-0.2.0}/.github/workflows/e2e.yml

@@ -126,6 +126,7 @@ jobs:
         working-directory: src/stemtrace/server/ui/frontend
         run: npm test
         env:
+          E2E_MODE: real
           PLAYWRIGHT_BASE_URL: http://localhost:8000
 
       - name: Upload Playwright report

{stemtrace-0.1.1 → stemtrace-0.2.0}/CHANGELOG.md

@@ -7,7 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.1] - 2025-12-31
+## [0.2.0] - 2026-01-03
+
+### Added
+- Workers API endpoints: `GET /api/workers` and `GET /api/workers/{hostname}`
+- Worker lifecycle tracking via `worker_ready` / `worker_shutdown` events to maintain a live worker registry
+- Workers UI page for inspecting online/offline workers and their registered tasks
+- Task Registry now shows which workers registered each task (`registered_by`)
 
 ## [0.1.1] - 2025-12-31
 
@@ -28,7 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Core domain models**: `TaskEvent`, `TaskState`, `TaskNode`, `TaskGraph`
 - **Protocol definitions**: `EventTransport`, `TaskRepository`, `AsyncEventConsumer`
 - **Event transports**: Redis Streams (`RedisTransport`), in-memory (`MemoryTransport`)
-- **Celery signal integration**: Automatic event capture via `stemtrace.init(app)`
+- **Celery signal integration**: Automatic event capture via `stemtrace.init_worker(app)`
 - **Server components**:
   - `GraphStore` — Thread-safe in-memory graph storage with LRU eviction
   - `EventConsumer` / `AsyncEventConsumer` — Background event processing
@@ -44,6 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **E2E test suite**: Docker API tests + Playwright browser tests
 - **Comprehensive test suite**: 350+ Python tests, 90%+ coverage
 
-[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.1.1...HEAD
+[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/iansokolskyi/stemtrace/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/iansokolskyi/stemtrace/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/iansokolskyi/stemtrace/releases/tag/v0.1.0

{stemtrace-0.1.1 → stemtrace-0.2.0}/CONTRIBUTING.md

@@ -19,7 +19,7 @@ git clone https://github.com/iansokolskyi/stemtrace.git
 cd stemtrace
 
 # Install dependencies (creates venv automatically)
-uv sync --all-extras
+uv sync --extra dev
 
 # Install pre-commit hooks
 uv run pre-commit install
@@ -79,7 +79,7 @@ uv run pytest
 uv run pytest --cov=stemtrace --cov-report=term-missing
 ```
 
-**Coverage requirement:** 80% minimum
+**Coverage requirement:** 95% minimum
 
 ### Updating Dependencies
 
@@ -132,7 +132,7 @@ uv lock --upgrade
 ### Code Quality
 
 - Google-style docstrings on all public APIs
-- Immutable dataclasses with `frozen=True, slots=True`
+- Pydantic models: immutable with `model_config = ConfigDict(frozen=True)`, mutable with `validate_assignment=True`
 - Fire-and-forget pattern for publishers (never block)
 - Fakes over mocks in tests
 

{stemtrace-0.1.1 → stemtrace-0.2.0}/Makefile

@@ -36,7 +36,7 @@ format:
 	uv run ruff check --fix src/ tests/
 
 test:
-	uv run pytest --cov=stemtrace --cov-report=term-missing --cov-fail-under=80
+	uv run pytest --cov=stemtrace --cov-report=term-missing --cov-fail-under=95
 
 # Run tests without coverage (faster iteration)
 test-fast:
@@ -170,7 +170,7 @@ e2e-mock:
 e2e-up:
 	docker compose -f docker-compose.e2e.yml up -d --wait
 	@echo "Waiting for services..."
-	@timeout 60 bash -c 'until curl -sf http://localhost:8000/stemtrace/api/health -o /dev/null; do sleep 2; done' || true
+	@timeout 60 bash -c 'until curl -sf http://localhost:8000/stemtrace/api/health -o /dev/null; do sleep 2; done' || (echo "❌ Service failed to become healthy"; exit 1)
 	@echo "✅ E2E environment ready at http://localhost:8000"
 
 # Stop E2E test environment

{stemtrace-0.1.1 → stemtrace-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.1.1
+Version: 0.2.0
 Summary: A lightweight Celery task flow visualizer
 Project-URL: Homepage, https://github.com/iansokolskyi/stemtrace
 Project-URL: Documentation, https://github.com/iansokolskyi/stemtrace#readme
@@ -41,7 +41,6 @@ Requires-Dist: build>=1.0.0; extra == 'dev'
 Requires-Dist: bump-my-version>=0.28.0; extra == 'dev'
 Requires-Dist: hatchling>=1.20.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
-Requires-Dist: pika>=1.3.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
@@ -50,15 +49,13 @@ Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Requires-Dist: twine>=5.0.0; extra == 'dev'
 Requires-Dist: types-redis>=4.0.0; extra == 'dev'
 Requires-Dist: websockets>=12.0; extra == 'dev'
-Provides-Extra: rabbitmq
-Requires-Dist: pika>=1.3.0; extra == 'rabbitmq'
 Description-Content-Type: text/markdown
 
 # stemtrace 🌿
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://badge.fury.io/py/stemtrace.svg)](https://badge.fury.io/py/stemtrace)
+[![PyPI version](https://img.shields.io/pypi/v/stemtrace)](https://pypi.org/project/stemtrace/)
 [![Python](https://img.shields.io/pypi/pyversions/stemtrace.svg)](https://pypi.org/project/stemtrace/)
 [![CI](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml/badge.svg)](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/iansokolskyi/stemtrace/graph/badge.svg)](https://codecov.io/gh/iansokolskyi/stemtrace)
@@ -72,7 +69,9 @@ Description-Content-Type: text/markdown
 
 Ever stared at a failed Celery task wondering "what called this?" or "why did it retry 5 times?"
 
-Stemtrace captures your task executions as a graph — visualize parent→child flows, see retry chains, track groups and chords, all without adding any new infrastructure. Just your existing Redis broker.
+Stemtrace captures your task executions as a graph — visualize parent→child flows, see retry chains, track groups and chords, all without adding any new infrastructure.
+
+**Today stemtrace supports Redis** for event transport (via Redis Streams). **RabbitMQ support is planned.**
 
 ## ✨ Features
 
@@ -86,20 +85,58 @@ Stemtrace captures your task executions as a graph — visualize parent→child
 - **Groups & Chords** — Automatic visualization of `group()` and `chord()` patterns
 - **Parent-Child Tracking** — See which task spawned which
 
+**Worker Monitoring & Registry**
+- **Workers page** — See which workers are online/offline and what tasks they have registered
+- **Registry status badges** — Quickly spot tasks that are active, never run, or not registered by any current worker
+
 **Production Ready**
 - **Zero Infrastructure** — Uses your existing Redis broker, no database needed
 - **Sensitive Data Scrubbing** — Passwords and API keys filtered automatically
 - **Read-Only** — Safe for production; never modifies your task queue
 - **FastAPI Integration** — Mount into your existing app with one line
 
+## 🔎 What you’ll see in the dashboard
+
+### Task details (timing, inputs/outputs, errors)
+
+- **What you’ll see**: Per-task execution timing (including how long it spent in each state), parameters (args/kwargs), return value, and the full event history.
+- **Why it helps**: Quickly answer “what happened?” for a single task: slow queueing vs slow execution, which retry succeeded, and (on failures) the exception + traceback for debugging.
+
+<p align="center">
+  <img src="docs/screenshots/task_details.png" width="900" alt="Task detail view showing parameters, result, and timeline" />
+</p>
+
+### Flow graphs (chains, groups, chords)
+
+- **What you’ll see**: An interactive DAG of your workflow with parent→child edges, plus clear GROUP/CHORD containers for Celery canvas patterns.
+- **Why it helps**: Understand fan-out/fan-in at a glance (especially chords), spot which branch failed, and debug “why didn’t my callback run?” without grepping logs.
+
+<p align="center">
+  <img src="docs/screenshots/workflow.png" width="900" alt="Chord visualization in the workflow graph" />
+</p>
+
+### Task registry (registration status + warnings)
+
+- **What you’ll see**: A registry of tasks with status badges like **Active**, **Never Run**, and **Not Registered** plus “registered by …” worker info.
+- **Why it helps**: Catch misconfigurations where tasks get stuck in **PENDING** because no current worker has the task registered (common in multi-repo or deploy drift scenarios).
+
+<p align="center">
+  <img src="docs/screenshots/unregistered.png" width="900" alt="Task registry showing not-registered warning and status badges" />
+</p>
+
 ## 🚀 Quick Start
 
 ### 1. Install
 
 ```bash
+# Using pip
 pip install stemtrace
+
+# Using uv
+uv add stemtrace
 ```
 
+
 ### 2. Instrument your Celery app
 
 ```python
@@ -108,8 +145,10 @@ import stemtrace
 
 app = Celery("myapp", broker="redis://localhost:6379/0")
 
-# One line to enable flow tracking
-stemtrace.init(app)
+# One line to enable event capture.
+# Tip: put this in the module where you define your Celery app so it's imported by
+# both Celery workers and any code that calls app.send_task()/delay().
+stemtrace.init_worker(app)
 ```
 
 ### 3. View the dashboard
@@ -126,11 +165,11 @@ Open [http://localhost:8000](http://localhost:8000).
 
 ```python
 from fastapi import FastAPI
-from stemtrace.server import StemtraceExtension
+import stemtrace
 
-flow = StemtraceExtension(broker_url="redis://localhost:6379/0")
-app = FastAPI(lifespan=flow.lifespan)
-app.include_router(flow.router, prefix="/stemtrace")
+app = FastAPI(lifespan=my_lifespan)  # Your existing app
+
+stemtrace.init_app(app, broker_url="redis://localhost:6379/0")
 ```
 
 Access at `/stemtrace/` in your existing app — no new services to deploy.
@@ -187,7 +226,7 @@ stemtrace is designed as two decoupled components:
 ```python
 import stemtrace
 
-stemtrace.init(
+stemtrace.init_worker(
     app,
     # Optional: override broker URL (defaults to Celery's broker_url)
     transport_url="redis://localhost:6379/0",
@@ -204,9 +243,6 @@ stemtrace.init(
     safe_keys=frozenset({"public_key"}),       # Never scrub these keys
 )
 
-# Configuration also available via StemtraceConfig model:
-# - max_data_size: Maximum serialized data size (default: 10KB)
-
 # Introspection (after init)
 stemtrace.is_initialized()   # -> True
 stemtrace.get_config()       # -> StemtraceConfig
@@ -225,7 +261,7 @@ Scrubbed values appear as `[Filtered]` in the UI.
 
 ### Canvas Graph Visualization
 
-stemtrace automatically detects and visualizes Celery canvas constructs:
+`stemtrace` automatically detects and visualizes Celery canvas constructs:
 
 ```text
 # Parent-spawned group: GROUP is child of parent
@@ -261,9 +297,7 @@ batch_processor
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `STEMTRACE_BROKER_URL` | Broker connection URL | Auto-detect from Celery |
-| `STEMTRACE_TTL` | Event TTL in seconds | `86400` |
-| `STEMTRACE_PREFIX` | Key/queue prefix | `stemtrace` |
+| `STEMTRACE_BROKER_URL` | Broker URL for `stemtrace server` / `stemtrace consume` and `stemtrace.init_app()` | `redis://localhost:6379/0` |
 
 ### Supported Brokers
 
@@ -271,7 +305,6 @@ batch_processor
 |--------|------------|--------|
 | Redis | `redis://`, `rediss://` | ✅ Supported |
 | RabbitMQ | `amqp://`, `amqps://` | 🚧 Planned |
-| Amazon SQS | `sqs://` | 🚧 Planned |
 
 ## 🐳 Docker
 
@@ -295,12 +328,12 @@ services:
 
 ## 🖥️ Deployment Options
 
-stemtrace offers two deployment modes depending on your needs:
+`stemtrace` offers two deployment modes depending on your needs:
 
 | Mode | Best For | Command |
 |------|----------|---------|
 | **Standalone Server** | Dedicated monitoring, simple setup | `stemtrace server` |
-| **FastAPI Embedded** | Single-app deployment, existing FastAPI apps | `StemtraceExtension` |
+| **FastAPI Embedded** | Single-app deployment, existing FastAPI apps | `stemtrace.init_app(...)` |
 
 ### Option 1: Standalone Server (Recommended)
 
@@ -326,66 +359,63 @@ stemtrace server \
 
 #### High-Scale Production Setup
 
-For high-throughput environments, run the consumer separately from the web server:
-
-```bash
-# Terminal 1: Run consumer (processes events)
-stemtrace consume
-
-# Terminal 2: Run API server (separate process, shares state via broker)
-stemtrace server
-```
+Note: `stemtrace server` includes an embedded consumer today (single-process). A multi-process deployment mode is planned.
 ### Option 2: FastAPI Embedded
 
 Mount stemtrace directly into your existing FastAPI application:
 
 ```python
 from fastapi import FastAPI
-from stemtrace.server import StemtraceExtension
+import stemtrace
+
+app = FastAPI(lifespan=my_lifespan)  # Your existing app with lifespan
+
+stemtrace.init_app(app, broker_url="redis://localhost:6379/0")  # Wraps lifespan, adds /stemtrace routes
+```
+
+That's it. `init_app()` automatically:
+- Wraps your existing lifespan (Sentry, DB connections, etc. keep working)
+- Mounts the dashboard at `/stemtrace/`
+- Starts the event consumer
+
+#### Configuration Options
 
-flow = StemtraceExtension(
+```python
+import stemtrace
+
+# Returns the underlying StemtraceExtension if you need it (optional).
+extension = stemtrace.init_app(
+    app,
     broker_url="redis://localhost:6379/0",
-    # Optional configuration:
-    # embedded_consumer=True,  # Run consumer in FastAPI process (default)
-    # serve_ui=True,           # Serve React UI (default)
-    # prefix="stemtrace",      # Redis key prefix
-    # ttl=86400,               # Event TTL in seconds
-    # max_nodes=10000,         # Max nodes to keep in memory
+    prefix="/stemtrace",        # Mount path AND event stream prefix (normalized)
+    ttl=86400,                  # Event TTL in seconds
+    max_nodes=10000,            # Max nodes in memory
+    embedded_consumer=True,     # Run consumer in FastAPI process
+    serve_ui=True,              # Serve React dashboard
+    auth_dependency=None,       # Optional auth (see below)
 )
-app = FastAPI(lifespan=flow.lifespan)
-app.include_router(flow.router, prefix="/stemtrace")
 ```
 
-Access the dashboard at `/stemtrace/` within your app.
-
 #### With Custom Authentication
 
-Use your existing auth middleware:
-
 ```python
 from fastapi import Depends
-from stemtrace.server import StemtraceExtension
+import stemtrace
 from your_app.auth import require_admin
 
-flow = StemtraceExtension(
-    broker_url="redis://localhost:6379/0",
-    auth_dependency=Depends(require_admin),
-)
-app = FastAPI(lifespan=flow.lifespan)
-app.include_router(flow.router, prefix="/stemtrace")
+stemtrace.init_app(app, broker_url="redis://localhost:6379/0", auth_dependency=Depends(require_admin))
 ```
 
 Or use built-in auth helpers:
 
 ```python
-from stemtrace.server import StemtraceExtension, require_basic_auth
+import stemtrace
 
-flow = StemtraceExtension(
+stemtrace.init_app(
+    app,
     broker_url="redis://localhost:6379/0",
-    auth_dependency=require_basic_auth("admin", "secret"),
+    auth_dependency=stemtrace.require_basic_auth("admin", "secret"),
 )
-app = FastAPI(lifespan=flow.lifespan)
-app.include_router(flow.router, prefix="/stemtrace")
 ```
 
 #### Embedded Consumer Modes
@@ -393,7 +423,7 @@ app.include_router(flow.router, prefix="/stemtrace")
 | Mode | Use Case | Setup |
 |------|----------|-------|
 | Embedded | Development, simple apps | Default — consumer runs in FastAPI process |
-| External | Production, high scale | Run `stemtrace consume` separately |
+| External | Production, high scale | Planned |
 
 ## 🗺️ Roadmap
 
@@ -406,12 +436,12 @@ app.include_router(flow.router, prefix="/stemtrace")
 - ✅ **Sensitive data scrubbing** — Passwords and API keys filtered automatically
 - ✅ **Real-time updates** — WebSocket-powered live dashboard
 - ✅ **FastAPI integration** — Mount into your existing app
-- ✅ **Task registry** — Browse all discovered task definitions
+- ✅ **Workers page** — Monitor online/offline workers and their registered tasks
+- ✅ **Task registry** — Browse discovered + registered tasks with clear status badges
 
 ### Coming Soon
 
 - 🔜 **RabbitMQ support** — Use your existing RabbitMQ broker
-- 🔜 **Worker monitoring** — See which worker processed each task
 - 🔜 **Anomaly detection** — Spot stuck, orphaned, or failed tasks
 - 🔜 **Dashboard with stats** — Success rates, durations, failure trends
 - 🔜 **OpenTelemetry export** — Send traces to Jaeger, Tempo, Datadog
@@ -427,7 +457,7 @@ See our [Contributing Guide](CONTRIBUTING.md) to get started.
 ```bash
 git clone https://github.com/iansokolskyi/stemtrace.git
 cd stemtrace
-uv sync --all-extras  # Install dependencies
+uv sync --extra dev   # Install dependencies
 make check            # Run tests
 ```