Skip to content

Automatic trace context propagation across workflow steps #679

@bixu

Description

@bixu

Problem

When using OTel tracing with swamp extensions, operators must manually wire trace context (traceId, parentSpanId) between workflow steps using CEL expressions and step dependencies. This is boilerplate that every traced workflow needs, and it's error-prone (wrong CEL paths, forgetting to add dependencies, etc.).

For example, to get a connected trace waterfall from a multi-step workflow, the current approach requires:

  1. Creating a dedicated root span step via the @bixu/opentelemetry model
  2. Adding dependsOn from every job to the root span job
  3. Manually passing traceId and parentSpanId via CEL expressions in every step's inputs

This defeats the purpose of having observability — it should be automatic.

Proposed Solution

Related to #677 (native OTel tracing for swamp internals): once swamp has built-in tracing, trace context should propagate automatically through the workflow execution hierarchy:

  • Workflow run creates a root span
  • Each job creates a child span under the workflow span
  • Each step creates a child span under the job span
  • Extension method execution receives the step's trace context automatically via the execution context, so extension-emitted spans become children of the step span

This means:

  • No manual traceId/parentSpanId inputs needed on methods
  • No extra dependsOn for trace context
  • Extension models that emit their own spans (like @bixu/github/repo) automatically appear as children in the trace waterfall
  • A single trace shows the complete workflow → job → step → API call hierarchy

Alternatives Considered

  • Current approach (manual CEL wiring): Works but requires significant boilerplate in every workflow, and operators have to understand OTel internals to get connected traces
  • Injecting trace context via global args: Would reduce per-step boilerplate but still requires model authors to handle propagation explicitly

Additional Context

This is a follow-on to #677. The extension-level tracing we've built (traced() helper with traceId/parentSpanId pass-through) works as a proof-of-concept, but highlights that the right place for context propagation is in swamp's workflow engine, not in user-space workflow YAML.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestexternalAn issue raised by an external contributor

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions