Metrics

Stepflow allows you to collect dimensional metrics to monitor the health and performance of your workflows.

StepflowMetrics

The StepflowMetrics collector manages different types of metric instruments.

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

const metrics = createMetrics({
  config: {
    enabled: true,
    prefix: "stepflow",
  },
});

Metric Types

Counters

Monotonically increasing values, useful for counting events.

const counter = metrics.counter("orders_total", "Total number of orders");

counter.inc(); // Increment by 1
counter.inc(5); // Increment by 5

Gauges

Values that can go up and down, useful for tracking current state (e.g., queue depth).

const gauge = metrics.gauge("active_executions", "Number of active executions");

gauge.set(10);
gauge.inc();
gauge.dec();

Histograms

Track the distribution of values, useful for latencies.

const histogram = metrics.histogram(
  "step_duration_ms",
  "Step execution duration",
);

histogram.observe(150);

Labels

All metrics support dimensional labels for fine-grained filtering and grouping.

counter.inc(1, { workflow: "welcome-email", status: "success" });
gauge.set(5, { region: "us-east-1" });

Timer Helper

Histograms include a timer helper to easily measure durations.

const stopTimer = histogram.startTimer({ step: "send-email" });

await sendEmail();

const duration = stopTimer(); // Returns duration in ms and records it

Configuration

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Whether metrics collection is enabled
`prefix`	`string`	`"stepflow"`	Prefix for all metric names
`defaultLabels`	`MetricLabels`	`{}`	Default labels applied to all metrics
`defaultBuckets`	`number[]`	[...]	Default histogram buckets for latency

Metrics

On this page