Observability

Stepflow provides a comprehensive observability system built for durable workflows. It includes structured logging, distributed tracing, metrics collection, and execution timelines for time-travel debugging.

The observability system is designed to be OpenTelemetry-compatible while providing Stepflow-specific context for better correlation.

Installation

Install the observability package:

pnpm add @stepflowjs/observability

Core Components

The observability system consists of four main components:

• Logging: Structured logging with correlation context (execution ID, step name).
• Tracing: Distributed tracing with OpenTelemetry-compatible spans.
• Metrics: Collection of counters, gauges, and histograms for monitoring.
• Timeline: Detailed execution history for time-travel debugging and visualization.

Quick Start

To enable observability in your Stepflow instance, use the createObservability provider:

import { Stepflow } from "@stepflowjs/core";
import { createObservability, ConsoleExporter } from "@stepflowjs/observability";

const observability = createObservability({
  serviceName: "my-workflow-service",
  exporters: [new ConsoleExporter()],
});

const stepflow = new Stepflow({
  // ... other config
  observability,
});

await observability.start();

Exporters

Exporters allow you to send observability data to external systems.

ConsoleExporter

Useful for development and debugging.

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

const exporter = new ConsoleExporter();

OTLPExporter

Used for production to send data to OpenTelemetry-compatible backends like Jaeger, Grafana Tempo, or Honeycomb.

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

const exporter = new OTLPExporter({
  url: "http://localhost:4318/v1/traces",
  headers: {
    "x-api-key": "your-key",
  },
});