FlowStorm debugger User’s Guide

There are two ways of using FlowStorm for Clojure :

ClojureStorm is a fork of the official Clojure compiler that adds automatic instrumentation so you don’t need to think about it (you can still disable it when you don’t need it). You use it by swapping the official Clojure compiler by ClojureStorm at dev time, using dev aliases or lein profiles.

Debugging ClojureScript is a case of remote debugging in FlowStorm. This means the debugger will run in a separate process and connect to the debuggee (your browser or nodejs runtime) via a websocket and optionally an nrepl server.

There are two ways of using FlowStorm with ClojureScript :

ClojureScriptStorm is a fork of the official ClojureScript compiler that adds automatic instrumentation so you don’t need to think about it (you can still disable it when you don’t need it).

You use it by swapping the official ClojureScript compiler by ClojureScriptStorm at dev time, using dev aliases or profiles.

You can debug your babashka scripts with FlowStorm using the JVM. The process is quite simple.

Let’s say we want to debug this example script https://raw.githubusercontent.com/babashka/babashka/master/examples/htmx_todoapp.clj which runs a webserver with a basic todo app.

First we need to generate a deps.edn by running bb print-deps > deps.edn

Then modify the resulting deps.edn to add the FlowStorm alias like this :

With clojure.storm.instrumentOnlyPrefixes=user we are telling ClojureStorm to instrument everything inside the user namespace since the script doesn’t contain any namespace declaration.

And that is it, you can now start your clojure repl as usual, with clj -A:dev and then eval the :dbg keyword to start the debugger UI.

Then eval the entire file to compile everything. To start the server in this example you will have to remove the wrapping that is basically only allowing the server to run if we are running from babashka, like this :

so we can also start it from Clojure.

After the server has started, you can use the app from the browser and everything will get recorded as usual.

The code tool is the first of the Flows tab. It provides most of the functionality found in a traditional debugger. You can use it to step over each expression, visualize values, locals and more.

The call stack tree tool is the second one of the Flows tab. It allows you to see the execution flow by expanding its call stack tree.

The call stack tree is useful for a high level overview of a complex execution and also as a tool for quickly moving through time.

You can jump to any point in time by double clicking on a node or by right clicking and on the context menu selecting Step code.

Use the button at the top left corner of the tree tool to show the current frame of the debugger in the tree.

There are also two value panels at the bottom that show the arguments and return value for the currently selected function call.

The functions tool is the third one of the Flows tab.

It shows a list of all traced functions sort by how many times the have been called.

Normal functions will be colored black, multimethods magenta and types/records protocols/interfaces implementations in green.

Together with the call stack tree it provides a high level overview of a thread execution, and allows you to jump through time much faster than single stepping.

You can search over the functions list by using the bar at the top.

You can use this tool to record, display and navigate a total order of your recordings in a timeline. This can be used, for example, to visualize how multiple threads expressions interleave, which is sometimes useful to debug race conditions.

You enable/disable the multi-thread timeline recording using its button on the toolbar. Recording on the multi-thread timeline will make your program execution a little slower so it is recommended to have it paused unless you need it.

When you have something recorded on the multi-thread timeline you access the tool from the top right corner.

As an example, let’s say you record the execution this function :

By opening the tool a window like this should pop up :

As you can see the timeline tool displays a linear representation of your expressions. Times flows from top to bottom and each thread gets assigned a different color. Every time a function is called or returns you will see it under the Function column, and for each expression executed you will see a row with its Expression and Value.

Double clicking any row will make your code stepper (on the main window) jump to the code at that point in time.

There is also a Only functions? checkbox at the top that will retrieve only function calls and can be used to visualize the threads interleaving at a higher level.

FlowStorm has a lot of functionality to replace printing to the console as a debugging method since most of the time it is pretty inefficient. Nonetheless, sometimes adding a bunch of print lines to specific places in your code is a very powerful way of understanding execution.

For this cases FlowStorm has the Printer tool, which allows you to define, manage and visualize print points, without the need of re running your code. It will work on your recordings as everything else.

You can add and re run print points over your recordings as many times as you need. To add a print point, just right click on any recorded expression.

It will ask you for a couple optional fields.

