stemtrace 0.3.7__tar.gz → 0.3.8__tar.gz

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

@@ -1,10 +1,10 @@
 [tool.bumpversion]
-current_version = "0.3.7"
+current_version = "0.3.8"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true
-tag = false  # Tag created via GitHub Release UI
-commit_message = "chore: release v{new_version}"
+tag = false  # Tagged after the release PR merges (make release-tag)
+message = "chore: release v{new_version}"
 
 # Python package version in pyproject.toml
 [[tool.bumpversion.files]]
@@ -60,3 +60,10 @@ replace = """## [Unreleased]
 filename = "README.md"
 search = "[![PyPI version](https://img.shields.io/badge/pypi-v{current_version}-darklime)](https://pypi.org/project/stemtrace)"
 replace = "[![PyPI version](https://img.shields.io/badge/pypi-v{new_version}-darklime)](https://pypi.org/project/stemtrace)"
+
+# CHANGELOG compare links: advance [unreleased], add the new version's link
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v{current_version}...HEAD"
+replace = """[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v{new_version}...HEAD
+[{new_version}]: https://github.com/iansokolskyi/stemtrace/compare/v{current_version}...v{new_version}"""

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

@@ -1,19 +1,9 @@
 name: Release
 
 on:
+  # Releases are tagged on main after the release PR merges (make release-tag).
   push:
     tags: ["v*"]
-  # Manual trigger from Actions tab
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Version to release (e.g., 0.1.0) - must match version in pyproject.toml"
-        required: true
-        type: string
-
-env:
-  # Determine version from tag or manual input
-  VERSION: ${{ github.event.inputs.version || github.ref_name }}
 
 jobs:
   build:
@@ -25,17 +15,14 @@ jobs:
       tag: ${{ steps.version.outputs.tag }}
     steps:
       - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          fetch-depth: 0  # full history for the "tag is on main" check
 
       - name: Determine version
         id: version
         run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
-            echo "tag=v${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
-          else
-            echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
-            echo "tag=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
-          fi
+          echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+          echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
 
       - name: Verify version matches pyproject.toml
         run: |
@@ -50,6 +37,19 @@ jobs:
           fi
           echo "✅ Version $PYPROJECT_VERSION matches"
 
+      - name: Verify the tagged commit is on main
+        run: |
+          # Releases are tagged after the release PR merges; never from a branch.
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main || {
+            echo "❌ ${GITHUB_REF_NAME} points at a commit that isn't on main"; exit 1; }
+
+      - name: Check release notes exist in CHANGELOG.md
+        run: |
+          # Fail before anything is published: every release needs notes.
+          python3 scripts/changelog_section.py "$VERSION"
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
@@ -158,17 +158,17 @@ jobs:
           name: dist
           path: dist/
 
-      - name: Create tag (for manual dispatch)
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "${{ needs.build.outputs.tag }}" -m "Release ${{ needs.build.outputs.tag }}"
-          git push origin "${{ needs.build.outputs.tag }}"
+      - name: Extract release notes from CHANGELOG.md
+        run: python3 scripts/changelog_section.py "$VERSION" > "$RUNNER_TEMP/release_notes.md"
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           tag_name: ${{ needs.build.outputs.tag }}
+          # CHANGELOG.md section first; GitHub appends contributors, PR list
+          # and the compare link.
+          body_path: ${{ runner.temp }}/release_notes.md
           generate_release_notes: true
           files: dist/*

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

@@ -33,3 +33,4 @@ src/stemtrace/server/ui/frontend/src/routeTree.gen.ts
 src/stemtrace/server/ui/frontend/playwright-report/
 src/stemtrace/server/ui/frontend/test-results/
 src/stemtrace/server/ui/frontend/playwright/.cache/
+.release-notes.md

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

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.8] - 2026-10-10
+
+### Fixed
+- `node_alias_from_arguments` can now be set on the standalone server and Docker image: `stemtrace server --node-alias-from-arguments <key>` or `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS=<key>` (a kwarg name or a positional index). `init_app()` reads the same env var when the argument isn't passed (#69).
+- RabbitMQ: publishing from workers no longer blocks tasks while the broker is down, stalled or in a memory/disk alarm. Each publish tries every host of the URL once with a 2s timeout; repeated or slow failures open a circuit breaker that drops events (instead of queueing them) until the broker answers again, and the worker logs at most four warnings a minute with counts of dropped events. The README's broker section has the details and limits.
+- RabbitMQ: the server's consumer now reconnects after the broker restarts or drops the connection; it used to retry forever on a dead channel.
+- RabbitMQ: a broker outage no longer floods the server log with one ERROR traceback per second; reconnects back off from 1s to 30s and log one line per attempt, plus one when the connection is back (thanks @ohadmata — #70, #71).
+- RabbitMQ: a message the consumer can't decode is dropped with a warning instead of blocking the queue forever.
+- RabbitMQ: stopping the server no longer waits out the reconnect delay or hangs on a frozen broker.
+
+### Added
+- Health endpoint: `consumer_connected` is now reported for RabbitMQ, so `/api/health` shows `degraded` while the server can't read from the broker.
+
+### Deprecated
+- `init_worker(node_alias_from_arguments=...)` has no effect (node names are resolved by the server) and now logs a deprecation warning; it will be removed in a future major release.
+
 ## [0.3.7] - 2026-10-10
 
 ### Changed
@@ -165,7 +181,10 @@ 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.5...HEAD
+[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.8...HEAD
+[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
 [0.3.5]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.2...v0.3.3

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

@@ -136,6 +136,18 @@ uv lock --upgrade
 - Fire-and-forget pattern for publishers (never block)
 - Fakes over mocks in tests
 
+## Releasing (maintainers)
+
+Every release goes through a pull request into `main` and is published by CI from a tag on `main`.
+
+1. Add user-facing entries under `## [Unreleased]` in `CHANGELOG.md`.
+2. `make release-pr BUMP=patch|minor|major` runs the checks, creates `release/vX.Y.Z`, bumps the
+   version and opens a PR whose description is the changelog section.
+3. When CI is green, merge the PR with a merge commit (not squash or rebase).
+4. `make release-tag` tags the merge on `main`. The tag triggers the Release workflow, which
+   publishes to PyPI and GHCR and creates the GitHub Release from the changelog section. It
+   refuses to publish if the section is empty or the tag isn't on `main`.
+
 ## Questions?
 
 - Open an issue for bugs or feature requests

{stemtrace-0.3.7 → stemtrace-0.3.8}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install check types lint format test coverage clean ui-install ui-dev ui-build e2e e2e-api e2e-playwright build release-check version bump-dry bump-patch bump-minor bump-major release
+.PHONY: install check types lint format test coverage clean ui-install ui-dev ui-build e2e e2e-api e2e-playwright build release-check version bump-dry bump-patch bump-minor bump-major release release-pr release-tag
 
 # Install all dependencies
 install:
@@ -99,6 +99,8 @@ build:
 # Full pre-release checklist
 release-check:
 	@echo "=== Pre-release Checklist ==="
+	@echo "0. Checking CHANGELOG.md has [Unreleased] entries..."
+	@uv run python scripts/changelog_section.py Unreleased > /dev/null
 	@echo "1. Running all checks..."
 	$(MAKE) check
 	@echo ""
@@ -107,7 +109,6 @@ release-check:
 	@echo ""
 	@echo "✅ Ready to release!"
 	@echo ""
-	@echo "Next: make release"
 
 # =============================================================================
 # Versioning (bump-my-version)
@@ -126,7 +127,7 @@ bump-patch:
 	@NEW_VER=$$(uv run bump-my-version show current_version); \
 	echo "✅ Version bumped to $$NEW_VER"; \
 	echo ""; \
-	echo "Next: make release"
+	echo "Note: releases use make release-pr, which runs the bump itself; this target is for manual use only"
 
 # Bump minor version (0.1.0 -> 0.2.0)
 bump-minor:
@@ -134,7 +135,7 @@ bump-minor:
 	@NEW_VER=$$(uv run bump-my-version show current_version); \
 	echo "✅ Version bumped to $$NEW_VER"; \
 	echo ""; \
-	echo "Next: make release"
+	echo "Note: releases use make release-pr, which runs the bump itself; this target is for manual use only"
 
 # Bump major version (0.1.0 -> 1.0.0)
 bump-major:
@@ -142,20 +143,54 @@ bump-major:
 	@NEW_VER=$$(uv run bump-my-version show current_version); \
 	echo "✅ Version bumped to $$NEW_VER"; \
 	echo ""; \
-	echo "Next: make release"
+	echo "Note: releases use make release-pr, which runs the bump itself; this target is for manual use only"
 
 # Tag and push to trigger release workflow
 release:
-	@VERSION=$$(uv run bump-my-version show current_version); \
+	@echo "Releases go through a PR: make release-pr BUMP=patch|minor|major, then make release-tag."
+	@exit 1
+
+# Open a release PR: preflight, checks, release/vX.Y.Z branch, version bump, PR with notes.
+# Usage: make release-pr BUMP=patch|minor|major
+release-pr:
+	@set -e; \
+	case "$(BUMP)" in patch|minor|major) ;; *) echo "Usage: make release-pr BUMP=patch|minor|major"; exit 1;; esac; \
+	test "$$(git rev-parse --abbrev-ref HEAD)" = main || { echo "❌ Run from main"; exit 1; }; \
+	test -z "$$(git status --porcelain)" || { echo "❌ Working tree not clean"; exit 1; }; \
+	gh auth status >/dev/null 2>&1 || { echo "❌ gh is not authenticated (gh auth login)"; exit 1; }; \
+	git fetch -q --tags origin main; \
+	test -z "$$(git log HEAD..origin/main --oneline)" || { echo "❌ main is behind origin/main"; exit 1; }; \
+	NEW=$$(uv run bump-my-version show new_version --increment $(BUMP)); \
+	! git rev-parse -q --verify "refs/heads/release/v$$NEW" >/dev/null || { echo "❌ Local branch release/v$$NEW exists"; exit 1; }; \
+	test -z "$$(git ls-remote --heads origin "release/v$$NEW")" || { echo "❌ Remote branch release/v$$NEW exists"; exit 1; }; \
+	! git rev-parse -q --verify "refs/tags/v$$NEW" >/dev/null || { echo "❌ Tag v$$NEW exists"; exit 1; }; \
+	$(MAKE) release-check; \
+	git switch -c "release/v$$NEW"; \
+	uv run bump-my-version bump $(BUMP); \
+	NOTES=$$(mktemp); trap 'rm -f "$$NOTES"' EXIT; \
+	uv run python scripts/changelog_section.py "$$NEW" > "$$NOTES"; \
+	git push -u origin "release/v$$NEW" || { echo "❌ Push failed; local branch release/v$$NEW holds the bump commit"; exit 1; }; \
+	gh pr create --base main --head "release/v$$NEW" --title "chore: release v$$NEW" --body-file "$$NOTES" \
+		|| { echo "❌ PR creation failed; release/v$$NEW is pushed, open the PR manually"; exit 1; }; \
+	echo ""; \
+	echo "✅ Release PR opened for v$$NEW"; \
+	echo "Next: gh pr checks --watch, merge with a merge commit, then make release-tag"
+
+# Tag the merged release on main; the tag push triggers the Release workflow.
+release-tag:
+	@set -e; \
+	git switch -q main; \
+	git pull -q --ff-only origin main; \
+	VERSION=$$(uv run bump-my-version show current_version); \
 	TAG="v$$VERSION"; \
-	echo "Tagging $$TAG..."; \
+	SUBJECT=$$(git log -1 --format=%s); \
+	test "$$(git rev-list --parents -n 1 HEAD | wc -w)" -eq 3 || { echo "❌ HEAD of main is not a merge commit (merge the release PR with a merge commit)"; exit 1; }; \
+	case "$$SUBJECT" in *"/release/$$TAG"|*"release $$TAG"|*"release $$TAG "*) ;; *) echo "❌ HEAD of main is not the $$TAG release PR merge: $$SUBJECT"; exit 1;; esac; \
+	git fetch -q --tags origin; \
+	! git rev-parse -q --verify "refs/tags/$$TAG" >/dev/null || { echo "❌ $$TAG already exists"; exit 1; }; \
 	git tag -a "$$TAG" -m "Release $$TAG"; \
-	echo "Pushing to origin..."; \
-	git push origin main; \
 	git push origin "$$TAG"; \
-	echo ""; \
-	echo "✅ Released $$TAG"; \
-	echo "   → GitHub Actions will publish to PyPI and Docker"
+	echo "✅ Tagged $$TAG → Release workflow publishes PyPI, GHCR and the GitHub Release"
 
 # =============================================================================
 # E2E Testing

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.3.7
+Version: 0.3.8
 Summary: A lightweight Celery task flow visualizer
 Project-URL: Homepage, https://github.com/iansokolskyi/stemtrace
 Project-URL: Documentation, https://github.com/iansokolskyi/stemtrace#readme
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.7-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.8-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)
@@ -253,10 +253,6 @@ 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
-
-    # UI display
-    node_alias_from_arguments="operator_type", # Use kwargs["operator_type"] as node name
-    # node_alias_from_arguments="0",           # Or use args[0] (digit string = positional index)
 )
 
 # Introspection (after init)
@@ -336,6 +332,7 @@ stemtrace.init_app(
 |----------|-------------|---------|
 | `STEMTRACE_BROKER_URL` | Celery broker URL (used for on-demand worker/registry inspection). Also used as the default for `STEMTRACE_TRANSPORT_URL`. | `redis://localhost:6379/0` |
 | `STEMTRACE_TRANSPORT_URL` | Event transport URL (where stemtrace publishes/consumes events).  | Defaults to `STEMTRACE_BROKER_URL`. |
+| `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS` | Server only: show a task argument as the graph node name (see [Node Names from Task Arguments](#node-names-from-task-arguments)). Same as `--node-alias-from-arguments` / `init_app(node_alias_from_arguments=...)`. | Unset (task names are shown). |
 
 ### Supported Brokers
 
@@ -356,6 +353,36 @@ again once events are re-consumed.
   - Events already consumed/acked by the server are **gone**.
   - Events published while the server is down are only visible after restart if the server’s
     durable per-consumer queue still exists and the messages are still within TTL.
+  - Events that can't be published to RabbitMQ are dropped, not buffered on the worker, and a
+    broker outage doesn't slow tasks down. Each publish tries every host of the broker URL once
+    (2s connect timeout, 2s per read or write after that). A single quick failure, such as a
+    refused connection, drops only that event; a failure that took 0.5s or more (a timeout) or
+    three quick failures in a row make the worker skip publishing for a cooldown that grows from
+    1s to 30s and resets on the next successful publish.
+  - During a RabbitMQ memory or disk alarm, the broker accepts connections but stops reading
+    from publishers, so a publish is sent but never confirmed. The worker counts such events as
+    "sent but unconfirmed" (RabbitMQ may still deliver them once the alarm clears); after two
+    unconfirmed attempts in a row it retries only every 30s. Each attempt leaves one blocked
+    connection on the broker until the alarm clears, so expect 2 to 3 connections per worker
+    process in the first minute of an alarm and about 2 per minute after that, all released
+    when the alarm ends. Each retry also logs `Received method (10, 60) during closing channel 0`
+    from py-amqp's `amqp` logger (not stemtrace's): that's RabbitMQ's "connection blocked"
+    notice arriving while the connection closes.
+  - Logging is bounded: at most four warnings a minute however the broker behaves (failures,
+    an outage starting, an outage ending, and a summary). Each reports the number of events
+    dropped, and sent but unconfirmed, since the previous one, and losses are reported within
+    about 1.5 minutes even when the broker flaps.
+  - Limitation: a broker that answers but slowly (say, close to the 2s timeout for each step)
+    still costs every event several seconds, because publishes that eventually succeed don't
+    open the breaker.
+  - A failover broker URL (`amqp://h1//;amqp://h2//`) must list nodes of the same RabbitMQ
+    cluster: workers keep publishing to whichever host last worked, so the server must be able to
+    consume those events from any of them. Entries resolve as in kombu: a bare host (`;h2`)
+    takes user, password, port, virtual host and TLS options from the first entry, while a
+    URL-form entry (`;amqp://h2`) gets guest/guest unless it names credentials, and takes port
+    and virtual host from the previous entry only when it omits them (`//` means `/`). A host
+    that refuses the login ends that publish attempt without trying the later hosts, as in
+    kombu.
 - **Workers + Registry tabs**: stemtrace uses **Celery inspect** on demand to populate workers
   and registered tasks, so those pages work even if the server missed `worker_ready` events.
 - **If you need durable history across restarts**: point stemtrace events at Redis even if your
@@ -387,6 +414,15 @@ docker run -p 8000:8000 \
     ghcr.io/iansokolskyi/stemtrace
 ```
 
+Show a task argument as the graph node name (here `kwargs["operator_type"]`):
+
+```bash
+docker run -p 8000:8000 \
+    -e STEMTRACE_BROKER_URL=redis://host.docker.internal:6379/0 \
+    -e STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS=operator_type \
+    ghcr.io/iansokolskyi/stemtrace
+```
+
 Or with Docker Compose:
 
 ```yaml
@@ -430,9 +466,26 @@ stemtrace server \
     --transport-url redis://myredis:6379/0 \
     --host 0.0.0.0 \
     --port 8000 \
+    --node-alias-from-arguments operator_type \
     --reload  # For development
 ```
 
+#### Node Names from Task Arguments
+
+By default, graph nodes are labeled with the task name. Generic tasks (e.g. one `run_operator`
+task that does different things depending on its arguments) are easier to tell apart when the
+graph shows an argument instead:
+
+- `--node-alias-from-arguments operator_type` uses `kwargs["operator_type"]`
+- `--node-alias-from-arguments 0` uses `args[0]` (a digit string is a positional index)
+
+If the argument is missing, the task name is shown. This is a **server** setting: set it on
+`stemtrace server` (flag or `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS`, e.g. in Docker) or pass
+`node_alias_from_arguments` to `stemtrace.init_app(...)`. Surrounding whitespace is ignored, and
+`stemtrace server` prints `Node alias: <key>` at startup when it is set. Workers need
+`capture_args=True` (the default) so the arguments are available. Passing it to
+`stemtrace.init_worker(...)` has no effect and is deprecated.
+
 #### Protecting the Server (Built-in Login Page)
 
 ```bash
@@ -486,6 +539,7 @@ extension = stemtrace.init_app(
     embedded_consumer=True,     # Run consumer in FastAPI process
     serve_ui=True,              # Serve React dashboard
     auth_dependency=None,       # Optional auth (see below)
+    node_alias_from_arguments=None,  # e.g. "operator_type" or "0"; see Node Names from Task Arguments
 )
 ```
 
@@ -567,7 +621,7 @@ Because the status code stays 200, check `status` in the body if you want monito
 What is detected depends on the transport:
 
 - **Redis:** refused or reset connections, connect timeouts, repeated read timeouts, and consumer loop failures. On redis-py < 8 the default socket timeout is unbounded, so a half-open or hung broker connection may go unnoticed; add `?socket_timeout=…` or `?health_check_interval=…` to the broker URL if you need that.
-- **RabbitMQ:** connectivity isn't reported (`consumer_connected` is `null`), so `"degraded"` only reflects consumer loop failures.
+- **RabbitMQ:** refused or dropped connections and channel errors while connecting or draining, and consumer loop failures. The consumer connection is read about once a second and a read that times out counts as connected, so a half-open connection, or a broker that is frozen but keeps the socket open, may go unnoticed. Messages the consumer can't decode (not JSON) are dropped with a warning and don't count as failures.
 
 ## 🗺️ Roadmap
 

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

@@ -4,7 +4,7 @@
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.7-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.8-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)
@@ -198,10 +198,6 @@ 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
-
-    # UI display
-    node_alias_from_arguments="operator_type", # Use kwargs["operator_type"] as node name
-    # node_alias_from_arguments="0",           # Or use args[0] (digit string = positional index)
 )
 
 # Introspection (after init)
@@ -281,6 +277,7 @@ stemtrace.init_app(
 |----------|-------------|---------|
 | `STEMTRACE_BROKER_URL` | Celery broker URL (used for on-demand worker/registry inspection). Also used as the default for `STEMTRACE_TRANSPORT_URL`. | `redis://localhost:6379/0` |
 | `STEMTRACE_TRANSPORT_URL` | Event transport URL (where stemtrace publishes/consumes events).  | Defaults to `STEMTRACE_BROKER_URL`. |
+| `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS` | Server only: show a task argument as the graph node name (see [Node Names from Task Arguments](#node-names-from-task-arguments)). Same as `--node-alias-from-arguments` / `init_app(node_alias_from_arguments=...)`. | Unset (task names are shown). |
 
 ### Supported Brokers
 
@@ -301,6 +298,36 @@ again once events are re-consumed.
   - Events already consumed/acked by the server are **gone**.
   - Events published while the server is down are only visible after restart if the server’s
     durable per-consumer queue still exists and the messages are still within TTL.
+  - Events that can't be published to RabbitMQ are dropped, not buffered on the worker, and a
+    broker outage doesn't slow tasks down. Each publish tries every host of the broker URL once
+    (2s connect timeout, 2s per read or write after that). A single quick failure, such as a
+    refused connection, drops only that event; a failure that took 0.5s or more (a timeout) or
+    three quick failures in a row make the worker skip publishing for a cooldown that grows from
+    1s to 30s and resets on the next successful publish.
+  - During a RabbitMQ memory or disk alarm, the broker accepts connections but stops reading
+    from publishers, so a publish is sent but never confirmed. The worker counts such events as
+    "sent but unconfirmed" (RabbitMQ may still deliver them once the alarm clears); after two
+    unconfirmed attempts in a row it retries only every 30s. Each attempt leaves one blocked
+    connection on the broker until the alarm clears, so expect 2 to 3 connections per worker
+    process in the first minute of an alarm and about 2 per minute after that, all released
+    when the alarm ends. Each retry also logs `Received method (10, 60) during closing channel 0`
+    from py-amqp's `amqp` logger (not stemtrace's): that's RabbitMQ's "connection blocked"
+    notice arriving while the connection closes.
+  - Logging is bounded: at most four warnings a minute however the broker behaves (failures,
+    an outage starting, an outage ending, and a summary). Each reports the number of events
+    dropped, and sent but unconfirmed, since the previous one, and losses are reported within
+    about 1.5 minutes even when the broker flaps.
+  - Limitation: a broker that answers but slowly (say, close to the 2s timeout for each step)
+    still costs every event several seconds, because publishes that eventually succeed don't
+    open the breaker.
+  - A failover broker URL (`amqp://h1//;amqp://h2//`) must list nodes of the same RabbitMQ
+    cluster: workers keep publishing to whichever host last worked, so the server must be able to
+    consume those events from any of them. Entries resolve as in kombu: a bare host (`;h2`)
+    takes user, password, port, virtual host and TLS options from the first entry, while a
+    URL-form entry (`;amqp://h2`) gets guest/guest unless it names credentials, and takes port
+    and virtual host from the previous entry only when it omits them (`//` means `/`). A host
+    that refuses the login ends that publish attempt without trying the later hosts, as in
+    kombu.
 - **Workers + Registry tabs**: stemtrace uses **Celery inspect** on demand to populate workers
   and registered tasks, so those pages work even if the server missed `worker_ready` events.
 - **If you need durable history across restarts**: point stemtrace events at Redis even if your
@@ -332,6 +359,15 @@ docker run -p 8000:8000 \
     ghcr.io/iansokolskyi/stemtrace
 ```
 
+Show a task argument as the graph node name (here `kwargs["operator_type"]`):
+
+```bash
+docker run -p 8000:8000 \
+    -e STEMTRACE_BROKER_URL=redis://host.docker.internal:6379/0 \
+    -e STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS=operator_type \
+    ghcr.io/iansokolskyi/stemtrace
+```
+
 Or with Docker Compose:
 
 ```yaml
@@ -375,9 +411,26 @@ stemtrace server \
     --transport-url redis://myredis:6379/0 \
     --host 0.0.0.0 \
     --port 8000 \
+    --node-alias-from-arguments operator_type \
     --reload  # For development
 ```
 
+#### Node Names from Task Arguments
+
+By default, graph nodes are labeled with the task name. Generic tasks (e.g. one `run_operator`
+task that does different things depending on its arguments) are easier to tell apart when the
+graph shows an argument instead:
+
+- `--node-alias-from-arguments operator_type` uses `kwargs["operator_type"]`
+- `--node-alias-from-arguments 0` uses `args[0]` (a digit string is a positional index)
+
+If the argument is missing, the task name is shown. This is a **server** setting: set it on
+`stemtrace server` (flag or `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS`, e.g. in Docker) or pass
+`node_alias_from_arguments` to `stemtrace.init_app(...)`. Surrounding whitespace is ignored, and
+`stemtrace server` prints `Node alias: <key>` at startup when it is set. Workers need
+`capture_args=True` (the default) so the arguments are available. Passing it to
+`stemtrace.init_worker(...)` has no effect and is deprecated.
+
 #### Protecting the Server (Built-in Login Page)
 
 ```bash
@@ -431,6 +484,7 @@ extension = stemtrace.init_app(
     embedded_consumer=True,     # Run consumer in FastAPI process
     serve_ui=True,              # Serve React dashboard
     auth_dependency=None,       # Optional auth (see below)
+    node_alias_from_arguments=None,  # e.g. "operator_type" or "0"; see Node Names from Task Arguments
 )
 ```
 
@@ -512,7 +566,7 @@ Because the status code stays 200, check `status` in the body if you want monito
 What is detected depends on the transport:
 
 - **Redis:** refused or reset connections, connect timeouts, repeated read timeouts, and consumer loop failures. On redis-py < 8 the default socket timeout is unbounded, so a half-open or hung broker connection may go unnoticed; add `?socket_timeout=…` or `?health_check_interval=…` to the broker URL if you need that.
-- **RabbitMQ:** connectivity isn't reported (`consumer_connected` is `null`), so `"degraded"` only reflects consumer loop failures.
+- **RabbitMQ:** refused or dropped connections and channel errors while connecting or draining, and consumer loop failures. The consumer connection is read about once a second and a read that times out counts as connected, so a half-open connection, or a broker that is frozen but keeps the socket open, may go unnoticed. Messages the consumer can't decode (not JSON) are dropped with a warning and don't count as failures.
 
 ## 🗺️ Roadmap
 

{stemtrace-0.3.7 → stemtrace-0.3.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stemtrace"
-version = "0.3.7"
+version = "0.3.8"
 description = "A lightweight Celery task flow visualizer"
 readme = "README.md"
 license = { text = "MIT" }

stemtrace-0.3.8/scripts/changelog_section.py

@@ -0,0 +1,59 @@
+"""Print one version's section of CHANGELOG.md, for use as GitHub release notes.
+
+Usage: python scripts/changelog_section.py <version|Unreleased>
+
+Exits with status 1 when the section is missing or empty, so a release can't be
+published without notes.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+CHANGELOG = Path(__file__).resolve().parents[1] / "CHANGELOG.md"
+
+
+def changelog_section(text: str, version: str) -> str:
+    """Return the body of the ``## [version]`` section, without its heading.
+
+    Args:
+        text: Full CHANGELOG.md content (Keep a Changelog format).
+        version: Version such as ``0.3.8`` (a leading ``v`` is ignored) or
+            ``Unreleased``.
+
+    Returns:
+        The section body with surrounding blank lines stripped; empty if the
+        section is missing or holds only subheadings or HTML comments.
+    """
+    version = version.removeprefix("v")
+    heading = re.compile(rf"^## \[{re.escape(version)}\][^\n]*\n", re.MULTILINE)
+    match = heading.search(text)
+    if match is None:
+        return ""
+    rest = text[match.end() :]
+    next_heading = re.search(r"^## \[", rest, re.MULTILINE)
+    body = rest[: next_heading.start()] if next_heading else rest
+    # Link reference definitions at the end of the file aren't release notes.
+    body = re.sub(r"^\[[^\]]+\]:\s+\S+\s*$", "", body, flags=re.MULTILINE)
+    body = body.strip()
+    # A section with only "### Added"-style headings or comments has no notes.
+    content = re.sub(r"<!--.*?-->", "", body, flags=re.DOTALL)
+    content = re.sub(r"^#{3,}.*$", "", content, flags=re.MULTILINE)
+    return body if content.strip() else ""
+
+
+def main(argv: list[str]) -> int:
+    """Print the requested section of the repo's CHANGELOG.md; 1 if empty."""
+    if len(argv) != 2:
+        print(__doc__.strip().splitlines()[2], file=sys.stderr)
+        return 2
+    section = changelog_section(CHANGELOG.read_text(encoding="utf-8"), argv[1])
+    if not section:
+        print(f"No CHANGELOG.md entries for [{argv[1]}]", file=sys.stderr)
+        return 1
+    print(section)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))