Durable workflow traces

​

Recommended model

​

Parent versus link

• a retry starts after the earlier process or trace ended
• a checkpoint resumes in a new runtime instance
• one step combines several messages or upstream runs
• one completed step starts several independent branches

​

Retry example

const retrySpan = tracer.startSpan("workflow.step", {
  attributes: {
    "squasher.workflow.id": "invoice-delivery",
    "squasher.workflow.run_id": workflowRunId,
    "squasher.workflow.step": "send-email",
    "squasher.workflow.attempt": 2,
    "squasher.workflow.checkpoint_id": checkpointId,
  },
  links: [
    {
      context: previousAttemptSpanContext,
      attributes: { "squasher.link.reason": "retry" },
    },
  ],
});

​

Checkpoints and state changes

span.addEvent("workflow.checkpoint", {
  "squasher.workflow.checkpoint_id": checkpointId,
  "squasher.workflow.step": "await-approval",
});

​

Status and errors

• End each attempt span when that attempt stops running.
• Set span status to ERROR when an attempt fails.
• Record error.type and a safe error message.
• Record the final workflow outcome as a structured event or finite completion span.
• Keep timeout, cancellation, retry, and terminal failure as different outcomes.

​

Verify

1. Run one workflow that pauses and resumes.
2. Run one workflow that fails once and then succeeds.
3. Search by squasher.workflow.run_id and confirm every attempt appears.
4. Open the retry span and confirm its link opens the earlier attempt.
5. Confirm that no span remains open only because the workflow is waiting.

​

References

• OpenTelemetry span links
• OpenTelemetry messaging trace structure

​

Agent handoff

Instrument durable workflow <workflow_name> with finite OpenTelemetry spans. Use stable workflow and run attributes, create one span for each active attempt, record checkpoints as events, link retries or resumed work to the prior span context, do not invent a parent, and verify one pause/resume and one failed retry in Squasher.