FlowStorm debugger User’s Guide

This is the newest and simplest way of using FlowStorm. It requires you to swap your official Clojure compiler by ClojureStorm only at dev time.

Swapping compilers sounds like a lot, but don’t worry, ClojureStorm is just a patch applied over the official compiler with some extra stuff for automatic instrumentation. You shouldn’t encounter any differences, it is only for dev, and you can swap it back and forth by starting your repl with a different alias or lein profile.

The easiest way to run and learn FlowStorm with ClojureStorm is by running the repl tutorial.

You can start a repl with FlowStorm like this :

Pasting that command on your terminal will bring up a repl with FlowStorm and the compiler swapped by ClojureStorm. When the repl comes up evaluate the :dbg keyword to bring up the UI and then click on Help→Tutorial on the menu for a tour of the basics.

After the tutorial you would want to add and configure it for your projects, or create a global config so here are the basics :

If your project is using deps.edn, your deps.edn file should look like this :

where YOUR_INSTRUMENTATION_STRING should be a comma separated list of namespaces prefixes like :

which means automatically instrument my-project.* (which includes all sub namespaces), all lib1.* and only everything under lib2.core

All this can be changed after without restarting your repl from FlowStorm browser.

This is probably what most people want since you don’t want to instrument things like nrepl, cider or any of your tooling stuff although you can still do it if you need it. There are also other options you can check with :help.

If your project uses lein, your project.clj file should look something like this :

with YOUR_INSTRUMENTATION_STRING as described above.

If you use the clojure cli you can start a repl with the FlowStorm dependency loaded like this :

If you are a lein user add the dependency to your project.clj :dependencies and run lein repl.

Then require the api namespace and start the debugger :

You should now see a empty debugger window. Click on the recording button to leave the debugger in recording mode and the let’s debug something:

