Skip to content

Commit 4cdae09

Browse files
authored
Adopt Rust 4.17 replay-aware workflow logging (#542)
* Prepare Rust 4.17 replay-aware logging adoption * Bind logging evidence and qualify host emission * Cite lifecycle and logging receipts by their exact scopes * Translate Rust replay-aware logging and constraints across all locales --------- Co-authored-by: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com>
1 parent 1ff1d6f commit 4cdae09

24 files changed

Lines changed: 192 additions & 16 deletions

File tree

‎docs/constraints/workflow-constraints.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ Here are some examples of things you shouldn't do inside of a workflow class:
1313
- Don't make network requests to external resources, as these may be slow or unavailable at different times. Instead, pass the necessary data as inputs to the workflow when it is started or use an activity to retrieve the data.
1414
- Don't use random number generators (unless using a side effect) or other sources of randomness, as these will produce different results each time they are called. Instead, pass any necessary randomness as an input to the workflow when it is started.
1515

16+
## Logging from workflow code {#workflow-logging}
17+
18+
A worker reconstructs committed workflow history after activations and cold replacement, so ordinary application logging can repeat earlier messages. Use the replay-aware logger documented for your binding when available. Rust service mode provides the [Rust SDK 4.17 workflow logger](../polyglot/rust.md#workflow-logging); other bindings retain their separately documented contracts.
19+
20+
Logging is a process observation. Keep durable workflow commands independent of replay-state observations and log delivery. Even a replay-aware logger can repeat a message from an uncommitted attempt after a crash or retry; it is not an exactly-once outbox. Keep host handlers bounded and nonblocking so logging does not stall the worker. Put durable business effects behind the appropriate activity or recorded workflow operation instead.
21+
1622
## Boot-Time Guardrails
1723

1824
When workflow classes are registered under `workflows.v2.types.workflows`, the package scans them at boot time for obvious replay-unsafe calls (`Carbon::now()`, `Auth::user()`, `DB::`, `Http::`, `random_int()`, and similar) and surfaces findings according to `workflows.v2.guardrails.boot`:

‎docs/polyglot/rust.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -719,6 +719,22 @@ runs record `max_supported`; existing runs reuse the durable marker.
719719
drained. See [Side Effects](/docs/features/side-effects/) and
720720
[Versioning](/docs/features/versioning/) for the shared durable semantics.
721721

722+
## Replay-aware workflow logging {#workflow-logging}
723+
724+
Rust SDK 4.17.0 adds `ctx.logger().info("message")` for observations from workflow code. It routes to the application's existing `tracing` subscriber using target `durable_workflow::workflow`, with SDK-bound immutable `namespace`, `workflow_instance_id` and `workflow_run_id` fields. Configure the host subscriber; the SDK installs no global subscriber.
725+
726+
Ordinary log calls execute again as a worker reconstructs workflow history. The workflow logger stays quiet for committed-prefix, query/offline and completed-history replay, including cold worker replacement, and outside an active invocation. It can emit only in new execution beyond that prefix with a complete bound run identity. `ctx.replay_state()` observes that live consumed-history boundary rather than a Boolean fixed when the task starts:
727+
728+
| `WorkflowReplayState` | Observation |
729+
| --- | --- |
730+
| `Replaying` | Reconstructing committed history or a query; workflow logs are suppressed. |
731+
| `Executing` | New execution beyond the committed prefix; an uncommitted task retry can repeat logs. |
732+
| `Unavailable` | Outside this workflow invocation, or the state cannot be read safely; workflow logs are suppressed. |
733+
734+
Keep durable command order independent of this observation state and log delivery. A log from an uncommitted attempt can repeat after a crash or retry, so the logger is not an exactly-once outbox. Keep application handlers bounded and nonblocking, for example with an application-owned logging queue. Unwinding subscriber panics are isolated from the workflow result; process aborts and blocking handlers remain application responsibilities.
735+
736+
See the [published logging guide](https://github.com/durable-workflow/sdk-rust/blob/4.17.0/README.md#workflow-logging), [WorkflowLogger API](https://rust.durable-workflow.com/durable_workflow/struct.WorkflowLogger.html) and [WorkflowReplayState API](https://rust.durable-workflow.com/durable_workflow/enum.WorkflowReplayState.html). [Registry lifecycle/deadline controls](https://github.com/durable-workflow/sdk-rust/pull/269#issuecomment-6868388853) and [four-process logging acceptance](https://github.com/durable-workflow/sdk-rust/pull/269#issuecomment-6868494262) were recorded on the named native Server 3.10.0 linux/amd64 tuple. Other bindings and broader replay/producer qualification retain their own scope.
737+
722738
## Rust determinism rules {#rust-determinism-rules}
723739

724740
A replay must produce the same durable commands in the same order for the recorded input and history. Rust's ordinary collections, clocks and concurrency primitives do not automatically preserve that contract:

‎i18n/de/docusaurus-plugin-content-docs/current/constraints/workflow-constraints.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ Beispiele für Operationen, die nicht in den Workflow-Code gehören:
1313
- Führen Sie keine Netzwerkaufrufe zu externen Ressourcen aus. Verfügbarkeit und Laufzeit können schwanken. Übergeben Sie benötigte Daten beim Start oder lesen Sie sie in einer Aktivität.
1414
- Verwenden Sie keine Zufallszahlengeneratoren oder andere Zufallsquellen außerhalb eines Side Effects. Jeder Aufruf kann ein anderes Ergebnis liefern. Übergeben Sie benötigte Zufallswerte als Eingabe.
1515

16+
## Logging aus Workflow-Code {#workflow-logging}
17+
18+
Ein Worker rekonstruiert nach Aktivierungen und kaltem Austausch den persistierten Workflow-Verlauf. Gewöhnliches Anwendungslogging kann deshalb frühere Meldungen wiederholen. Verwenden Sie den für Ihr Binding dokumentierten replay-bewussten Logger, sofern verfügbar. Rust Service Mode bietet den [Workflow-Logger des Rust SDK 4.17](../polyglot/rust.md#workflow-logging); andere Bindings behalten ihre gesondert dokumentierten Verträge.
19+
20+
Logging ist eine Prozessbeobachtung. Halten Sie dauerhafte Workflow-Befehle unabhängig von Replay-Zustand und Log-Zustellung. Auch ein replay-bewusster Logger kann eine Meldung aus einem nicht persistierten Versuch nach Absturz oder Retry wiederholen; er ist keine Outbox mit Exactly-once-Garantie. Host-Handler müssen begrenzt und nicht blockierend bleiben, damit Logging den Worker nicht aufhält. Dauerhafte Geschäftseffekte gehören stattdessen in eine passende Activity oder aufgezeichnete Workflow-Operation.
21+
1622
## Prüfungen beim Anwendungsstart {#boot-time-guardrails}
1723

1824
Für unter `workflows.v2.types.workflows` registrierte Workflow-Klassen prüft das Paket beim Start offensichtliche Replay-unsichere Aufrufe wie `Carbon::now()`, `Auth::user()`, `DB::`, `Http::` und `random_int()`. Die Einstellung `workflows.v2.guardrails.boot` bestimmt die Behandlung:

‎i18n/de/docusaurus-plugin-content-docs/current/polyglot/rust.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -718,6 +718,22 @@ Marker erneut. `patched(change_id)` bietet die boolesche Rollout-Form.
718718
Die gemeinsame dauerhafte Semantik beschreiben [Seiteneffekte](/docs/features/side-effects/)
719719
und [Versionierung](/docs/features/versioning/).
720720

721+
## Replay-bewusstes Workflow-Logging {#workflow-logging}
722+
723+
Rust SDK 4.17.0 ergänzt `ctx.logger().info("message")` für Beobachtungen aus Workflow-Code. Die Ereignisse gehen an den bestehenden `tracing`-Subscriber der Anwendung mit dem Target `durable_workflow::workflow` und den unveränderlichen, vom SDK gebundenen Feldern `namespace`, `workflow_instance_id` und `workflow_run_id`. Konfigurieren Sie den Host-Subscriber; das SDK installiert keinen globalen Subscriber.
724+
725+
Gewöhnliche Log-Aufrufe werden erneut ausgeführt, wenn ein Worker den Workflow-Verlauf rekonstruiert. Der Workflow-Logger bleibt bei Replay des persistierten Präfixes, Query-/Offline-Replay und abgeschlossenen Verläufen still, auch nach einem kalten Worker-Wechsel und außerhalb eines aktiven Aufrufs. Er kann nur in neuer Ausführung hinter diesem Präfix und mit vollständiger gebundener Run-Identität ausgeben. `ctx.replay_state()` beobachtet diese aktuelle Grenze des konsumierten Verlaufs statt eines beim Task-Start fixierten Boolean:
726+
727+
| `WorkflowReplayState` | Beobachtung |
728+
| --- | --- |
729+
| `Replaying` | Rekonstruktion des persistierten Verlaufs oder einer Query; Workflow-Logs werden unterdrückt. |
730+
| `Executing` | Neue Ausführung hinter dem persistierten Präfix; ein Retry eines noch nicht persistierten Tasks kann Logs wiederholen. |
731+
| `Unavailable` | Außerhalb dieses Workflow-Aufrufs oder Zustand nicht sicher lesbar; Workflow-Logs werden unterdrückt. |
732+
733+
Halten Sie die dauerhafte Befehlsreihenfolge unabhängig von diesem Beobachtungszustand und der Log-Zustellung. Ein Log aus einem nicht persistierten Versuch kann nach Absturz oder Retry erneut erscheinen; der Logger ist keine Outbox mit Exactly-once-Garantie. Halten Sie Anwendungshandler begrenzt und nicht blockierend, etwa mit einer anwendungseigenen Logging-Queue. Subscriber-Panics mit Stack-Unwinding werden vom Workflow-Ergebnis isoliert; Prozessabbrüche und blockierende Handler bleiben Anwendungsverantwortung.
734+
735+
Siehe den [veröffentlichten Logging-Guide](https://github.com/durable-workflow/sdk-rust/blob/4.17.0/README.md#workflow-logging), die [WorkflowLogger-API](https://rust.durable-workflow.com/durable_workflow/struct.WorkflowLogger.html) und die [WorkflowReplayState-API](https://rust.durable-workflow.com/durable_workflow/enum.WorkflowReplayState.html). [Registry-Lifecycle-/Deadline-Kontrollen](https://github.com/durable-workflow/sdk-rust/pull/269#issuecomment-6868388853) und [Logging-Abnahme mit vier Prozessen](https://github.com/durable-workflow/sdk-rust/pull/269#issuecomment-6868494262) wurden auf dem benannten Tupel mit native Server 3.10.0 unter linux/amd64 erfasst. Andere Bindings und weitergehende Replay-/Producer-Qualifikation behalten ihren eigenen Umfang.
736+
721737
## Rust-Regeln für Determinismus {#rust-determinism-rules}
722738

723739
Ein Replay muss für aufgezeichnete Eingabe und Historie dieselben dauerhaften Befehle in derselben Reihenfolge erzeugen. Gewöhnliche Rust-Sammlungen, Uhren und Nebenläufigkeitsprimitive erhalten diesen Vertrag nicht automatisch:

‎i18n/de/source-hashes.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
"constraints/idempotent-vs-deterministic.md": "f7396f01a4111ce187e751b009c1efb96f5538e8a602006eed24f7b1d8f44adf",
1919
"constraints/overview.md": "fd6c842c6c22d6f0df37a52de15ca74b34664f5ecd78af0c08b1e0cdb9a2be1f",
2020
"constraints/structural-limits.md": "5c7b7f6c86c5ca547eb3f200400ceab3b589f32d83866914f44e3a5a7d81e964",
21-
"constraints/workflow-constraints.md": "2fc7b45646bf459ff31fb27d38b5ae34602e1a64697c8f2d2378421a7f8a6ef5",
21+
"constraints/workflow-constraints.md": "f80f68b13877a67469a313b9fdcdbb27c1de6fe102cdfddb15e2af95997d2517",
2222
"contribute-a-sample.md": "d250d8c63d448e32d3160ff7a2900e7a270dcbd9cda22cf3af46cdf219395ea3",
2323
"conversational-workflows.md": "d155b4af3d83293802cfa765bb28de7b3fc52345509f4f3d02e16318d825a675",
2424
"defining-workflows/activities.md": "05b46f73477a0bbd5f21d17ac37def8a8eac53f1e629155805c98cc46e75b418",
@@ -87,7 +87,7 @@
8787
"polyglot/python.md": "82da06617fe24e70c5c89197d192a81430a282b788ef93afd3b3bcb690ba2a9f",
8888
"polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71",
8989
"polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3",
90-
"polyglot/rust.md": "2cc511074e6d0ce8ababa0ccd6acbdaa7df3bf5d8c67ae5ef2fa07d75a05d2e7",
90+
"polyglot/rust.md": "31950634b8ccdb5c288ba871cc7f816de6683c52bf738bfdc13fa7aa825c6335",
9191
"polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c",
9292
"polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429",
9393
"polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2",

‎i18n/es/docusaurus-plugin-content-docs/current/constraints/workflow-constraints.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ Ten en cuenta estas reglas al escribir un workflow:
2424
hacerlo durante la ejecución, usa un side effect para registrar el resultado.
2525
También puedes pasar el valor aleatorio como entrada al iniciar el workflow.
2626

27+
## Logging desde el código del workflow {#workflow-logging}
28+
29+
Un worker reconstruye el historial confirmado del workflow tras activaciones y reemplazos en frío, por lo que el logging normal de la aplicación puede repetir mensajes anteriores. Use el logger consciente del replay documentado para su binding cuando esté disponible. El modo servicio Rust ofrece el [logger de workflow de Rust SDK 4.17](../polyglot/rust.md#workflow-logging); los demás bindings conservan sus contratos documentados por separado.
30+
31+
El logging es una observación del proceso. Mantenga los comandos durables del workflow independientes de las observaciones de replay y de la entrega de logs. Incluso un logger consciente del replay puede repetir un mensaje de un intento no confirmado tras un fallo o retry; no es un outbox exactamente una vez. Los handlers del host deben estar acotados y no bloquear para no detener al worker. Sitúe los efectos de negocio durables en la actividad u operación de workflow registrada adecuada.
32+
2733
## Comprobaciones al iniciar la aplicación {#boot-time-guardrails}
2834

2935
Cuando registras clases de workflow en `workflows.v2.types.workflows`, el paquete

‎i18n/es/docusaurus-plugin-content-docs/current/polyglot/rust.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -547,6 +547,22 @@ El SDK de Rust registra valores no deterministas pequeños con `WorkflowContext:
547547

548548
Utiliza `WorkflowContext::get_version(change_id, min_supported, max_supported)` para mantener compatibles con la reproducción las ramas antiguas y nuevas durante un despliegue. Las ejecuciones nuevas registran `max_supported`; las existentes reutilizan el marcador duradero. `patched(change_id)` ofrece la forma booleana del despliegue y `deprecate_patch(change_id)` conserva el marcador tras finalizar la rama heredada. Consulta [Efectos secundarios](/docs/features/side-effects/) y [Versionado](/docs/features/versioning/) para la semántica duradera compartida.
549549

550+
## Logging de workflows consciente del replay {#workflow-logging}
551+
552+
Rust SDK 4.17.0 añade `ctx.logger().info("message")` para observaciones desde el código del workflow. Envía los eventos al subscriber `tracing` existente de la aplicación con el target `durable_workflow::workflow` y los campos inmutables vinculados por el SDK `namespace`, `workflow_instance_id` y `workflow_run_id`. Configure el subscriber del host; el SDK no instala uno global.
553+
554+
Las llamadas de log normales vuelven a ejecutarse cuando un worker reconstruye el historial del workflow. El logger del workflow permanece silencioso durante el replay del prefijo confirmado, las consultas/replay offline y los historiales completados, incluso tras reemplazar el worker en frío, y fuera de una invocación activa. Solo puede emitir en ejecución nueva más allá de ese prefijo y con una identidad de run completa y vinculada. `ctx.replay_state()` observa ese límite vivo del historial consumido, en lugar de un booleano fijado al iniciar la tarea:
555+
556+
| `WorkflowReplayState` | Observación |
557+
| --- | --- |
558+
| `Replaying` | Reconstrucción de historial confirmado o de una consulta; se suprimen los logs del workflow. |
559+
| `Executing` | Ejecución nueva más allá del prefijo confirmado; reintentar una tarea no confirmada puede repetir logs. |
560+
| `Unavailable` | Fuera de esta invocación del workflow o sin lectura segura del estado; se suprimen los logs del workflow. |
561+
562+
Mantenga el orden de comandos durables independiente de este estado de observación y de la entrega de logs. Un log de un intento no confirmado puede repetirse tras un fallo o retry; el logger no es un outbox exactamente una vez. Mantenga los handlers de la aplicación acotados y no bloqueantes, por ejemplo con una cola de logging propia. Los panics del subscriber con desenrollado de pila se aíslan del resultado del workflow; los abortos del proceso y handlers bloqueantes siguen siendo responsabilidad de la aplicación.
563+
564+
Consulte la [guía de logging publicada](https://github.com/durable-workflow/sdk-rust/blob/4.17.0/README.md#workflow-logging), la [API WorkflowLogger](https://rust.durable-workflow.com/durable_workflow/struct.WorkflowLogger.html) y la [API WorkflowReplayState](https://rust.durable-workflow.com/durable_workflow/enum.WorkflowReplayState.html). Los [controles de ciclo de vida/deadline desde el registro](https://github.com/durable-workflow/sdk-rust/pull/269#issuecomment-6868388853) y la [aceptación de logging con cuatro procesos](https://github.com/durable-workflow/sdk-rust/pull/269#issuecomment-6868494262) se registraron en la tupla nombrada native Server 3.10.0 linux/amd64. Los demás bindings y la cualificación más amplia de replay/productor mantienen su propio alcance.
565+
550566
## Reglas de determinismo de Rust {#rust-determinism-rules}
551567

552568
Una reproducción debe generar los mismos comandos duraderos, en el mismo orden, para la entrada y el historial registrados. Las colecciones, relojes y primitivas de concurrencia normales de Rust no mantienen automáticamente ese contrato:

‎i18n/es/source-hashes.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
"constraints/idempotent-vs-deterministic.md": "f7396f01a4111ce187e751b009c1efb96f5538e8a602006eed24f7b1d8f44adf",
1919
"constraints/overview.md": "fd6c842c6c22d6f0df37a52de15ca74b34664f5ecd78af0c08b1e0cdb9a2be1f",
2020
"constraints/structural-limits.md": "5c7b7f6c86c5ca547eb3f200400ceab3b589f32d83866914f44e3a5a7d81e964",
21-
"constraints/workflow-constraints.md": "2fc7b45646bf459ff31fb27d38b5ae34602e1a64697c8f2d2378421a7f8a6ef5",
21+
"constraints/workflow-constraints.md": "f80f68b13877a67469a313b9fdcdbb27c1de6fe102cdfddb15e2af95997d2517",
2222
"contribute-a-sample.md": "d250d8c63d448e32d3160ff7a2900e7a270dcbd9cda22cf3af46cdf219395ea3",
2323
"conversational-workflows.md": "d155b4af3d83293802cfa765bb28de7b3fc52345509f4f3d02e16318d825a675",
2424
"defining-workflows/activities.md": "05b46f73477a0bbd5f21d17ac37def8a8eac53f1e629155805c98cc46e75b418",
@@ -87,7 +87,7 @@
8787
"polyglot/python.md": "82da06617fe24e70c5c89197d192a81430a282b788ef93afd3b3bcb690ba2a9f",
8888
"polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71",
8989
"polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3",
90-
"polyglot/rust.md": "2cc511074e6d0ce8ababa0ccd6acbdaa7df3bf5d8c67ae5ef2fa07d75a05d2e7",
90+
"polyglot/rust.md": "31950634b8ccdb5c288ba871cc7f816de6683c52bf738bfdc13fa7aa825c6335",
9191
"polyglot/server-api-reference.md": "ecd6d358d6e5bde442ebf0e1ec8a072779089e2a5c4427e31eef646f42c6c03c",
9292
"polyglot/server-config-reference.md": "aec241c0046f12a9d6efe2d6c1de443d7753bdf34135e06a6f83b3904ed1d429",
9393
"polyglot/server-role-topology.md": "3d048f0c6b5f179399622508f51e67fff8aa5a6d5b2492533fc720eeec2c27f2",

‎i18n/fr/docusaurus-plugin-content-docs/current/constraints/workflow-constraints.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ Dans le corps d’un workflow :
1515
- Évitez les requêtes réseau directes, dont la réponse, la vitesse et la disponibilité varient. Passez les données en entrée ou récupérez-les dans une activité.
1616
- Évitez les générateurs de nombres aléatoires et les autres sources d’aléa, sauf si le résultat est enregistré avec un effet de bord durable. Vous pouvez aussi passer la valeur aléatoire en entrée au démarrage.
1717

18+
## Journaliser depuis le code de workflow {#workflow-logging}
19+
20+
Un worker reconstruit l’historique validé du workflow après les activations et remplacements à froid ; la journalisation ordinaire de l’application peut donc répéter les messages précédents. Utilisez le logger conscient du replay documenté pour votre binding lorsqu’il existe. Le mode service Rust fournit le [logger de workflow de Rust SDK 4.17](../polyglot/rust.md#workflow-logging) ; les autres bindings conservent leurs contrats documentés séparément.
21+
22+
La journalisation est une observation du processus. Gardez les commandes durables indépendantes des observations du replay et de la livraison des logs. Même un logger conscient du replay peut répéter un message d’une tentative non validée après un crash ou un retry ; ce n’est pas une outbox garantissant exactement une fois. Les handlers hôtes doivent rester bornés et non bloquants pour ne pas immobiliser le worker. Placez les effets métier durables dans l’activité ou l’opération de workflow enregistrée appropriée.
23+
1824
## Contrôles au démarrage {#boot-time-guardrails}
1925

2026
Au démarrage, le package analyse les classes enregistrées dans `workflows.v2.types.workflows`. Il repère les appels manifestement incompatibles avec la relecture, comme `Carbon::now()`, `Auth::user()`, `DB::`, `Http::` et `random_int()`. La configuration `workflows.v2.guardrails.boot` détermine la réaction :

0 commit comments

Comments
 (0)