The Message format is the "println text". A message to identify the print on the printer output. Here you can use any text, in which you can optionally use %s for the printed value, same as you would use it with format.

The Expression field can be use to apply a transfomer function over the value before printing it. Useful when you want to see a part of the value.

After you add them, you can access the Printers tool by navigating to More tools → Printers.

The threads selector allows you to select the thread the prints are going to run on. Leaving it blank will run prints over all threads recordings (checkout the notes for caveats). Clicking the refresh button will [re]run the printing again over the current recordings.

You can tweak your prints at any time, like changing the print-length, print-level, message, transform-fn or just temporarily disable any of them. When you are ok re-setting you prints, just click refresh and they will print again.

Double clicking on any printed line will jump to the Flows code tab, with the debugger pointed to the expression that generated the print.

Bookmarks are useful when you find yourself jumping around, trying to understand a complex execution. They enable you to mark execution positions so you can come back to them later.

You can bookmark the current position by pressing the bookmark button in the code tool, next to your stepping controls. It will ask you the bookmark description.

You can find you bookmarks on the top menu View → Bookmarks.

Double clicking on any bookmark will make the debugger jump back to its position.

For using all the features in the Outputs tool you need to be using nrepl and start your repl with flow-storm.nrepl.middleware/wrap-flow-storm middleware.

If you use Cider for example you can add it to cider-jack-in-nrepl-middlewares via customizing the global value or by using .dir-locals.el.

The top panel is a data window for displaying evaluations and taps. As soon as you evaluate or tap something it will be displayed here.

The last evals pane gives you access to the last 10 evaluation results, same as *1 and *2.

Click on any value to display it on the top data window.

Everytime FlowStorm starts, it will add a tap, so whenever you tap> something it will show on the taps list.

Click on any value to display it on the top data window.

If the tapped value has also been recorded as an expression in Flows, you can right click on it and run Search value on Flows to move the debugger to that point in time.

A #tap tag will also be available, which will tap and return so you can use it like (+ 1 2 #tap (* 3 4)) Use the clear button to clear the list.

There is also #tap-stack-trace. It will tap the current stack trace.

Everything written on out or err will be captured and displayed on the bottom panel. You can copy anything from this area with normal tools.

You can navigate into any key or value by clicking on it.

Use the breadcrums at the top to navigate back.

If any value contains metadata, it will be shown at the top. Clicking on it will make the data window navigate into it.

You can change how to display your current value by using the visualizers selector dropdown at the top.

The seqable visualizer allows you to navigate all kind of sequences (even infinite ones) by bringing more pages on demand.

Click on More to bring the next page in.

You can always define a var for the current value being shown on any data window by clicking the def button. Clicking on it will raise a popup asking for a symbol name. If you don’t provide a fully qualified symbol it will define the var under user or cljs.user if you are in ClojureScript.

A quick way to use it is to provide a short name, let’s say foo, and then access it from your code like user/foo.

DataWindows not only support displaying and navigating values, but also updating them in real time from your application.

From your program’s code you can always create a data window with :

by providing a data window id, a value, and optionally the initial breadcrum label.

But you can also update it (given that the selected visualizer supports updating like :scope for numbers) with :

This data-window-val-update is pretty useful when called from loops or refs watches, specially paired with a custom visualizer.

Data Windows support datafy nav out of the box. The data window will always be showing the result of clojure.datafy/datafy of a value. For maps or vectors where keys provide navigation it will automatically add a blue arrow next to the value.

Clicking on the value will just dig the data, while clicking on the blue arrow will navigate as with clojure.datafy/nav applied to that collection on that key.

An important aspect of Data Windows is to be able to provide custom visualizers on the fly.

Let’s say we have model a chess board as a set of maps which represent our pieces.

If we open a data window with data-window-push-val we are going to see something like this :

but we can do better, we can create a custom visualizer so we can see it like this :

Data visualization in FlowStorm is composed of two things:

For a basic Clojure session everything will be running under the same process, but this is not the case for ClojureScript or remote Clojure.

First let’s require some namespaces :

We can register a custom visualizer by calling register-visualizer.

The important part there are :id, :pred, and :on-create.

The :id will be the one displayed on the visualizers dropdown, and re-registering a visualizer with the same id will replace the previous one.

