Observable by design.

ObzenFlow is designed to be understandable at every level. Read any run as one causal timeline with the ObzenFlow CLI. Monitor a running flow through metrics that come directly from wide events, the source of truth. Visualize a running flow on one canvas in ObzenFlow Studio, now in development.

CLI

Observability comes straight from event-sourced wide events.

Every stage journals the actual record of execution, and each record also carries the conditions during execution. The ObzenFlow CLI shows you both, which makes it uniquely powerful for observability.

Your journals are a superpower for root cause analysis.

Every decision that matters is recorded to the journal and inspectable. Here, two records from one run show how the payment for order store-4475 failed.

  1. What was decided

    The first record is the gateway call’s outcome, a timeout. The second is the fact authorize_payment recorded from it, payment.authorization_unavailable.

  2. Which came first

    Each record carries its place in the run’s logical clock, so you can see the fact follow the timeout in the same stage’s journal.

  3. Why

    Both records carry the same cause. The gateway timed out, so no answer came back.

obzenflow show · payment_gateway_resilience
EFFECT (stage: authorize_payment, journal: 4)
effect.execution_failed ← authorize_payment(payment.order_validated)
⟨1:3,2:11,3:9,4:57,5:11,6:2,7:2,8:2,9:2,10:2⟩
idempotency key: payment-authorize:store-4475
payload schema version: 1
{
  "effect_type": "payment.authorize",
  "observation": {
    "observation": "execution_failed",
    "authority": "port_return",
    "external_completion": "unknown"
  },
  "outcome": "failed",
  "error_type": "timeout",
  "error_message": "processor_timeout_simulated",
  "retry": "retryable"
}

EFFECTFUL TRANSFORM (stage: authorize_payment, journal: 4)
payment.authorization_unavailable ← authorize_payment(payment.order_validated)
⟨1:3,2:11,3:9,4:58,5:11,6:2,7:2,8:2,9:2,10:2⟩
payload schema version: 1
{
  "amount_cents": 1800,
  "customer_id": "cust-3741",
  "order_id": "store-4475",
  "phase": "Outage",
  "reason": "processor_timeout_simulated"
}

Logical clocks show what happened before what.

Every record carries a vector clock, which basically is its own view of order at the time that the record was written.

ObzenFlow has total order per journal and causal order across journals. You can see here that validate_order doesn’t necessarily know or care about what’s happening in store_orders or web_orders unless it attempts to validate an order. That’s causal order. That’s how we maintain ordering without coupling to wall-clock time.

This may seem unimportant, but it’s a debugging superpower to understand what a particular journal’s understanding of ordering across the entire system was at the time it finalized an event.

  1. Concurrent orders stay concurrent

    store_orders and web_orders don’t communicate directly, so they have no opinion on what happened before what, and they don’t need to.

  2. Each record shows what its stage had seen

    When validate_order sees store_orders, its own clock is updated based on its understanding, but its view of web_orders doesn’t change.

  3. History carries forward

    Eventually validate_order visits a web order, and its own clock is incremented and its view of web_orders is updated. This is causal order.

Every record contains its causality, history, and agency.

Every stage journal stores wide events. Beside the payload, each record carries the id of the source event that entered the flow, the ids of the records it was made from, the outcome and event time, and the effect call that produced it. When someone asks why order store-4471 was authorized, the answer is in this record and the records it points to, with no log line or trace to find.

  1. Start with the correlation id

    Every record derived from the store order carries the id minted when it entered the flow, in every stage journal. Filter obzenflow show --jsonl on that id and you have the order’s whole story, from the store order to this authorization and its delivery. For most questions that is the answer.

  2. Use causality when one fact has many sources

    A running balance is made from dozens of postings and a join from several orders, so filtering on one order finds the output but not the rest of what went into it. Causality names the records an emission was made from, and a keyed output also points at its previous output, so the lineage of a join or a balance is complete.

  3. See the call that produced it

    Processing records the outcome and the event time. The effect cursor names the stage, the input and the call that produced this fact, so replay returns the recorded gateway decision instead of calling the gateway again.

  4. Read the fact

    The payload is the authorization as the stage recorded it, and it is never edited or deleted. A correction is a new fact appended after it. Societies have run on append-only journals of facts since double-entry accounting.

