Tracing

Stepflow includes a distributed tracing system that is compatible with OpenTelemetry. It allows you to track the execution flow of your workflows across different services and steps.

StepflowTracer

The StepflowTracer manages spans and context propagation.

import { createTracer } from "@stepflowjs/observability";

const tracer = createTracer({
  config: {
    serviceName: "workflow-engine",
    enabled: true,
    sampleRate: 1.0,
  },
});

Spans

A span represents a single unit of work. Spans can be nested to create a hierarchy.

const span = tracer.startSpan("process-order", {
  attributes: { "order.id": "123" },
});

try {
  // Do work
  span.addEvent("validation-complete");
  span.setStatus("ok");
} catch (error) {
  span.setStatus("error", error.message);
  throw error;
} finally {
  span.end();
}

Span Helpers

Stepflow provides helpers to automatically manage span lifecycle and context.

withSpan

Executes a synchronous function within a span.

const result = tracer.withSpan(span, () => {
  return doWork();
});

withSpanAsync

Executes an asynchronous function within a span.

const result = await tracer.withSpanAsync(span, async () => {
  return await doWorkAsync();
});

Context Propagation

Stepflow automatically propagates trace context through workflow executions and steps, ensuring that all spans related to a single execution are correctly correlated.

Configuration