How Journaling Works
The best way to understand journaling is to see it in action. The examples below show a payment workflow with three steps. On first execution, each step runs normally and its result is journaled. If the workflow crashes and replays, completed steps return their journaled result instantly — the external API calls never happen again.
1use orcher::prelude::*;2use anyhow::Result;34#[task]5pub async fn charge_card(_ctx: TaskContext, input: PaymentInput) -> Result<ChargeResult> {6 // Call Stripe API...7}89#[task]10pub async fn reserve_inventory(_ctx: TaskContext, order_id: String) -> Result<InventoryResult> {11 // Reserve stock...12}1314#[task]15pub async fn send_confirmation(_ctx: TaskContext, charge_id: String) -> Result<()> {16 // Send email...17}1819#[workflow]20pub async fn payment_workflow(21 ctx: WorkflowContext,22 order: OrderInput,23) -> Result<PaymentResult> {24 // Step 1: Charge card25 // First execution: Executes and journals result26 // Replay: Returns journaled result without re-executing27 let charge: ChargeResult = ctx28 .execute_task(charge_card, order.clone())29 .await?;3031 // If crash happens here, step 1 is already journaled3233 // Step 2: Reserve inventory34 // First execution: Executes and journals result35 // Replay: Returns journaled result36 let inventory: InventoryResult = ctx37 .execute_task(reserve_inventory, order.id.clone())38 .await?;3940 // Step 3: Send confirmation41 // Always executes (not in journal yet)42 ctx.execute_task(send_confirmation, charge.id.clone()).await?;4344 Ok(PaymentResult {45 charge_id: charge.id,46 reserved: inventory.reserved,47 })48}Execution vs Replay
The diagram below contrasts what happens during a workflow's first execution versus a replay after a crash. On first execution, each step runs its real logic and the result is journaled. On replay, the SDK loads the journal and returns cached results — the original code is never re-invoked.
Under the Hood
This section traces the full path a step takes — from your SDK call, through the server's command processor, into PostgreSQL, and back out during replay. Understanding this flow helps you reason about what happens when things go wrong.
Two Storage Layers
| Layer | Table | Key | Purpose |
|---|---|---|---|
| Execution Log | execution_log | (workflow_id, step_name) | Step-level idempotency cache. Stores result, status, attempt count. Used for ctx.execute() replay protection. |
| Journal | workflow_execution_journal | (workflow_id, execution_id, event_id) | Append-only event history. Full audit trail. Provides the entries that drive replay via journal_to_jobs(). |
In-Memory Cache (HighPerfCache)
Orcher uses a Moka-based cache to avoid hitting PostgreSQL on every replay:
- TTL: 60 seconds per entry
- Max entries: 5,000 cached journals
- Incremental loading: On cache hit, only loads entries with
event_id > max_cached_event_id(partial DB query instead of full reload) - Optimistic append: When a new entry is written, it's appended to the in-memory cache immediately (no DB roundtrip to refresh)
- Metrics:
journal_hits,journal_misses,journal_hit_rate()tracked for observability
Journal Entry Structure
Each entry in the workflow_execution_journal table:
1{2 "id": 12345,3 "workflow_id": "order-processing-abc123",4 "execution_id": "exec_xyz789",5 "event_id": 3,6 "event_type": "StepCompleted",7 "timestamp": "2024-01-15T10:30:45.123Z",8 "payload": {9 "step_name": "charge_card",10 "result": {11 "charge_id": "ch_abc123",12 "status": "succeeded"13 }14 },15 "version": 0,16 "task_id": 456,17 "organization_id": "org_123",18 "shard_id": 0,19 "created_at": "2024-01-15T10:30:45.123Z"20}Journal Entry Types
Orcher records different types of entries throughout workflow execution:
Step Events
Step events track the completion of individual operations within a workflow. These are the most common entry type and drive the replay mechanism.
StepCompleted— A step finished (inline closure, distributed task, child workflow, or side effect). This is the primary entry type that drives replay.
Workflow Lifecycle
These events mark the major state transitions of a workflow execution — from start through completion, failure, cancellation, or timeout.
WorkflowExecutionStarted— Workflow begins executionWorkflowExecutionCompleted— Workflow completes successfullyWorkflowExecutionFailed— Workflow fails with errorWorkflowExecutionCanceled— Workflow is cancelledWorkflowExecutionTimedOut— Workflow exceeds timeoutWorkflowExecutionRestartedFresh— Workflow restarted with clean state
Task Events
Task events track the lifecycle of distributed tasks dispatched to task queues. These entries record when a task is scheduled, completes, fails, or is cancelled.
TaskScheduled— Task dispatched to task queueTaskCompleted— Task completes successfullyTaskFailed— Task fails with errorTaskCanceled— Task is cancelled
Signal and Event Events
Signal events record inter-workflow communication. These track when external events are delivered to a workflow or when a workflow sends a signal to another workflow.
EventReceived— External signal/event delivered to workflow (data is base64-encoded in the payload field)ExternalEventSent— Workflow sent a signal to another workflow
Child Workflow Events
Child workflow events track the full lifecycle of workflows spawned by a parent. These entries enable the parent to monitor and replay child workflow results.
ChildWorkflowExecutionInitiated— Child workflow createdChildWorkflowExecutionStarted— Child workflow begins runningChildWorkflowExecutionCompleted— Child workflow completesChildWorkflowExecutionFailed— Child workflow failsChildWorkflowExecutionTimedOut— Child workflow exceeds timeoutChildWorkflowExecutionCanceled— Child workflow is cancelled
Timer Events
Timer events record durable sleeps and delays within a workflow.
TimerFired— Timer/sleep completes