obzenflow show --full
{
  …
  "kind": "stage_output",
  "record": {
    "envelope": {
      "provenance": {
        "event": {
          "id": "3F2QN67Z2VNN3QTP5680D9PGDF",
          …
          "causality": {
            "parent_ids": [
              "01M5WS0C35F1RD3A1YKT9W3HQJ",
              "01M5WS0C33TJAA9R26FX679W6H"
            ]
          },
          …
          "processing": {
            "event_time": 1000,
            "status": "Success"
          },
          "correlation": {
            "ids": ["01M5WS0C33NA8DK0CKANZ75FR3"]
          },
          "effect_provenance": {
            "cursor": {
              "stage_key": "authorize_payment",
              "input_seq": 1,
              "effect_ordinal": 0
            },
            …
    "payload": {
      "amount_cents": 8640,
      "authorization_id": "AUTH-DEMO-1234",
      "customer_id": "cust-1187",
      "order_id": "store-4471",
      "phase": "Warmup"
    }
  }
}

Read and check every run from the terminal.

The ObzenFlow CLI ships in the main repository behind the cli feature. It reads a run’s journal files directly, during the run or long after it, and never alters them.

  1. Show the journals

    Read the event-sourced records themselves: every stage’s facts in one causal timeline, with what caused each one.

  2. Inspect the manifest

    See how a run ended, which schema wrote it, which journal file holds each stage, and where every record sits, without opening a single record.

  3. Verify two runs

    Compare a replay with its original run. The verdict comes back as an exit code your CI can act on.

$ obzenflow show $RUN --compact
EFFECT  effect.execution_failed ← authorize_payment(payment.order_vali… [--full]
EFFECTFUL TRANSFORM  payment.authorization_unavailable ← authorize_pay… [--full]
DELIVERY  delivery.succeeded ← manual_review(payment.authorization_una… [--full]
DELIVERY  delivery.succeeded ← paid_orders(payment.authorized)  {"subj… [--full]
TRANSFORM  payment.order_validated ← validate_order(commerce.customer_… [--full]
EFFECTFUL TRANSFORM  payment.authorized ← authorize_payment(payment.or… [--full]
EFFECTFUL TRANSFORM  payment.authorized ← authorize_payment(payment.or… [--full]
$ obzenflow inspect $RUN
flow_id:    flow_01M7H7NPKCNKY87R8P9N65E8J1
flow_name:  payment_gateway_resilience_demo
status:     Completed
schema:     23.0
stages:     9

[authorize_payment] Transform_authorize_payment_stage_01M7H7NPK6HM6T7H9MK2GF4W97.log (Transform)
           0  supervisor.stage.authorize_payment.registered
         510  supervisor.stage.authorize_payment.ready
$ obzenflow verify --baseline $RUN --candidate $REPLAY
output matched the original run, 0 differences

Metrics

Metrics come directly from the source of truth.

Four of the flow’s built-in endpoints are for monitoring. An aggregator tails every stage journal and folds the records into the counts, rates and histograms Prometheus scrapes, and the live stream reads the same journals for each connection, so every number and every frame traces back to a record you can open with the CLI. The two probes need neither the journals nor authentication.

One scrape serves the golden signals, RED and USE.

With the prometheus feature on, /metrics serves the aggregator’s latest snapshot. Every series is folded from journal records, so the standard methods need no instrumentation in your handlers. The repository includes Grafana dashboards for the flow and for each stage.

  1. Golden signals for the flow

    Traffic as events in from sources and out through sinks, errors across every stage, latency end to end as a histogram, and saturation as flow utilization.

  2. RED for every stage

    Rate from the stage’s event counter, errors by kind from its error journal, and duration as a histogram of processing time with the standard Prometheus buckets.

  3. USE for every stage and edge

    Utilization from the stage’s rate limiter. Saturation from each edge’s remaining credits, events in flight and time spent blocked. Errors are the counters RED already reads, and an edge’s contract lag sits here too.

GET /metrics
obzenflow_flow_events_in_total{flow="payment_gateway_resilience_demo",…} 25
obzenflow_flow_events_out_total{flow="payment_gateway_resilience_demo",…} 20
obzenflow_flow_errors_total{flow="payment_gateway_resilience_demo",…} 0
obzenflow_flow_latency_seconds_bucket{…,le="1"} 18
obzenflow_flow_latency_seconds_bucket{…,le="+Inf"} 20
obzenflow_flow_utilization{flow="payment_gateway_resilience_demo",…} 0.62

obzenflow_events_total{stage="validate_order",…} 25
obzenflow_events_total{stage="authorize_payment",…} 17
obzenflow_errors_total{stage="authorize_payment",…} 0
obzenflow_processing_time_seconds_bucket{stage="authorize_payment",le="1",…} 15
obzenflow_processing_time_seconds_bucket{stage="authorize_payment",le="+Inf",…} 17

obzenflow_rate_limiter_utilization{stage="web_orders",…} 0.91
obzenflow_backpressure_credits{downstream="authorize_payment",…} 1
obzenflow_backpressure_in_flight{downstream="authorize_payment",…} 7
obzenflow_backpressure_wait_seconds_total{stage="validate_order",…} 3.4
obzenflow_contract_lag_events{contract="DeliveryContract",…} 0

Each change arrives as a frame with its journal position.

/api/flow/events is a server-sent events stream. A connection opens its own readers over the stage and system journals, reads what it has not yet seen, then tails them, projecting each record into a frame named for what changed.

  1. A frame per change

    Stage lifecycle, throughput, breaker and rate limiter transitions and contract results each arrive under their own event: name, with the JSON for that change in data:.

  2. Each frame carries its commit

    The data names the journal commit the frame was projected from, its sequence and its vector clock, so a frame can be matched to the record obzenflow show prints.

  3. Reconnect where you left off

    The last frame of every batch carries an id: holding each journal’s applied position. Send it back as Last-Event-ID and the new connection continues from those positions instead of reading the journals from the start.

GET /api/flow/events
event:bootstrap
data:{"event_type":"flow_bootstrap",…}

event:stage_lifecycle
data:{…,"event_type":"stage_running","commitment":{…,"sequence":61,…},…}

event:throughput_update
data:{"stages":[{…,"measurement":{"events_per_second":4.8,…}},…],…}

event:middleware_lifecycle
data:{…,"middleware":"circuit_breaker",…,"state_to":"open",…}

event:contract_result
data:{…,"reader_seq":10,"contract_name":"DeliveryContract","status":"passed",…}
id:jr1:{"01M5WS0BYJ…":61,"01M5WS0BYK…":14,…}

The process itself answers liveness and readiness.

/health says the process is up. /ready says the flow is running. Neither opens a journal and both skip authentication, so load balancer and Kubernetes probes can call them as they are.

  1. Liveness

    /health answers 200 OK for as long as the process is up, whatever state the flow is in.

  2. Readiness

    /ready answers 200 READY only while the flow is running. Before that point, and from the moment it starts draining, it answers 503 NOT_READY, so a load balancer stops routing to it while it drains.

GET /health · GET /ready
GET /health
200 OK

GET /ready
200 READY

GET /ready            # while draining
503 NOT_READY

Studio

Your flow at a glance.

When something goes wrong in a running flow, the answer is usually scattered across dashboards, logs, and tribal knowledge. ObzenFlow Studio, now in development, puts the whole operational surface in one place.

What does your flow look like right now?

ObzenFlow Studio renders your flow’s topology directly from the running server. Stages appear as colour-coded nodes: green for sources, blue for transforms, purple for sinks, orange for routers, yellow for joins. Connections route around obstacles so dense topologies stay readable. Stages in cycles are marked so feedback loops are visible at a glance.

Four zoom tiers control what level of detail is on screen. Pull back for a bird’s-eye overview of the full graph. Zoom in to see per-stage latency percentiles and middleware state. The layout scales cleanly whether your flow is three stages or a graph with dozens of stages, fan-out, fan-in, and feedback.

No architecture diagram to maintain. No stale Miro board. The topology on screen is the topology that is running.

Where's the bottleneck?

Metrics update every second from the flow’s Prometheus-compatible endpoint. Flow-level numbers appear in a bottom panel: total events in and out, throughput rates, flow utilization, and total errors. Each stage displays its own RED metrics directly on the node: rate (events per second), errors (percentage), and duration (P50 and P99 latency), alongside stage state and middleware status when enabled.

Backpressure is visible on the canvas too. When a stage is blocked, ObzenFlow Studio shows which downstream stage is the bottleneck, the minimum credit level, and the in-flight count at the congested edge. The bottleneck is a visual, not something you infer from a dashboard query.

What broke, and when?

Circuit breakers and rate limiters are visible directly on the stage they protect. Circuit breakers show their current state (closed, open, or half-open), rejection rate, consecutive failure count, and how long they have been in each state. When a breaker opens, the visual treatment changes immediately. No need to check Prometheus or parse logs to know a dependency is failing.

Rate limiters show their current mode, utilization percentage, events in the current window, and how many events have been delayed. Token bucket capacity and current token count are visible. When a limiter begins throttling, the stage pulses to draw attention.

These are the same production-grade primitives you declared in your flow definition. ObzenFlow Studio surfaces their runtime state so you can see them working, not just trust that they are.

Did events actually arrive?

Every connection in the topology displays the contract status for that edge. Passing contracts show a green badge. Violations show red. Overrides show orange. Pending shows grey. The evidence is continuous, not something you query after the fact. A delivery violation is visible the moment it happens, at the exact point in the topology where it occurred.

Select an edge and ObzenFlow Studio reveals the full evidence: result counts, violation counts, override counts, and the specific reasons when violations occur, whether that is a sequence divergence, a timestamp misalignment, or a lag event.

Most runtimes treat delivery guarantees as a configuration setting you trust. ObzenFlow Studio turns them into evidence you can watch. The badge on the edge is either green or it is not.

Is the flow running?

ObzenFlow Studio provides direct lifecycle control. Start a flow and stop it gracefully, draining in-flight events before shutdown. The current state is displayed prominently and colour-coded across the full lifecycle: starting, running, draining, completing, drained, completed, cancelled, or failed.

Button states are driven by the actual flow state received from the server, so controls always reflect reality rather than assumed state. When a flow finishes or fails, the duration and final state appear immediately.

Flow in draining state with lifecycle indicator

How does ObzenFlow Studio connect?

ObzenFlow Studio is compiled to WebAssembly from the same Rust codebase as the framework. Building ObzenFlow from source includes the visual tooling with no additional runtime dependencies. No Electron app. No separate install. No SaaS dashboard to configure.

Enable the server in your flow’s config and it exposes topology, metrics, and event streams. Launch the ObzenFlow Studio UI and it connects to those endpoints automatically. The topology loads, stages appear on the canvas, and connections are drawn. From that moment, every state change, every metric update, and every middleware event streams to the UI as it happens.

➜ obzenflow git:(main) cargo run -p obzenflow \
--example prometheus_demo \
--features prometheus,web-host -- \
--config examples/prometheus_demo/obzenflow.prometheus.toml

What changes for your team

Runtime concepts become visible

Watch events move through the topology, see rate limiters begin throttling, and observe circuit breakers open and recover on the canvas.

Incidents get more direct

Instead of querying metrics, correlating timestamps, or asking what the topology looks like, the current state is visible where the problem is happening.

Onboarding gets easier

A whiteboard sketch becomes a running demonstration, so teams can learn backpressure, circuit breaking, and delivery contracts from the live system.

Start building today.

ObzenFlow Studio is in development and not yet released. Until then, learn exactly how to build ObzenFlow applications.