From 3f57757c3d3af810a6ead0159bde088f68b95fa1 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Mon, 4 May 2026 08:24:59 +0300 Subject: [PATCH] Fix correlation_id default in publisher docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The publisher.md table claimed `correlation_id` defaults to `auto UUID`, but the code falls back to the resolved `timer_id` (`publisher/usecase.py:73`, `broker.py:189`). Update the default cell to `same as timer_id` and add an admonition explaining the implication for idempotent retries (same `timer_id` → same `correlation_id` across retries). Enable the `admonition` markdown extension in `mkdocs.yml` so the new `!!! note` block renders. --- docs/usage/publisher.md | 11 ++++++++++- mkdocs.yml | 1 + 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/usage/publisher.md b/docs/usage/publisher.md index bfbb344..8e530f6 100644 --- a/docs/usage/publisher.md +++ b/docs/usage/publisher.md @@ -45,9 +45,18 @@ The `publish()` method on a publisher accepts the parameters below and returns t | `timer_id` | auto UUID | Unique ID for the timer — use for idempotency | | `activate_in` | `timedelta(0)` | Delay before delivery (fires immediately if 0) | | `activate_at` | `None` | Absolute timezone-aware datetime to fire at. Mutually exclusive with `activate_in` | -| `correlation_id` | auto UUID | Correlation ID for tracing — round-trips to the handler | +| `correlation_id` | same as `timer_id` | Correlation ID for tracing — round-trips to the handler. Defaults to the resolved `timer_id` (which is itself an auto UUID when not supplied) | | `headers` | `None` | `dict[str, Any]` of headers — round-trips to the handler | +!!! note "`correlation_id` defaults to `timer_id`" + If you omit `correlation_id`, it falls back to the resolved `timer_id` — + not a fresh UUID. When `timer_id` is also auto-generated, the two end up + equal but each unique. When you supply your own `timer_id` (e.g. + `"invoice-INV-001-due"`) for idempotent retries, omitting `correlation_id` + means every retry of that timer carries the *same* correlation ID. Pass + `correlation_id` explicitly if your tracing pipeline needs per-publish + uniqueness. + ### Tracing & headers example ```python diff --git a/mkdocs.yml b/mkdocs.yml index df1a4f7..bcd90a9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,6 +47,7 @@ theme: name: Switch to system preference markdown_extensions: + - admonition - toc: permalink: true - pymdownx.highlight: