stemtrace 0.1.0__tar.gz → 0.1.1__tar.gz

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

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

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

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -39,7 +39,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -58,12 +58,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -76,7 +76,7 @@ jobs:
         run: uv sync --all-extras
 
       - name: Run tests
-        run: uv run pytest --cov=stemtrace --cov-report=xml --cov-fail-under=80
+        run: uv run pytest --cov=stemtrace --cov-branch --cov-report=xml --cov-fail-under=80
 
       - name: Upload coverage
         uses: codecov/codecov-action@v5
@@ -117,7 +117,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -144,7 +144,7 @@ jobs:
         run: uvx twine check dist/*
 
       - name: Upload dist artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: dist
           path: dist/

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

@@ -33,7 +33,7 @@ jobs:
           echo "Services ready!"
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -80,7 +80,7 @@ jobs:
           echo "Services ready!"
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -129,7 +129,7 @@ jobs:
           PLAYWRIGHT_BASE_URL: http://localhost:8000
 
       - name: Upload Playwright report
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         if: always()
         with:
           name: playwright-report
@@ -137,7 +137,7 @@ jobs:
           retention-days: 7
 
       - name: Upload test results
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         if: failure()
         with:
           name: playwright-test-results

{stemtrace-0.1.0 → stemtrace-0.1.1}/.github/workflows/release.yml

@@ -22,7 +22,7 @@ jobs:
       version: ${{ steps.version.outputs.version }}
       tag: ${{ steps.version.outputs.tag }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Determine version
         id: version
@@ -49,12 +49,12 @@ jobs:
           echo "✅ Version $PYPROJECT_VERSION matches"
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
           cache: "npm"
@@ -74,7 +74,7 @@ jobs:
         run: twine check dist/*
 
       - name: Upload dist artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: dist
           path: dist/
@@ -87,7 +87,7 @@ jobs:
       id-token: write
     steps:
       - name: Download dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: dist
           path: dist/
@@ -102,7 +102,7 @@ jobs:
       contents: read
       packages: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -139,10 +139,10 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Download dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: dist
           path: dist/

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

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2025-12-31
+
+## [0.1.1] - 2025-12-31
+
+### Added
+- Python 3.14 support in CI and project classifiers
+- Mock-based E2E testing mode (no Docker required for local dev)
+- Codecov integration for coverage reporting
+
+### Changed
+- Upgraded React and React-DOM to v19
+- Upgraded @tanstack/react-query to latest
+- Updated GitHub Actions to v6 (checkout, setup-python, setup-node, upload/download-artifact)
+- Improved README with clearer Quick Start and FastAPI embedding docs
+
 ## [0.1.0] - 2025-12-27
 
 ### Added
@@ -29,5 +44,6 @@ 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.0...HEAD
+[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.1.1...HEAD
+[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.0 → stemtrace-0.1.1}/Makefile

@@ -161,7 +161,12 @@ release:
 # E2E Testing
 # =============================================================================
 
-# Start E2E test environment
+# Run Playwright E2E tests in mock mode (no Docker required)
+# This is the default and recommended way to run E2E tests locally
+e2e-mock:
+	cd $(FRONTEND_DIR) && npm test
+
+# Start E2E test environment (Docker)
 e2e-up:
 	docker compose -f docker-compose.e2e.yml up -d --wait
 	@echo "Waiting for services..."
@@ -176,14 +181,17 @@ e2e-down:
 e2e-api:
 	uv run pytest tests/e2e/ -m e2e -v
 
-# Run Playwright E2E tests (requires e2e-up first)
-e2e-playwright:
-	cd $(FRONTEND_DIR) && npm test
+# Run Playwright E2E tests against real Docker backend
+e2e-playwright-real:
+	cd $(FRONTEND_DIR) && E2E_MODE=real PLAYWRIGHT_BASE_URL=http://localhost:8000 npm test
 
-# Run all E2E tests (ensures cleanup on failure)
+# Run all E2E tests against Docker (full integration)
 e2e:
 	$(MAKE) e2e-up
-	$(MAKE) e2e-api && $(MAKE) e2e-playwright; \
+	$(MAKE) e2e-api && $(MAKE) e2e-playwright-real; \
 	status=$$?; \
 	$(MAKE) e2e-down; \
 	exit $$status
+
+# Quick E2E alias (mock mode, no Docker)
+e2e-quick: e2e-mock

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.1.0
+Version: 0.1.1
 Summary: A lightweight Celery task flow visualizer
 Project-URL: Homepage, https://github.com/iansokolskyi/stemtrace
 Project-URL: Documentation, https://github.com/iansokolskyi/stemtrace#readme
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
@@ -67,27 +68,29 @@ Description-Content-Type: text/markdown
 
 ---
 
-> **Flower answers "what exists". stemtrace answers "what happened".**
+> **Flower shows you what exists. Stemtrace shows you what happened.**
 
-`stemtrace` models Celery as a graph of executions derived from events. Visualize task flows, timelines, retries, and parent-child relationships — using your existing broker with zero new infrastructure.
+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.
 
 ## ✨ Features
 
-- **Task Flow Graphs** — Visualize parent → child chains, groups, and chords as DAGs
-- **Canvas Awareness** — Synthetic GROUP nodes for `group()` and `chord()` visualization
-- **Execution Timeline** — See queued → received → started → retried → finished states
-- **Full Lifecycle Capture** — PENDING, RECEIVED, STARTED, RETRY, SUCCESS, FAILURE states
-- **Arguments & Results** — View task inputs and outputs with sensitive data scrubbing
-- **Exception Capture** — Full traceback visibility on retries and failures
-- **Task Registry** — Browse all discovered task definitions
-- **Timing Visibility** — Start time and duration shown directly in graph nodes
-- **Correlation Tracking** — Trace requests across multiple tasks via `trace_id`
-- **Retry Visibility** — Know exactly which retries happened and why
-- **Zero Infrastructure** — Uses your existing broker; no database required
-- **Broker-Agnostic** — Works with Redis, RabbitMQ, and other Celery brokers
-- **FastAPI Pluggable** — Mount directly into your existing FastAPI app
-- **Zero Config** — Auto-detects your Celery broker configuration
+**See What Happened**
+- **Task Flow Graphs** — Visualize chains, groups, and chords as interactive DAGs
+- **Execution Timeline** — Track queued → started → retried → finished states
+- **Arguments & Results** — Inspect inputs, outputs, and exceptions
+- **Retry Chains** — Understand exactly when and why retries happened
+
+**Canvas Support**
+- **Groups & Chords** — Automatic visualization of `group()` and `chord()` patterns
+- **Parent-Child Tracking** — See which task spawned which
+
+**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
 
 ## 🚀 Quick Start
 
@@ -109,17 +112,30 @@ app = Celery("myapp", broker="redis://localhost:6379/0")
 stemtrace.init(app)
 ```
 
-### 3. Run the visualizer
+### 3. View the dashboard
+
+**Option A: Standalone server** (new container/process)
 
 ```bash
 stemtrace server
 ```
 
-Open [http://localhost:8000](http://localhost:8000) and watch your task flows come alive.
+Open [http://localhost:8000](http://localhost:8000).
 
-> By default, connects to `redis://localhost:6379/0`. Override with `--broker-url` or `STEMTRACE_BROKER_URL` env var.
+**Option B: Embed in your FastAPI app** (no extra container)
 
-See [Deployment Options](#️-deployment-options) for FastAPI integration and production setups.
+```python
+from fastapi import FastAPI
+from stemtrace.server import StemtraceExtension
+
+flow = StemtraceExtension(broker_url="redis://localhost:6379/0")
+app = FastAPI(lifespan=flow.lifespan)
+app.include_router(flow.router, prefix="/stemtrace")
+```
+
+Access at `/stemtrace/` in your existing app — no new services to deploy.
+
+See [Deployment Options](#️-deployment-options) for auth, scaling, and more.
 
 ## 📦 Architecture
 
@@ -188,6 +204,9 @@ 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
@@ -257,15 +276,9 @@ batch_processor
 ## 🐳 Docker
 
 ```bash
-# With Redis
 docker run -p 8000:8000 \
     -e STEMTRACE_BROKER_URL=redis://host.docker.internal:6379/0 \
-    ghcr.io/stemtrace/server
-
-# With RabbitMQ
-docker run -p 8000:8000 \
-    -e STEMTRACE_BROKER_URL=amqp://guest:guest@host.docker.internal:5672/ \
-    ghcr.io/stemtrace/server
+    ghcr.io/iansokolskyi/stemtrace
 ```
 
 Or with Docker Compose:
@@ -273,7 +286,7 @@ Or with Docker Compose:
 ```yaml
 services:
   stemtrace:
-    image: ghcr.io/stemtrace/server
+    image: ghcr.io/iansokolskyi/stemtrace
     ports:
       - "8000:8000"
     environment:
@@ -330,7 +343,15 @@ Mount stemtrace directly into your existing FastAPI application:
 from fastapi import FastAPI
 from stemtrace.server import StemtraceExtension
 
-flow = StemtraceExtension(broker_url="redis://localhost:6379/0")
+flow = StemtraceExtension(
+    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
+)
 app = FastAPI(lifespan=flow.lifespan)
 app.include_router(flow.router, prefix="/stemtrace")
 ```
@@ -376,53 +397,40 @@ app.include_router(flow.router, prefix="/stemtrace")
 
 ## 🗺️ Roadmap
 
-### Completed
-
-- [x] Task lifecycle tracking via signals
-- [x] Broker-agnostic event transport (Redis Streams)
-- [x] FastAPI pluggable integration
-- [x] React SPA dashboard with real-time WebSocket updates
-- [x] Task flow graph visualization
-- [x] Execution timeline view
-- [x] Task args/kwargs capture with sensitive data scrubbing
-- [x] Exception and traceback capture
-- [x] Task registry (browse all discovered tasks)
-- [x] PENDING/RECEIVED state capture
-- [x] E2E test suite (Docker API tests + Playwright browser tests)
-- [x] Canvas graph reconstruction (`group_id` capture, synthetic GROUP/CHORD nodes)
-- [x] Chord callback linking (CHORD node → callback edge)
-- [x] Timing display in graph nodes (start time, duration)
-
-### Planned
-
-- [ ] Worker/queue tracking in events
-- [ ] Monitoring APIs (workers, stats, orphan detection)
-- [ ] UI reorganization (Dashboard, unified Executions, enhanced Registry)
-- [ ] RabbitMQ transport
-- [ ] OpenTelemetry export
-- [ ] Webhook event export
-- [ ] JSON export API
+### What's Working Now
+
+- ✅ **Task flow graphs** — Visualize chains, groups, and chords as DAGs
+- ✅ **Full lifecycle tracking** — PENDING → RECEIVED → STARTED → SUCCESS/FAILURE
+- ✅ **Canvas awareness** — Automatic GROUP/CHORD node visualization
+- ✅ **Arguments & results** — View inputs, outputs, and exceptions
+- ✅ **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
+
+### 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
+- 🔜 **Webhook notifications** — Push events to your systems
+- 🔜 **Data export** — Download execution history as JSON
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
+Contributions, bug reports, and feature requests are welcome! This is a community project — if stemtrace helps you debug Celery, consider helping make it better.
+
+See our [Contributing Guide](CONTRIBUTING.md) to get started.
 
 ```bash
-# Clone the repo
 git clone https://github.com/iansokolskyi/stemtrace.git
 cd stemtrace
-
-# Install dependencies (requires uv)
-uv sync --all-extras
-
-# Run checks
-make check
+uv sync --all-extras  # Install dependencies
+make check            # Run tests
 ```
 
 ## 📄 License
 
-MIT License — see [LICENSE](LICENSE) for details.
-
----
-
-**stemtrace** is not affiliated with the Celery project. Celery is a trademark of Ask Solem.
+MIT — use it however you like.