Observability#

TanStack Workflow emits OpenTelemetry traces from the runtime and core engine. The packages depend only on @opentelemetry/api; your application owns the OTel SDK, exporter, collector, and provider setup.

If no OpenTelemetry SDK is configured, tracing is a no-op.

What is traced#

The runtime creates spans for:

• tanstack.workflow.start_run
• tanstack.workflow.deliver_signal
• tanstack.workflow.deliver_approval
• tanstack.workflow.sweep
• tanstack.workflow.drive_run

Store calls made by the runtime are traced as child spans, such as tanstack.workflow.store.claim_run, tanstack.workflow.store.append_events, and tanstack.workflow.store.claim_due_timers.

Fresh ctx.step executions create tanstack.workflow.step spans. Replayed steps do not create fresh step execution spans because no user step code ran.

Privacy defaults#

Workflow tracing intentionally does not record workflow input, workflow output, signal payloads, step results, or arbitrary step metadata as attributes.

Built-in attributes are stable identifiers and counts:

• tanstack.workflow.workflow_id
• tanstack.workflow.workflow_version
• tanstack.workflow.run_id
• tanstack.workflow.operation
• tanstack.workflow.result_kind
• tanstack.workflow.step_id
• tanstack.workflow.signal_name
• tanstack.workflow.schedule_id
• tanstack.workflow.bucket_id
• tanstack.workflow.lease_owner
• tanstack.workflow.event_count
• tanstack.workflow.events_truncated

If you want to add safe application attributes, pass telemetry.attributes or telemetry.mapStepMeta.

Configure tracing#

Initialize OpenTelemetry in your app before Workflow code runs. Then create the runtime normally:

import { defineWorkflowRuntime } from '@tanstack/workflow-runtime'

export const workflowRuntime = defineWorkflowRuntime({
  store,
  workflows,
})

Workflow uses the global OpenTelemetry tracer provider by default.

To customize Workflow tracing:

export const workflowRuntime = defineWorkflowRuntime({
  store,
  workflows,
  telemetry: {
    spanNamePrefix: 'tanstack.workflow',
    attributes: ({ workflowId }) => ({
      'app.workflow_id': workflowId ?? 'unknown',
    }),
    mapStepMeta: (meta) => ({
      'app.step_name': String(meta.name),
    }),
  },
})

Only use mapStepMeta for metadata you know is safe to export. Workflow does not export step metadata by default.

Disable tracing for a runtime:

export const workflowRuntime = defineWorkflowRuntime({
  store,
  workflows,
  telemetry: false,
})

Deployment notes#

Host adapters do not need separate tracing configuration. Netlify, Vercel, Cloudflare, and Railway helpers call runtime.sweep(), so they inherit the runtime spans automatically.

For serverless platforms, initialize the OpenTelemetry SDK in the platform's recommended instrumentation entrypoint. Workflow only emits spans through the OpenTelemetry API; exporter flushing and process lifecycle are app concerns.