stemtrace 0.3.8__tar.gz → 0.3.10__tar.gz

{stemtrace-0.3.8 → stemtrace-0.3.10}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.3.8"
+current_version = "0.3.10"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true
@@ -12,9 +12,9 @@ filename = "pyproject.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 
-# Python __version__ in package __init__.py
+# Python __version__ (leaf module, re-exported by the package __init__.py)
 [[tool.bumpversion.files]]
-filename = "src/stemtrace/__init__.py"
+filename = "src/stemtrace/_version.py"
 search = '__version__ = "{current_version}"'
 replace = '__version__ = "{new_version}"'
 

stemtrace-0.3.10/.coderabbit.yaml

@@ -0,0 +1,92 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# CodeRabbit review settings. The rules behind these instructions are summarized
+# in CONTRIBUTING.md; ruff, mypy and import-linter already run in CI, so reviews
+# should focus on what tools can't check.
+language: en-US
+tone_instructions: >-
+  Be concise and specific. Skip praise and style nits that ruff or Biome already
+  enforce. Lead with correctness, boundaries and test gaps.
+
+reviews:
+  profile: chill
+  high_level_summary: true
+  poem: false
+  in_progress_fortune: false
+  sequence_diagrams: false
+  collapse_walkthrough: true
+  path_filters:
+    - "!uv.lock"
+    - "!**/package-lock.json"
+    - "!src/stemtrace/server/ui/frontend/src/routeTree.gen.ts"
+    - "!src/stemtrace/server/ui/frontend/dist/**"
+  # Most specific paths first, the general Python entry last. The server and
+  # general globs match only *.py, so frontend files get just the frontend entry.
+  path_instructions:
+    - path: "src/stemtrace/core/**"
+      instructions: |
+        Domain layer: pure Python plus Pydantic only. Flag any I/O (network, files,
+        environment, clocks used for side effects) and any import of
+        stemtrace.library, stemtrace.server, Celery, Redis, kombu or FastAPI.
+        Events are immutable (frozen=True). Synthetic GROUP/CHORD nodes have
+        empty `events`; new graph code must handle that.
+    - path: "src/stemtrace/library/**"
+      instructions: |
+        Runs inside Celery workers. Imports core only, never stemtrace.server.
+        Publishing is fire-and-forget: it must never raise into or block a task,
+        and a failing broker must stay cheap on repeated events (circuit breaker
+        or backoff, never retry per event). Log volume must stay bounded during
+        an outage. Check shared state under prefork, threads and gevent/eventlet,
+        and fork safety of module-level locks. Per-task state belongs in a
+        ContextVar.
+    - path: "src/stemtrace/server/ui/frontend/**"
+      instructions: |
+        React 19 + TypeScript strict + TanStack Router/Query + @xyflow/react.
+        No `any`, explicit return types on exported functions, props interfaces
+        for components. routeTree.gen.ts is generated and must not be edited by
+        hand. Graph or UI behavior changes need Playwright coverage in tests/.
+    - path: "src/stemtrace/server/**/*.py"
+      instructions: |
+        Web server and consumer. Imports core only, never stemtrace.library. The
+        server is read-only toward the broker and the user's Celery app. Check
+        that API response schema changes are reflected in the frontend types and
+        tests, that auth dependencies apply to new routes, and that background
+        loops stop within a bounded time.
+    - path: "pyproject.toml"
+      instructions: |
+        Flag any new per-file-ignores entry for the design rules (C90, PLR09xx,
+        BLE, ERA, RET, PT) and any added import-linter ignore_imports entry:
+        the baseline only shrinks. New dependencies need a stated reason.
+    - path: "tests/**"
+      instructions: |
+        - A new test should fail on the old code with an assertion error that is
+          the bug, not an ImportError.
+        - Assert exact values, sequences and log counts, not `is not None`.
+        - Prefer fakes that model the real library semantics over
+          unittest.mock; a fake that always succeeds proves nothing.
+        - No real sleeps in unit tests: inject the clock and sleep function, and
+          bound loops so a regression fails instead of hanging.
+        - New `# noqa` comments need a reason after the codes; bare ones are
+          the pre-existing baseline and only shrink.
+        - Imports at the top of the file. Names follow
+          test_<action>_<condition>_<result>. Tests needing Redis or RabbitMQ
+          are marked integration; Docker-based ones e2e.
+    - path: "src/stemtrace/**/*.py"
+      instructions: |
+        - Does each new class or function hide a decision or remove work from its
+          callers? Flag pass-through wrappers and options with no current caller.
+        - Constants, timeouts and limits are defined once and imported, not copied.
+        - Every blocking call (connect, read, close, join, wait, lock) needs an
+          explicit timeout smaller than its caller's.
+        - Broad `except Exception` only at fire-and-forget boundaries, with a
+          `# noqa: BLE001  <reason>` comment and logging with context.
+        - Comments explain why or state an invariant. Comments about third-party
+          behavior should name the library version and function.
+        - Behavior claims in docstrings, README and CHANGELOG must be backed by a
+          test. Changes to user-visible behavior should be opt-in.
+        - Bare `# noqa: <codes>` comments are the baseline of code that predates
+          the lint rules; it only shrinks. Flag a newly added bare noqa: a new
+          suppression must give a reason after the codes, and a refactor
+          should delete the noqa it makes unnecessary.
+
+chat:
+  art: false

{stemtrace-0.3.8 → stemtrace-0.3.10}/.dockerignore

@@ -39,6 +39,7 @@ ENV/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+.import_linter_cache/
 .coverage
 htmlcov/
 .tox/

{stemtrace-0.3.8 → stemtrace-0.3.10}/.github/workflows/ci.yml

@@ -15,6 +15,7 @@ jobs:
   lint:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     env:
       UV_PYTHON: "3.12"
       STEMTRACE_SKIP_UI_BUILD: "1"
@@ -40,9 +41,13 @@ jobs:
       - name: Check formatting
         run: uv run --locked --no-build ruff format --check src/ tests/
 
+      - name: Check import contracts
+        run: uv run --locked --no-build lint-imports
+
   type-check:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     env:
       UV_PYTHON: "3.12"
       STEMTRACE_SKIP_UI_BUILD: "1"
@@ -68,6 +73,7 @@ jobs:
   test:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     env:
       UV_PYTHON: ${{ matrix.python-version }}
       STEMTRACE_SKIP_UI_BUILD: "1"
@@ -104,6 +110,7 @@ jobs:
   audit:
     name: Audit runtime dependencies
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     env:
       UV_PYTHON: "3.12"
     steps:
@@ -128,6 +135,7 @@ jobs:
   frontend:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     defaults:
       run:
         working-directory: src/stemtrace/server/ui/frontend
@@ -153,6 +161,7 @@ jobs:
   build:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     env:
       UV_PYTHON: "3.12"
     needs: [lint, type-check, test, frontend]
@@ -200,6 +209,7 @@ jobs:
     # actual default-branch commit after merges (or direct pushes / releases).
     if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     env:
       UV_PYTHON: "3.12"
       STEMTRACE_SKIP_UI_BUILD: "1"

{stemtrace-0.3.8 → stemtrace-0.3.10}/.github/workflows/release.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     env:
       UV_PYTHON: "3.12"
     outputs:
@@ -87,8 +88,11 @@ jobs:
           path: dist/
 
   pypi:
-    needs: build
+    # After the image: a failed or hung docker build then publishes nothing,
+    # instead of leaving PyPI ahead of GHCR and the GitHub Release.
+    needs: [build, docker]
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     environment: pypi
     permissions:
       id-token: write
@@ -105,6 +109,7 @@ jobs:
   docker:
     needs: build
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     permissions:
       contents: read
       packages: write
@@ -147,6 +152,7 @@ jobs:
   github-release:
     needs: [build, pypi, docker]
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: write
     steps:

{stemtrace-0.3.8 → stemtrace-0.3.10}/.gitignore

@@ -14,6 +14,7 @@ htmlcov/
 # Type checking / linting
 .mypy_cache/
 .ruff_cache/
+.import_linter_cache/
 
 # Virtual environments
 .venv/

{stemtrace-0.3.8 → stemtrace-0.3.10}/.pre-commit-config.yaml

@@ -30,3 +30,9 @@ repos:
         language: system
         types: [python]
         pass_filenames: false
+      - id: lint-imports
+        name: import contracts
+        entry: uv run lint-imports
+        language: system
+        types: [python]
+        pass_filenames: false

