FlowStorm Quickstart

FlowStorm is a time-travelling debugger for clojure.

IMO, Clojure has the best development experience with its REPL-driven workflow. FlowStorm makes it even better.

Most notably:

"time-traveling" retrospective debugger (walk forward and backward, search for values)
zero-config tap> destination
retroactively add print statements to previous evaluations
inject values found in the debugger back into your REPL

My recommended set-up is to create a global lein profile and/or global deps alias, so that enabling flowstorm on any project is painless:

Deps

In ~/.clojure/deps.edn:

{:aliases
 {:flowstorm
  {:classpath-overrides {org.clojure/clojure nil}
   :extra-deps {com.github.flow-storm/clojure {:mvn/version "RELEASE"}
                com.github.flow-storm/flow-storm-dbg {:mvn/version "RELEASE"}}
   :jvm-opts ["-Dflowstorm.startRecording=false"
              "-Dclojure.storm.instrumentEnable=true"
              "-Dclojure.storm.instrumentAutoPrefixes=true"]}}}

Example: clj -A:flowstorm -M:repl (if you have a repl alias)

Lein

In ~/.lein/profiles.clj:

{:flowstorm
 {:dependencies [[com.github.flow-storm/clojure "RELEASE"]
                 [com.github.flow-storm/flow-storm-dbg "RELEASE"]]
  :exclusions [org.clojure/clojure]
  :jvm-opts ["-Dflowstorm.startRecording=false"
             "-Dclojure.storm.instrumentEnable=true"
             "-Dclojure.storm.instrumentAutoPrefixes=true"]}}

Example: lein with-profile +flowstorm repl

VSCode + Calva

In addition to the above, in Calva extension settings:

Under Calva: My Clj Aliases add flowstorm
Under Calva: My Lein Profiles add flowstorm

Or, if you prefer json for your settings.json:

"calva.myCljAliases": [
  "flowstorm"
],
"calva.myLeinProfiles": [
  "flowstorm"
]

Usage

Start your REPL with the FlowStorm profile (see examples above). In the start-up log, you should see:

Storm instrumentation set to: true
ClojureStorm adding instrumentation auto prefix myproject

When the REPL is ready, you can open the FlowStorm UI by evaluating :dbg in the REPL.

In the FlowStorm UI open, hit the record button, back in your editor, evaluate some code, then view the code flow back in the FlowStorm UI. Check out the videos and the docs to learn what you can do in the FlowStorm UI.

Tips

Want to instrument a namespace outside of your project?

Add a folder and a fake file mimicking the library's structure under one of your source-paths, ex. src/ring/fake.clj will auto-instrument ring.*