After running it, you should get the return value of the expression (as if #rtrace wasn’t there), but now you will also have the debugger UI showing your recordings.

From here you probably want to check out the Flows tool which contains a lot of information about exploring your recordings.

For setting up FlowStorm with shadow-cljs you need to modify two files, your shadow-cljs.edn and your deps.edn. This is setup once and forget, so once you have configured FlowStorm you can do everything from the UI, without any other sources modifications.

If you want a shadow-cljs template to play with, take a look at this repo.

First, make your shadow-cljs.edn looks something like this :

So, the important parts are: you need to tell shadow to apply your deps.edn dev alias, set up a nrepl port, and also add flow-storm.storm-preload to your preloads. If you have other preloads make sure flow-storm.storm-preload is the first one.

Then, modify your deps.edn dev profile to look like this :

There are lots of things going on there, but the main ones are: disabling the official compiler, adding ClojureScriptStorm and FlowStorm dependencies, and then configuring what you want ClojureScriptStorm to automatically instrument.

It is important to configure what namespaces you want to instrument, and you do this by setting the cljs.storm.instrumentOnlyPrefixes jvm property.

This is a comma separated list of namespaces prefixes, you normally want your app namespaces plus some libraries, like : cljs.storm.instrumentOnlyPrefixes=org.my-app,org.my-lib,hiccup

And this is it. Once you have it configured, run your shadow watch as you normally do, load your app on the browser (or nodejs).

Whenever your need the debugger, on a terminal run the ui with your shadow-cljs.edn data :

and then reload you page so it connects to it.

Since we started the app with flowstorm.startRecording=false you will have to click on the record button once to start recording. Whenever recording is enable and something executes under an instrumented namespace you should see the recordings appear in the debugger under the main thread.

You can use FlowStorm and ClojureScriptStorm with cljs.main.

To compile instrumented files :

To run a repl that instrument everything under org.foo :

Then run the FlowStorm UI :

And now refresh your browser page so your browser app connects to the UI.

Let’s say you are using shadow-cljs to start a ClojureScript repl.

First you need to add FlowStorm dependency to your project dependencies, like this :

Then let’s say you start your repl like :

As you can see from the output log shadow-cljs started a nrepl server on port 9000, this is the port FlowStorm needs to connect to, so to start the debugger and connect to it you run :

And that is all you need, the debugger GUI will pop up and everything will be ready.

Try tracing some code from the repl :

After running it, you should get the return value of the expression (as if #rtrace wasn’t there).

The debugger thread list (the one on the left) shows all the threads it has recordings for. Because we are in javascript land there will always be just one thread, called main. Double clicking it should open the "thread exploring tools" for that thread in a new tab.

This guide will cover all the tools in more detail but if you are interested in code stepping for example you will find it in the code stepping tool at the bottom left corner of the thread tab, the one that has the () icon.

Click on it and use the stepping controls to step over the code.

Now that everything seems to be working move on and explore the many features FlowStorm provides. There are many ways of instrumenting your code, and many ways to explore its executions.

If you are not using a repl or the repl you are using isn’t supported by FlowStorm yet you can still use the debugger but not all features will be supported (mainly the browser features).

For this you can start the debugger like before but without any parameters, like this :

And then go to your app code and call (flow-storm.runtime.debuggers-api/remote-connect) maybe on your main, so every time your program starts will automatically connect to the repl.

Here is a repo you can use if you want to try FlowStorm with shadow-cljs https://github.com/flow-storm/shadow-flow-storm-basic

You can setup FlowStorm to debug multiple ClojureScript builds. This can be useful when your application is made up of multiple parts, like when you have web workers.

Debugging multiple builds require multiple debugger instances, one per build.

The FlowStorm UI will start a websocket server, by default on 7722, so if you want to run multiple instances of it, you need to run each instance under a different port. You can do this by providing a :ws-port to the startup command.

So let’s say you want to run two debuggers, one for your page and one for a webworker, your can run them like this :

Now you also need to configure your builds to tell them what port they should connect to. You do this by writing different preloads for each of your builds, and then using them instead of your flow-storm.storm-preload, like:

my_app.main_storm_preload.cljs

my_app.webworker_storm_preload.cljs

They are the same as flow-storm.storm-preload just with different port numbers.

Now you can configure your shadow-cljs.edn like this :

The code tool allows you to step and "travel throught time" in two ways:

For moving around using the controls we have two rows of buttons.

The second row of controls, the most imoprtant one, are the stepping controls.

From left to right they are :

The numbers at the center show current_step_index / total_steps. This means that a total of total_steps has been recorded for this thread so far. Write any number (less than total_steps) on the text box to jump into that position in time.

The buttons around the step counter are :

On the first row we have more controls, also for moving around in time.

From left to right we have :

This means that code can be un-highlighted for two reasons:

In the contrived example above we see we are stepping the foo function. All inside this function body is highlighted but the bodies of the two anonymous functions for mapping and reducing. This will only get highlighted once you step into their bodies.

In this case you are sure there are recordings for these functions bodies because the reduce is non lazy, so if you keep stepping eventually you will get into their bodies, but there is a faster way.

For this you can right click on any un-highlighted expression that you think there could be a recording for and select Jump forward here.

This will make FlowStorm scan from the current point of the timeline searching forward for a value recorded at that coordinate (if any) and move the stepper to that point in time.

You also have Jump to first record here which will scan from the beginning of the timeline and Jump backwards here which will search backwards from the current position.

The controls at the right are power stepping controls. They provide more powerfull ways of stepping through the code.

Clicking on the back and forward button will use the selected power stepping tool.

There are currently 5 power stepping tools :

You can use the search tool to search over all your recorded values. Find the search tool on the toolbar (the magnifier glass) or under View → Search.

The first row let us constrain our search to a specific Flow or Thread and also let us select one of two types of searches.

Search by pr-str let us provide a query string, a print-level and a print length and it will walk the specified timelines doing a pr-str over each recorded value and collect every entry where our query string is found inside the printed value. With bigger print-level/print-length you search deeper into values but it is also slower.

Search by predicate let us provide a predicate that will be applied over each recorded values to collect them. You can put whatever Clojure code you like here like (fn [v] (map? v)) to search over all recorded maps.

After configuring your search, click on the magnifier glass on the first row (next to the search type selection) to run the search. You should start seeing results as the match and you can always cancel the search by the normal means.

Double clicking on any of the search results will take you to that point in time.

Whenever you click a highlighted form that has been executed multiple times inside the same function call (any kind of loop), instead of immediately jumping into it, FlowStorm will popup a menu, like in the picture below :

This is the loops navigation menu. It allows you to quickly move around interesting iterations of the loop.

The menu will display slightly different options depending on you current position. The [FIRST] …​ and [LAST] …​ entries will always show, which allows you to quickly jump to the first and last iteration of the loop.

If you are currently before the loop, clicking into any expression inside the loop will show the first 20 values for the clicked expression.

If instead you are currently in a expression after the loop, clicking back to an expression inside the loop, will show the last 20 values for the clicked expression.

Now if you are currently stepping inside the loop, clicking any other expression inside it will show you 10 values before and 10 values after of your current position.

Clicking on any of this entries will take you to that position in time.

If this is not enough, and you want to see all the values taken by some expression along the loop, you can always use the printer tool.

FlowStorm will report all functions that didn’t return because an exception unwind the stack, even when that exception was captured further and it didn’t bubble up.

When an unwind situation is recorded a combobox will show up in the toolbar, containing all the functions names together with the exceptions types. If you hover the mouse over any of them, a tooltip will display the exception message.

Clicking on any of them will position the stepper at that point in time so you can explore what happened before.

The locals panel will always show the locals bounded for the current point in time.

Right clicking on them will show a menu where you can :

Define all frame vars will define all the bindings for the entire frame in the current form namespace. This is useful for trying things at your editor as described here https://www.cognitect.com/blog/2017/6/5/repl-debugging-no-stacktrace-required

The stack panel will always show the current stacktrace. Be aware that the stacktrace only include functions calls that had been recorded, so if you aren’t recording everything there will be gaps.

Double clicking on any of the stack entries will make the debugger jump to that point in time.

Value panels show in many places in FlowStorm.

The value panel in the code tool always display a pretty print of the current expression value.

You can configure the print-level and print-meta for the pretty printing by using the controls at the top.

Clicking on the Actions→Goto file:line menu allows you to search and jump to the first recording of a expression with a file and line, given that one exists.

It will ask you for a file and line in the format of <class-path-file-path>:<line>.

If you have a file like src/org/my_app/core.clj and you are interested in expressions evaluating on like 42 you should search like org/my_app/core.clj:42.

Clicking on the calls counter of any function will display all function calls on the right sorted by time. Each line will show the arguments vector for each call, and their return value. Use the check boxes at the top to hide some of the arguments.

Double clicking on any row in the functions call list will jump to the stepper at that point in time.

You can also use the args and ret buttons to open the values on the inspector.

You can instrument any top level form at the repl by writing #trace before it, like this :

and then evaluating the form.

#rtrace is useful in two situations :

First, when instrumenting and running a simple form at the repl, like:

FlowStorm allows you to instrument entire namespaces by providing flow-storm.api/instrument-namespaces-clj.

You call it like this :

The first argument is a set of namespaces prefixes to instrument. In the previous example it means instrument all namespaces starting with org.my-app.core, and all starting with cljs.

The second argument can be a map supporting the following options :

These are some limitations when instrumenting forms :

Un-instrumenting code that has been instrumented with #trace or #ctrace is straight forward, just remove the tag and re evaluate the form.

To un-instrument entire namespaces you can use flow-storm.api/uninstrument-namespaces-clj which accept a set of namespaces prefixes.

Most of the time you can instrument code by just clicking in the browser. The only exceptions are functions that were just defined in the repl and weren’t loaded from a file.