:pred is a predicate on the data extracted from values, it should return true if this visualizer can handle the value.

And :on-create will be a function that receives this value and renders a java fx node.

Optionally you can provide :on-update and :on-destroy.

:on-update will receive values from the runtime via fsa/data-window-val-update. It will also get a handle to the original value (the one that created the DataWindow) and whatever map was returned by :on-create.

:on-destroy will be called everytime a visualizer gets removed, because you swapped your current visualizer or because you went back with breadcrums. It can be useful in case you need to clear resources created by :on-create.

:pred and :on-create will not recieve the original value but the extracted aspects of it after all registered extractors run.

You can check the data available to your visualizer for a value in a data window by calling :

If the data already extracted from your value is not enough for your visualizer you can register another extractor.

You can make any visualizer the default by calling add-default-visualizer which takes a predicate on the val-data (the same received by :on-create) and a visualizer key, like this :

For all FlowStorm provided visualizers take a look at flow-storm.debugger.ui.data-windows.visualizers namespace.

Default visualizers predicates are added in a stack, and tried from the top. This means that you can always overwrite a default by adding a new one.

Let’s say you want to explore recordings on thread 32. You can retrieve its timeline by calling ia/get-timeline like this :

Once you have the timeline you can start exploring it.

The timeline implements many of the Clojure basic interfaces, so you can :

The easiest way to take a look at a thread timeline is with some code like this :

In most cases converting all entries into maps with ia/as-immutable is enough, but if you want a little bit more performance you can access entries information without creating a immutable map first.

Timelines entries are of 4 different kinds: FnCallTrace, FnReturnTrace, FnUnwindTrace and ExprTrace.

You can access their data by using the following functions depending on the entry :

All kinds :

ExprTrace, FnReturnTrace and FnUnwindTrace :

ExprTrace, FnReturnTrace :

FnUnwindTrace :

FnCallTrace :

You can also access the timeline as a tree by calling :

Take a look at their docstrings for more info.

You can retrieve forms by form id with get-form and then use get-sub-form-at-coord and a coordinate.

Here is a little example :

If you have recorded a multi-thread timeline, you can retrieve it with total-order-timeline like this :

which you can then iterate using normal Clojure functions (map, filter, reduce, get, etc).

The easiest way to explore it is again with some code like this :

Notice that each of these entries contains a flow-id and thread-id also.

There are other utitities in the api ns that could be useful, some of the most interesting ones :

Take a look at their docstrings for more info.

If you run you process inside a docker container, here is a basic template for using FlowStorm with it https://github.com/flow-storm/docker-flow-storm-basic

The first important thing is to setup your instrumentation correctly via JVM properties :

On ClojureStorm :

On ClojureScriptStorm :

Apart from instrumentOnlyPrefixes which you probably already know, there is instrumentSkipPrefixes which also accepts a comma separated list of namespaces prefixes to skip, and instrumentSkipRegex with accepts a regex for namespaces to skip. All these together allows you to instrument you whole app but some undesired namespaces.

The next important thing is to be able to enable/disable instrumentation and add/remove prefixes without restarting the repl.

You can use the Browser tool to check and change on the fly the prefixes you configured in the previous section.

Right clicking any namespace will give you options for what level of a namespace you want to instrument.

On the bottom pane (instrumentations) you will see your current instrumentation configution (if any). Here we can see that everything under ring.middleware.anti-forgery will be instrumented every time something inside it gets compiled.

You can remove entries using the del buttons or temporarly disable/enable them using the Enable all checkbox.

You can use the Add menu in the picure above to add instrumentation prefixes.

After changing any prefix FlowStorm will ask if you want it to reload the affected namespaces for you. Namespace reloading will all reload all namespaces it depends on in topological order, so it shoulnd’t break your system in any way.

You can also provide functions to be called before and after reloading in case you need to stop and start your system with :

Code instrumentation in FlowStorm is done by rewriting your code, in a way that doesn’t change its behavior but when executed will trace everything the code is doing.

Checkout Cider Storm an Emacs Cider front-end with support for Clojure and ClojureScript.

FlowStorm UI requires JDK >= 17. If you can’t upgrade your JDK you can still use it by downgrading JavaFx.

If that is the case add these dependencies to your alias :