{stemtrace-0.3.8 → stemtrace-0.3.10}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.10] - 2026-10-11
+
+### Changed
+- Docker image: the UI is built once on the build machine's native platform instead of under emulation for each architecture, which also makes release builds faster. Building the image from source now needs BuildKit (the default since Docker 23 and in `docker compose`).
+- Development: ruff now also enforces complexity, function-size, blind-`except` and dead-code rules, and [import-linter](https://import-linter.readthedocs.io/) checks the `core`/`library`/`server` import boundaries in `make lint` and CI (see CONTRIBUTING.md). No runtime change.
+- The broker transports moved from `stemtrace.library.transports` to `stemtrace.transports`, so the Celery integration and the server share them without importing each other. The old module paths (`stemtrace.library.transports` and its `redis`, `rabbitmq`, `memory` and `breaker` submodules) still import the same public classes and functions but emit a `DeprecationWarning`, and will be removed in 1.0; patching module internals through the old paths (e.g. `mock.patch("stemtrace.library.transports.redis.time.sleep")`) no longer reaches the real code, so update such patches to `stemtrace.transports`. The transports' loggers are renamed to match (e.g. `stemtrace.transports.rabbitmq`); logging configured for the `stemtrace` logger is unaffected.
+
+### Fixed
+- Redis: a stream entry whose payload is valid JSON but not an object (e.g. `42`) is now skipped with a warning; it used to end the consumer's read loop and trigger a restart.
+
+## [0.3.9] - 2026-10-10
+
+### Added
+- Task output: with `init_worker(app, capture_output=True)`, what each task attempt prints and logs is shown on its task page, one block per attempt (latest first). Off by default because output isn't scrubbed; each attempt keeps the last `max_output_size` bytes (default 16 KB). Works with prefork, thread and gevent pools (thanks @JonatanMartens for the original implementation — #49; requested by @ohadmata — #47).
+
 ## [0.3.8] - 2026-10-10
 
 ### Fixed
@@ -181,7 +196,9 @@ 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.3.8...HEAD
+[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.10...HEAD
+[0.3.10]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.9...v0.3.10
+[0.3.9]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.8...v0.3.9
 [0.3.8]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.7...v0.3.8
 [0.3.7]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.6...v0.3.7
 [0.3.6]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.5...v0.3.6

{stemtrace-0.3.8 → stemtrace-0.3.10}/CONTRIBUTING.md

@@ -37,7 +37,7 @@ make check
 make check
 
 # Individual checks
-make lint       # ruff check + format
+make lint       # ruff check + format + import contracts
 make types      # mypy --strict
 make test       # pytest with coverage
 ```
@@ -54,6 +54,38 @@ uv run ruff check --fix src/ tests/
 uv run ruff format src/ tests/
 ```
 
+### Lint Rules and Import Contracts
+
+Besides style, ruff enforces design limits: McCabe complexity 10 (`C90`), at most
+12 branches, 6 returns, 50 statements and 5 positional arguments per function
+(`PLR09xx`; make extra parameters keyword-only), no blind `except Exception`
+(`BLE`), no commented-out code (`ERA`), plus `RET` and `PT` style rules. A broad
+except is accepted only at a fire-and-forget boundary, with
+`# noqa: BLE001  <reason>` on that line.
+
+[import-linter](https://import-linter.readthedocs.io/) checks the architecture
+boundaries (`uv run lint-imports`, part of `make lint` and CI):
+
+- `stemtrace.core` imports nothing from `stemtrace.library`, `stemtrace.server` or
+  `stemtrace.transports`, and no broker, Celery or web library (`celery`, `kombu`,
+  `amqp`, `redis`, `fastapi`, `starlette`, `uvicorn`, `typer`, `httpx`)
+- `stemtrace.transports` imports nothing from `stemtrace.library` or
+  `stemtrace.server` (both of them use it)
+- `stemtrace.library` does not import `stemtrace.server`
+- `stemtrace.server` does not import `stemtrace.library`
+
+**Baseline policy.** Code that predates these rules carries a per-line
+`# noqa: <codes>` comment with no reason (added with `ruff check --add-noqa`).
+Known import violations, if any, are listed under `ignore_imports` in
+`pyproject.toml` (there are none at the moment). The baseline only shrinks:
+
+- New code follows the rules. If a suppression is really needed, it names the
+  code and gives a reason: `# noqa: BLE001  fire-and-forget: <why>`. Never add a
+  bare `# noqa`.
+- When you fix a baselined line, delete its `# noqa`. Ruff's `RUF100` fails on a
+  `# noqa` that no longer suppresses anything, and import-linter fails on an
+  `ignore_imports` entry that no longer matches, so stale entries can't linger.
+
 ### Type Checking
 
 All code must pass `mypy --strict`:
@@ -125,8 +157,9 @@ uv lock --upgrade
 ### Key Principles
 
 - **core/** - Pure Python, no external dependencies
-- **library/** - Celery integration, imports only from core/
-- **server/** - Web server, imports only from core/
+- **transports/** - Broker adapters (Redis, RabbitMQ, memory), imports only from core/
+- **library/** - Celery integration, imports only from core/ and transports/
+- **server/** - Web server, imports only from core/ and transports/
 - Never import sideways (library ↔ server)
 
 ### Code Quality

{stemtrace-0.3.8 → stemtrace-0.3.10}/Dockerfile

@@ -2,7 +2,9 @@
 # Multi-stage build for smaller production image
 
 # Stage 1: Build frontend
-FROM node:22.23.3-alpine3.24@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402 AS frontend-builder
+# The UI build output is static files, identical for every platform, so build it
+# once on the native build platform instead of under QEMU (npm ci hung there).
+FROM --platform=$BUILDPLATFORM node:22.23.3-alpine3.24@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402 AS frontend-builder
 
 WORKDIR /app/frontend
 COPY src/stemtrace/server/ui/frontend/package*.json ./

{stemtrace-0.3.8 → stemtrace-0.3.10}/Makefile

@@ -30,6 +30,7 @@ exit(1) if missing else print('✓ All public APIs have docstrings') \
 lint:
 	uv run ruff check src/ tests/
 	uv run ruff format --check src/ tests/
+	uv run lint-imports
 
 format:
 	uv run ruff format src/ tests/
@@ -57,7 +58,7 @@ coverage:
 
 # Clean build artifacts
 clean:
-	rm -rf .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage dist/
+	rm -rf .pytest_cache .mypy_cache .ruff_cache .import_linter_cache htmlcov .coverage dist/
 	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
 
 # =============================================================================

{stemtrace-0.3.8 → stemtrace-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.3.8
+Version: 0.3.10
 Summary: A lightweight Celery task flow visualizer
 Project-URL: Homepage, https://github.com/iansokolskyi/stemtrace
 Project-URL: Documentation, https://github.com/iansokolskyi/stemtrace#readme
@@ -42,6 +42,7 @@ Provides-Extra: dev
 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: import-linter>=2.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
@@ -59,7 +60,7 @@ Description-Content-Type: text/markdown
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.8-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.10-darklime)](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)
@@ -83,6 +84,7 @@ Stemtrace captures your task executions as a graph — visualize parent→child
 - **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
+- **Task Output** — See what each attempt printed and logged, next to the task (opt-in)
 - **Retry Chains** — Understand exactly when and why retries happened
 
 **Canvas Support**
@@ -253,6 +255,10 @@ stemtrace.init_worker(
     scrub_sensitive_data=True,                 # Scrub passwords, API keys, etc.
     additional_sensitive_keys=frozenset({"my_secret"}),  # Add custom keys
     safe_keys=frozenset({"public_key"}),       # Never scrub these keys
+
+    # Task output (disabled by default, see "Task Output" below)
+    capture_output=False,                      # Capture what each attempt prints/logs
+    max_output_size=16384,                     # Max bytes kept per attempt (the end is kept)
 )
 
 # Introspection (after init)
@@ -271,6 +277,75 @@ By default, stemtrace scrubs common sensitive keys from task arguments:
 
 Scrubbed values appear as `[Filtered]` in the UI.
 
+#### Task Output (print and logging)
+
+Turn on `capture_output` on the worker to see what each task attempt printed and
+logged on its task page, instead of searching interleaved worker logs:
+
+```python
+stemtrace.init_worker(app, capture_output=True)
+```
+
+```python
+from celery.utils.log import get_task_logger
+import logging
+
+task_logger = get_task_logger(__name__)
+log = logging.getLogger("myapp.billing")
+
+@app.task(bind=True, max_retries=3)
+def charge(self, order_id):
+    print(f"charging {order_id}")           # -> charging 42
+    task_logger.info("calling gateway")     # -> INFO myapp.tasks: calling gateway
+    log.warning("gateway slow")             # -> WARNING myapp.billing: gateway slow
+    ...
+```
+
+The task page shows an **Output** section with one block per attempt (latest
+first): the output of a retried attempt is on its `RETRY` event, the final one on
+`SUCCESS`/`FAILURE`.
+
+- **What's captured**: `print()` to stdout and stderr, exactly as printed
+  (whether or not Celery redirects stdout to its log), and log records
+  (`logging.getLogger(...)`, `get_task_logger(...)`) emitted while the task
+  runs, in one chronological stream. Records are captured when they reach the
+  root logger or `celery.task`, or when a handler writes them to stdout/stderr
+  after stemtrace is set up. A logger with `propagate=False` whose handlers were
+  set up at worker startup (writing to the real stream or a file) isn't
+  captured. Log levels still apply to log records: one your logging config
+  filters out (e.g. `DEBUG` under `--loglevel=INFO`) isn't captured.
+  stemtrace's own logs and Celery/kombu internals are left out.
+  What the worker prints to its console or log file is unchanged (when no
+  logging handlers are configured, warnings still print as Python's
+  `logging.lastResort` would). One side effect: from the first task on, the root
+  logger has stemtrace's handler, so `logging.getLogger().hasHandlers()` is
+  `True` and a later `logging.basicConfig()` call without `force=True` does
+  nothing. Configure logging at startup (or pass `force=True`). Logging
+  handlers added while a task runs, ones that override `handle()`, or ones
+  that write to stdout/stderr in unusual ways may show a record twice or show
+  Celery/kombu lines in that task's output; handlers set up at worker startup
+  don't.
+- **Size**: at most `max_output_size` bytes (UTF-8) per attempt. Longer output
+  keeps its end, where failures usually are, after a `[… N bytes truncated]` line.
+  Output travels with the task's terminal event, so it is stored wherever events
+  are: by the server (up to `max_nodes` tasks) and, with the Redis transport, in
+  the stemtrace stream on your broker, which keeps the last `max(ttl, 10000)`
+  events (86,400 with the default `ttl`). At 16 KB per attempt that can add up to
+  more than a GB of Redis memory on busy workers, so consider a lower
+  `max_output_size` or `ttl` there. It isn't sent over the UI's WebSocket; the
+  task page fetches it.
+- **Pools**: each task's output is collected in a `ContextVar` (per thread, and
+  per greenlet under gevent/eventlet), so concurrent tasks never mix output.
+  Output from threads a task starts itself isn't captured.
+- **Not captured**: anything after the task ends, and output of a task whose
+  worker process was killed (hard time limit, OOM), since no terminal event is
+  sent from that process. Capture of a failed or retried attempt stops when
+  Celery reports the failure/retry, so `on_failure`/`on_retry` output is included
+  but `after_return` output is included only on success.
+- **Not scrubbed**: output is free text, so the key-based scrubbing above can't
+  apply. That's why it's off by default: only enable it if your tasks don't print
+  or log secrets.
+
 ### Canvas Graph Visualization
 
 `stemtrace` automatically detects and visualizes Celery canvas constructs:
@@ -631,6 +706,7 @@ What is detected depends on the transport:
 - ✅ **Full lifecycle tracking** — PENDING → RECEIVED → STARTED → SUCCESS/FAILURE
 - ✅ **Canvas awareness** — Automatic GROUP/CHORD node visualization
 - ✅ **Arguments & results** — View inputs, outputs, and exceptions
+- ✅ **Task output** — What each attempt printed and logged (opt-in)
 - ✅ **Sensitive data scrubbing** — Passwords and API keys filtered automatically
 - ✅ **Real-time updates** — WebSocket-powered live dashboard
 - ✅ **FastAPI integration** — Mount into your existing app

{stemtrace-0.3.8 → stemtrace-0.3.10}/README.md

@@ -4,7 +4,7 @@
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.8-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.10-darklime)](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)
@@ -28,6 +28,7 @@ Stemtrace captures your task executions as a graph — visualize parent→child
 - **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
+- **Task Output** — See what each attempt printed and logged, next to the task (opt-in)
 - **Retry Chains** — Understand exactly when and why retries happened
 
 **Canvas Support**
@@ -198,6 +199,10 @@ stemtrace.init_worker(
     scrub_sensitive_data=True,                 # Scrub passwords, API keys, etc.
     additional_sensitive_keys=frozenset({"my_secret"}),  # Add custom keys
     safe_keys=frozenset({"public_key"}),       # Never scrub these keys
+
+    # Task output (disabled by default, see "Task Output" below)
+    capture_output=False,                      # Capture what each attempt prints/logs
+    max_output_size=16384,                     # Max bytes kept per attempt (the end is kept)
 )
 
 # Introspection (after init)
@@ -216,6 +221,75 @@ By default, stemtrace scrubs common sensitive keys from task arguments:
 
 Scrubbed values appear as `[Filtered]` in the UI.
 
+#### Task Output (print and logging)
+
+Turn on `capture_output` on the worker to see what each task attempt printed and
+logged on its task page, instead of searching interleaved worker logs:
+
+```python
+stemtrace.init_worker(app, capture_output=True)
+```
+
+```python
+from celery.utils.log import get_task_logger
+import logging
+
+task_logger = get_task_logger(__name__)
+log = logging.getLogger("myapp.billing")
+
+@app.task(bind=True, max_retries=3)
+def charge(self, order_id):
+    print(f"charging {order_id}")           # -> charging 42
+    task_logger.info("calling gateway")     # -> INFO myapp.tasks: calling gateway
+    log.warning("gateway slow")             # -> WARNING myapp.billing: gateway slow
+    ...
+```
+
+The task page shows an **Output** section with one block per attempt (latest
+first): the output of a retried attempt is on its `RETRY` event, the final one on
+`SUCCESS`/`FAILURE`.
+
+- **What's captured**: `print()` to stdout and stderr, exactly as printed
+  (whether or not Celery redirects stdout to its log), and log records
+  (`logging.getLogger(...)`, `get_task_logger(...)`) emitted while the task
+  runs, in one chronological stream. Records are captured when they reach the
+  root logger or `celery.task`, or when a handler writes them to stdout/stderr
+  after stemtrace is set up. A logger with `propagate=False` whose handlers were
+  set up at worker startup (writing to the real stream or a file) isn't
+  captured. Log levels still apply to log records: one your logging config
+  filters out (e.g. `DEBUG` under `--loglevel=INFO`) isn't captured.
+  stemtrace's own logs and Celery/kombu internals are left out.
+  What the worker prints to its console or log file is unchanged (when no
+  logging handlers are configured, warnings still print as Python's
+  `logging.lastResort` would). One side effect: from the first task on, the root
+  logger has stemtrace's handler, so `logging.getLogger().hasHandlers()` is
+  `True` and a later `logging.basicConfig()` call without `force=True` does
+  nothing. Configure logging at startup (or pass `force=True`). Logging
+  handlers added while a task runs, ones that override `handle()`, or ones
+  that write to stdout/stderr in unusual ways may show a record twice or show
+  Celery/kombu lines in that task's output; handlers set up at worker startup
+  don't.
+- **Size**: at most `max_output_size` bytes (UTF-8) per attempt. Longer output
+  keeps its end, where failures usually are, after a `[… N bytes truncated]` line.
+  Output travels with the task's terminal event, so it is stored wherever events
+  are: by the server (up to `max_nodes` tasks) and, with the Redis transport, in
+  the stemtrace stream on your broker, which keeps the last `max(ttl, 10000)`
+  events (86,400 with the default `ttl`). At 16 KB per attempt that can add up to
+  more than a GB of Redis memory on busy workers, so consider a lower
+  `max_output_size` or `ttl` there. It isn't sent over the UI's WebSocket; the
+  task page fetches it.
+- **Pools**: each task's output is collected in a `ContextVar` (per thread, and
+  per greenlet under gevent/eventlet), so concurrent tasks never mix output.
+  Output from threads a task starts itself isn't captured.
+- **Not captured**: anything after the task ends, and output of a task whose
+  worker process was killed (hard time limit, OOM), since no terminal event is
+  sent from that process. Capture of a failed or retried attempt stops when
+  Celery reports the failure/retry, so `on_failure`/`on_retry` output is included
+  but `after_return` output is included only on success.
+- **Not scrubbed**: output is free text, so the key-based scrubbing above can't
+  apply. That's why it's off by default: only enable it if your tasks don't print
+  or log secrets.
+
 ### Canvas Graph Visualization
 
 `stemtrace` automatically detects and visualizes Celery canvas constructs:
@@ -576,6 +650,7 @@ What is detected depends on the transport:
 - ✅ **Full lifecycle tracking** — PENDING → RECEIVED → STARTED → SUCCESS/FAILURE
 - ✅ **Canvas awareness** — Automatic GROUP/CHORD node visualization
 - ✅ **Arguments & results** — View inputs, outputs, and exceptions
+- ✅ **Task output** — What each attempt printed and logged (opt-in)
 - ✅ **Sensitive data scrubbing** — Passwords and API keys filtered automatically
 - ✅ **Real-time updates** — WebSocket-powered live dashboard
 - ✅ **FastAPI integration** — Mount into your existing app