FlowStorm

https://flow-storm.github.io/flow-storm-debugger/
Admin
FlowStorm is a tracing debugger for Clojure and ClojureScript that instruments code and provides...
Tokens:18,606
Snippets:231
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Vanilla FlowStorm Setup with Clojure CLI

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use these commands to start a REPL with the FlowStorm debugger dependency loaded via the Clojure CLI. Adjust the command based on your operating system.

```bash
;; on Linux and OSX
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}'
```

```bash
;; on Windows
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}'
```

--------------------------------

### Start FlowStorm REPL (Linux/OSX)

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use this command to start a Clojure REPL with FlowStorm and ClojureStorm automatically instrumented. Evaluate :dbg to open the UI.

```bash
clj -Sforce -Sdeps '{:deps {} :aliases {:dev {:classpath-overrides {org.clojure/clojure nil} :extra-deps {com.github.flow-storm/clojure {:mvn/version "1.12.5"} com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}}}' -A:dev
```

--------------------------------

### Start App Debugger Instance

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Run this command in one terminal to start the application debugger instance. Ensure the correct version and ports are specified.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-app :ws-port 7722
```

--------------------------------

### Start ClojureScript REPL with FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use this command to start a ClojureScript REPL with FlowStorm preloaded and instrumenting code under `cljs.user`. This command also opens a browser connected to the REPL.

```bash
clj -Sforce -J-Dcljs.storm.instrumentOnlyPrefixes=cljs.user -Sdeps '{:deps {com.github.flow-storm/clojurescript {:mvn/version "1.12.134-3"} com.github.flow-storm/flow-storm-inst {:mvn/version "4.5.9"}}}' -M -m cljs.main -co '{:preloads [flow-storm.storm-preload]}' --repl
```

--------------------------------

### Shadow-cljs Configuration for Multiple Builds

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Example of shadow-cljs.edn configuration to define multiple builds, including an application and a webworker, each with its own preload.

```clojure
{...
 :builds
 {:app
  {:target :browser
   ...
   :modules
   {:my-app {:init-fn my.app/init
           :preloads [my-app.main-storm-preload]}
    :my-webworker {:init-fn my.app.worker/init
                   :preloads [my-app.webworker-storm-preload]
                   :web-worker true}}}}}
```

--------------------------------

### Install Thread Breakpoint

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Install a thread breakpoint by calling `break-at` with the function symbol. Optionally, provide a predicate function to break only when specific conditions are met.

```clojure
(flow-storm.api/break-at 'my-proj.core/some-fn)
```

```clojure
(flow-storm.api/break-at 'my-proj.core/some-fn (fn [arg1 arg2] (> arg1 arg2)))
```

--------------------------------

### Run Parallel Function Execution Example

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

This example demonstrates how to record and visualize parallel function execution using pmap. It's useful for debugging race conditions in multi-threaded applications.

```clojure
(defn run-parallel []
  (->> (range 4)
       (pmap (fn [i] (factorial i)))
       (reduce +)))
```

--------------------------------

### Start FlowStorm Debugger for React Native with Shadow-CLJS

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

This command starts the FlowStorm debugger and connects to a shadow-cljs nREPL server. Ensure `flow-storm-inst` is a dependency and the nREPL is running on port 9000. Replace `:your-app-build-id` and `YOUR_DEV_MACHINE_IP` with your specific values.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :your-app-build-id :debugger-host '"YOUR_DEV_MACHINE_IP"'
```

--------------------------------

### Plugin UI Styling Example

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Example of how to style a FlowStorm plugin's UI elements using CSS. It shows how to target elements within a specific plugin's pane.

```css
.my-plugin .table-view {
    -fx-font-family: 'monospaced';
}
```

--------------------------------

### Start Webworker Debugger Instance

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Run this command in a second terminal to start the webworker debugger instance. Note the different build ID and WebSocket port.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-web-worker :ws-port 7733
```

--------------------------------

### Install WebSocket Library for Node.js/React Native

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Ensure the 'websocket' library is installed for FlowStorm to function correctly in Node.js and React Native environments.

```bash
npm install websocket --save
```

--------------------------------

### Start FlowStorm Debugger with shadow-cljs (Linux/macOS)

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Launch the FlowStorm debugger, specifying the port, repl-type, and build-id for shadow-cljs integration on Linux and macOS.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-build-id
```

--------------------------------

### Global Leiningen Profile for FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure your global ~/.lein/profiles.clj to easily start FlowStorm with ClojureStorm. Use the +1.12-storm profile.

```clojure
{:1.12-storm
 {:dependencies [[com.github.flow-storm/clojure "1.12.5"]
                 [com.github.flow-storm/flow-storm-dbg "4.5.9"]]
  :exclusions [org.clojure/clojure]}

 ;; Optional plugins you find yourself using regularly
 :fs-web-plugin
 {:dependencies [[com.github.flow-storm/flow-storm-web-plugin "1.0.0-beta"]]
  :jvm-opts ["-Dclojure.storm.instrumentOnlyPrefixes.webPlugin=org.httpkit.server,ring.adapter.jetty,next.jdbc.result-set"
             "-Dflowstorm.plugins.namespaces.webPlugin=flow-storm.plugins.web.all"]
...}
```

--------------------------------

### Launch FlowStorm Debugger with shadow-cljs

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Run this command in your terminal to start the FlowStorm debugger UI. Ensure the port matches your `shadow-cljs.edn` configuration. Reload your application page to connect.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-app
```

--------------------------------

### Start FlowStorm Debugger UI

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Run this command in a separate terminal to launch the FlowStorm UI. Ensure the browser is refreshed after running this command to connect the browser app to the UI.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger
```

--------------------------------

### Start FlowStorm Debugger with shadow-cljs (Windows)

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Launch the FlowStorm debugger, specifying the port, repl-type, and build-id for shadow-cljs integration on Windows. Note the escaped quotes for the version.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version """4.5.9"""}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-build-id
```

--------------------------------

### Start FlowStorm Debugger with Custom Remote Configuration

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Start the FlowStorm debugger connecting to a remote process without an SSH tunnel. Configure nREPL port, runtime host, debugger host, and websocket port.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port NREPL-PORT :runtime-host '"YOUR-APP-BOX-IP-ADDRESS"' :debugger-host '"YOUR-BOX-IP-ADDRESS"' :ws-port WS-SERVER-PORT
```

--------------------------------

### Start FlowStorm Debugger with ClojureScript Support

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Launches the FlowStorm debugger UI, configured for ClojureScript development. It specifies the debugger version, port, REPL type, build ID, and pre-loads a custom visualizers namespace.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-app :pre-require visualizers
```

--------------------------------

### ClojureScript App Preload Configuration

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure your ClojureScript application's preload file to connect to the debugger. This example connects to WebSocket port 7722.

```clojure
(ns my-app.main-storm-preload
  (:require [cljs.storm.tracer]
            [flow-storm.tracer :as tracer]
            [flow-storm.runtime.debuggers-api :as dbg-api]))

(dbg-api/start-runtime)
(tracer/hook-clojurescript-storm)
(dbg-api/remote-connect {:debugger-host "localhost" :debugger-ws-port 7722})
```

--------------------------------

### Global deps.edn Alias for FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure your global ~/.clojure/deps.edn to easily start FlowStorm with ClojureStorm. Use the :1.12-storm alias.

```clojure
{...
 :aliases
 {:1.12-storm {:classpath-overrides {org.clojure/clojure nil}
               :extra-deps {com.github.flow-storm/clojure {:mvn/version "1.12.5"}
                            com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}

  ;; Optional plugins you find yourself using regularly
  :fs-web-plugin {:extra-deps {com.github.flow-storm/flow-storm-web-plugin {:mvn/version "1.0.0-beta"}}
                  :jvm-opts ["-Dclojure.storm.instrumentOnlyPrefixes.webPlugin=org.httpkit.server,ring.adapter.jetty,next.jdbc.result-set"
                             "-Dflowstorm.plugins.namespaces.webPlugin=flow-storm.plugins.web.all"]

  ...}}
```

--------------------------------

### ClojureScript Webworker Preload Configuration

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure your ClojureScript webworker's preload file to connect to the debugger. This example connects to WebSocket port 7733.

```clojure
(ns my-app.webworker-storm-preload
  (:require [cljs.storm.tracer]
            [flow-storm.tracer :as tracer]
            [flow-storm.runtime.debuggers-api :as dbg-api]))

(dbg-api/start-runtime)
(tracer/hook-clojurescript-storm)
(dbg-api/remote-connect {:debugger-host "localhost" :debugger-ws-port 7733})
```

--------------------------------

### Configure Out-of-Process Debugging Aliases

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Define Clojure CLI aliases for running the application process with FlowStorm instrumentation and for starting the FlowStorm UI process separately.

```clojure
{:aliases
 ;; for your system process
 {:runtime-storm {:classpath-overrides {org.clojure/clojure nil}
                  :extra-deps {com.github.flow-storm/clojure {:mvn/version "1.12.5"}
                               com.github.flow-storm/flow-storm-inst {:mvn/version "4.5.9"}}}
  ;; for the FlowStorm GUI process
  :ui-storm {:extra-deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}
             :exec-fn flow-storm.debugger.main/start-debugger
             :exec-args {:port 7888}}}} ;; set your nrepl port here!
```

--------------------------------

### Configure Emacs for Opening Files in JARs (Cross-OS)

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

This JVM option configures emacsclient for opening files within JARs, compatible with all operating systems starting from FlowStorm version 3.17.3. It uses a more complex elisp expression to locate the file within the JAR.

```jvmoptions
"-Dflowstorm.jarEditorCommand=emacsclient --eval '(let ((b (cider-find-file "jar:file:<<JAR>>!/<<FILE>>"))) (with-current-buffer b (switch-to-buffer b) (goto-char (point-min)) (forward-line (1- <<LINE>>))))'"
```

--------------------------------

### Start FlowStorm Debugger with SSH Tunnel

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Launch the FlowStorm debugger UI, connecting to a remote process via an established SSH tunnel. The debugger will listen on port 9000.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :port 9000
```

--------------------------------

### VSCode Alias Setup for FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

This `deps.edn` alias configures the classpath and JVM options for integrating FlowStorm with VSCode. It overrides the default Clojure version and adds FlowStorm dependencies.

```clojure
{:aliases {:flowstorm {:classpath-overrides {org.clojure/clojure nil}
                       :extra-deps {com.github.flow-storm/clojure {:mvn/version "1.12.5"}
                                    com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}
                       :jvm-opts ["-Dflowstorm.startRecording=true"
                                  "-Dclojure.storm.intrumentEnable=true"
                                  "-Dclojure.storm.intrumentAutoPrefixes=true"]}}}
```

--------------------------------

### FlowStorm Startup Instrumentation Configuration

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure startup instrumentation for ClojureStorm and ClojureScriptStorm using JVM properties. Specify namespaces to include, skip, or match with a regex.

```properties
-Dclojure.storm.instrumentOnlyPrefixes=my-app,my-lib
-Dclojure.storm.instrumentSkipPrefixes=my-app.too-heavy,my-lib.uninteresting
-Dclojure.storm.instrumentSkipRegex=.*test.*
```

```properties
-Dcljs.storm.instrumentOnlyPrefixes=my-app,my-lib
-Dcljs.storm.instrumentSkipPrefixes=my-app.too-heavy,my-lib.uninteresting
```

--------------------------------

### Configure shadow-cljs.edn for FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Add `flow-storm.storm-preload` to your `devtools.preloads`. Ensure it's the first preload if others exist. Configure the nrepl port and specify the deps.edn alias.

```clojure
 {:deps {:aliases [:1.12-cljs-storm]}
 :nrepl {:port 9000}
 ...
 :builds
 {:my-app {...
           :devtools {:preloads [flow-storm.storm-preload]
                      :http-port 8021}}}}
```

--------------------------------

### Configure JVM Options for File and Jar Editor Commands

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Specify the commands to open files or jar entries in an external editor. The `<<LINE>>`, `<<FILE>>`, and `<<JAR>>` placeholders will be replaced by FlowStorm with the appropriate values.

```bash
-Dflowstorm.fileEditorCommand=emacsclient -n +<<LINE>>:0 <<FILE>>
```

```bash
-Dflowstorm.jarEditorCommand=emacsclient -n +<<LINE>>:0 <<JAR>>/<<FILE>>
```

--------------------------------

### Configure Emacs for Opening Project Files

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use this JVM option to configure Emacs for opening project files. Ensure emacsclient is in your PATH.

```jvmoptions
"-Dflowstorm.fileEditorCommand=emacsclient -n +<<LINE>>:0 <<FILE>>"
```

--------------------------------

### Configure VSCode for Opening Files

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use this JVM option to configure VSCode for opening files. It utilizes the 'code --goto' command to navigate directly to the specified file and line.

```jvmoptions
"-Dflowstorm.fileEditorCommand=code --goto <<FILE>>:<<LINE>>"
```

--------------------------------

### Get Current Value in Data Window

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Retrieves the current value being displayed in a specified data window, useful for debugging custom visualizers.

```clojure
(viz/data-window-current-val :chess-board-dw)
```

--------------------------------

### Require and Connect to FlowStorm API

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

In your REPL, require the `flow-storm.api` namespace and then call `local-connect` to launch the debugger GUI and prepare for debugging.

```clojure
user> (require '[flow-storm.api :as fs-api]) ;; the only namespace you need to require
```

```clojure
user> (fs-api/local-connect) ;; will run the debugger GUI and get everything ready
```

--------------------------------

### Configure JVM Options for Clojure Instrumentation

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

These options control Clojure's Storm instrumentation. Enable instrumentation, specify prefixes to include or exclude, and use regex to skip specific namespaces or test-related code.

```bash
-Dclojure.storm.instrumentEnable=true
```

```bash
-Dclojure.storm.instrumentOnlyPrefixes[.*]=ns-prefix1,ns-prefix2
```

```bash
-Dclojure.storm.instrumentAutoPrefixes=false
```

```bash
-Dclojure.storm.instrumentSkipPrefixes[.*]=my-app.too-heavy,my-lib.uninteresting
```

```bash
-Dclojure.storm.instrumentSkipRegex=.*test.*
```

--------------------------------

### Get Thread Timeline

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Retrieve the timeline for a specific thread ID using `ia/get-timeline`. This timeline can then be explored using standard Clojure collection functions.

```clojure
(def timeline (ia/get-timeline 32))
```

--------------------------------

### Run and Instrument Form with #rtrace

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use the `#rtrace` macro to both instrument and immediately run a form at the REPL. This is useful for tracing the execution of simple expressions.

```clojure
#rtrace (-> (range) (filter odd?) (take 10) (reduce +))
```

--------------------------------

### Babashka Script Debugging - Conditional Execution

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Example of modifying a script to remove conditional execution logic that prevents it from running outside of Babashka, enabling debugging from Clojure.

```clojure
(when true #_(= *file* (System/getProperty "babashka.file"))
  ...)
```

--------------------------------

### Set Thread Trace Limit via JVM Option

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure a maximum number of traces per thread at startup using the `flowstorm.threadTraceLimit` JVM option. Setting this to 0 disables the limit. The `flowstorm.throwOnLimit` option can be used to control behavior when the limit is reached.

```jvm
-Dflowstorm.threadTraceLimit=1000
```

```jvm
-Dflowstorm.throwOnLimit=true
```

--------------------------------

### Configure Vim for Opening Files

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use this JVM option to configure Vim for opening files. It employs the 'vim +<<LINE>>' command to open the file at the specified line.

```jvmoptions
"-Dflowstorm.fileEditorCommand=vim +<<LINE>> <<FILE>>"
```

--------------------------------

### Configure JVM Options for UI Updates

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Control automatic UI updates and call tree updates. Setting `autoUpdateUI` or `callTreeUpdate` to `false` can improve performance in scenarios with frequent updates.

```bash
-Dflowstorm.autoUpdateUI=false
```

```bash
-Dflowstorm.callTreeUpdate=false
```

--------------------------------

### Configure JVM Options for Throw on Limit

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Enable or disable throwing an exception when a limit (e.g., thread trace limit) is reached. Setting this to `true` can help identify performance bottlenecks or infinite loops.

```bash
-Dflowstorm.throwOnLimit=true
```

--------------------------------

### Configure IntelliJ IDEA for Opening Files

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

This JVM option configures IntelliJ IDEA for opening files. It uses the 'idea --line' command to specify the line number and file path.

```jvmoptions
"-Dflowstorm.fileEditorCommand=idea --line <<LINE>> <<FILE>>"
```

--------------------------------

### Configure deps.edn for FlowStorm with shadow-cljs

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Set up a dev alias in `deps.edn` to override the ClojureScript compiler, add ClojureScriptStorm and FlowStorm dependencies, and configure automatic instrumentation prefixes.

```clojure
{... 
 :aliases
 ;; this alias can be defined globally in your ~/.clojure/deps.edn so you don't have to modify this file in your project
 {:1.12-cljs-storm
    {:classpath-overrides {org.clojure/clojurescript nil} ;; disable the official compiler
     :extra-deps {thheller/shadow-cljs {:mvn/version "3.3.4"
                                        :exclusions [org.clojure/clojojurescript]}
                  ;; bring ClojureScriptStorm
                  com.github.flow-storm/clojurescript {:mvn/version "1.12.134-3"}
                  ;; add FlowStorm runtime dep
                  com.github.flow-storm/flow-storm-inst {:mvn/version "4.5.9"}}}}}
```

--------------------------------

### Configure JVM Options for FlowStorm Recording and Plugins

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

These JVM options control FlowStorm's recording behavior and plugin namespaces. `startRecording` can be set to `false` to disable automatic recording. Plugin namespaces can be specified using regular expressions.

```bash
-Dflowstorm.startRecording=false
```

```bash
-Dflowstorm.plugins.namespaces[.+]=ns1,ns2
```

--------------------------------

### Require FlowStorm Indexes API

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Require the `flow-storm.runtime.indexes.api` namespace as `ia` to access and analyze recordings from the REPL.

```clojure
(require '[flow-storm.runtime.indexes.api :as ia])
```

--------------------------------

### Configure Emacs for Opening Files in JARs (Linux)

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

A simple JVM option for opening files within JARs using emacsclient on Linux. This method may not work on other operating systems.

```jvmoptions
"-Dflowstorm.jarEditorCommand=emacsclient -n +<<LINE>>:0 <<JAR>>/<<FILE>>"
```

--------------------------------

### Instrument and Run Code with #rtrace

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use the `#rtrace` reader macro to instrument and execute code. The expression will run normally, and the debugger UI will display the recording.

```clojure
user> #rtrace (reduce + (map inc (range 10))) ;; #rtrace will instrument and run some code
```

--------------------------------

### Configure JVM Options for ClojureScript Instrumentation

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Control ClojureScript instrumentation with options to enable, specify included/excluded prefixes, and skip specific namespaces or patterns. Note that `instrumentOnlyPrefixes` is listed twice in the source, with different values.

```bash
-Dcljs.storm.instrumentEnable=true
```

```bash
-Dcljs.storm.instrumentOnlyPrefixes=ns-prefix1,ns-prefix2
```

```bash
-Dcljs.storm.instrumentAutoPrefixes=false
```

```bash
-Dcljs.storm.instrumentOnlyPrefixes=my-app,my-lib
```

```bash
-Dcljs.storm.instrumentSkipPrefixes=my-app.too-heavy,my-lib.uninteresting
```

--------------------------------

### Instrument Form with #trace

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use the `#trace` macro to instrument any top-level form at the REPL. This is intended for forms that do not run immediately, such as function definitions.

```clojure
#trace
(defn sum [a b]
  (+ a b))
```

--------------------------------

### Enable EQL Query Pprint Extractor

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Call this function to enable the EQL query pprint visualizer, which is disabled by default.

```clojure
(flow-storm.runtime.values/register-eql-query-pprint-extractor)
```

--------------------------------

### Register Chess Board Visualizer with JavaFX

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Registers a visualizer for the :chess-board kind. It uses JavaFX to render the board, displaying pieces with appropriate colors and styles. Requires the :chess-board data extractor to have been applied.

```clojure
(import '[javafx.scene.layout GridPane])
(import '[javafx.scene.control Label])

(viz/register-visualizer
   {:id :chess-board
    ;; only be available if the chess-board data extractor run on this value
    :pred (fn [val] (contains? (::fs-values/kinds val) :chess-board))

    ;; use the chess/board info to render a board with java fx
    :on-create (fn [{:keys [chess/board]}] 
                 (let [kind->sprite {:king "♚" :queen "♛" :rook "♜" :bishop "♝" :knight "♞" :pawn "♟"}
                       pos->piece (->> board
                                       (mapv #(vector (:pos %) %))
                                       (into {}))]
                   {:fx/node (let [gp (GridPane.)] 
                               (doall 
                                (for [row (range 8) col (range 8)] 
                                  (let [cell-color (if (zero? (mod (+ col (mod row 2)) 2)) "#f0d9b5" "#b58863") 
                                        {:keys [kind player]} (pos->piece [row col]) 
                                        cell-str (kind->sprite kind "") 
                                        player-color (when player (name player))]
                                    (.add gp (doto (Label. cell-str)
                                               (.setStyle (format "-fx-background-color:%s; -fx-font-size:40; -fx-text-fill:%s; -fx-alignment: center;"
                                                                  cell-color player-color))
                                               (.setPrefWidth 50)) 
                                          (int col) 
                                          (int row)))))
                               gp)}))})
```

--------------------------------

### Instrument and Trace Code in REPL

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use the #rtrace macro in the REPL to instrument and run code, allowing FlowStorm to record its execution.

```clojure
cljs.user> #rtrace (reduce + (map inc (range 10))) ;; #rtrace will instrument and run some code
```

--------------------------------

### Configure JVM Options for UI Timeout

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Set the timeout in milliseconds for UI operations. This can be adjusted to prevent UI freezes or responsiveness issues in complex debugging sessions.

```bash
-Dflowstorm.uiTimeoutMillis=4000
```

--------------------------------

### Set Function Call Limits via JVM Prop

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure function call limits at application startup using the `flowstorm.threadFnCallLimits` JVM property. This limits the number of times a function and its call stack will be recorded per thread.

```jvm
-Dflowstorm.threadFnCallLimits=org.my-app/fn1:2,org.my-app/fn2:4
```

--------------------------------

### Instrument Namespaces with Prefixes

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Instrument entire namespaces based on provided prefixes using `instrument-namespaces-clj`. You can also specify namespaces to exclude or disable specific trace types.

```clojure
(instrument-namespaces-clj #{"org.my-app.core" "cljs."})
```

--------------------------------

### VSCode Custom Connect Sequence for FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

This JSON configuration for VSCode's `settings.json` defines a custom connect sequence for FlowStorm. It specifies the project type, how to handle ClojureScript, extra nREPL middleware, and the code to run after the REPL is jacked in.

```json
{
      "name": "flowstorm",
      "projectType": "deps.edn",
      "cljsType": "none",
      "extraNReplMiddleware": ["flow-storm.nrepl.middleware/wrap-flow-storm"],
      "afterCLJReplJackInCode": "((requiring-resolve 'flow-storm.storm-api/start-debugger))",
      "menuSelections": {
        "cljAliases": ["flowstorm"]
      }
}
```

--------------------------------

### Add Chess Board Visualizer as Default

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Sets the chess board visualizer as a default. This visualizer will be automatically applied to values that have the :chess-board kind, as determined by the provided predicate.

```clojure
(viz/add-default-visualizer (fn [val-data] (contains? (:flow-storm.runtime.values/kinds val-data) :chess-board)) :chess-board)
```

--------------------------------

### Access Timeline as Tree

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Access the timeline as a tree structure using `callstack-root-node`, `callstack-node-childs`, and `callstack-node-frame-data` for hierarchical exploration.

```clojure
* `callstack-root-node`
  * `callstack-node-childs`
  * `callstack-node-frame-data`
```

--------------------------------

### Establish SSH Tunnel for Remote Debugging

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Create an SSH tunnel to forward local ports to a remote debuggee. Assumes nREPL is on port 9000 and the debugger websocket on 7722.

```bash
ssh -L 9000:localhost:9000 -R 7722:localhost:7722 my-debuggee-box.com
```

--------------------------------

### Configure JVM Options for Thread Trace Limit

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Set a maximum limit for the number of trace entries per thread. This helps manage memory usage and performance by truncating excessively long traces.

```bash
-Dflowstorm.threadTraceLimit=1000
```

--------------------------------

### Configuring Instrumentation Prefixes in FlowStorm

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Set JVM properties to explicitly define which namespaces should be instrumented. Use instrumentOnlyPrefixes for inclusion and instrumentSkipPrefixes for exclusion.

```properties
-Dclojure.storm.instrumentOnlyPrefixes=my-project.,lib1.,lib2.core
```

--------------------------------

### Require FlowStorm API for Early Debugging

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

In cases where you need to debug app initialization before the debugger is connected, require the flow-storm.api namespace in your main code.

```clojure
require 'flow-storm.api
```

--------------------------------

### Push Value to Data Window

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use this function to push a value into a specified data window for real-time visualization. Provide the data window ID, the value, and an optional initial breadcrumb label.

```clojure
(flow-storm.api/data-window-push-val :changing-long-dw-id 0 "a-long")
```

--------------------------------

### Register Custom Visualizer

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Registers a custom visualizer with a unique ID, a predicate function to determine applicability, and an optional creation function for the UI node.

```clojure
(viz/register-visualizer
     {:id :my-viz
      :pred (fn [val] )
      :on-create (fn [val] {:fx/node :any-java-fx-node-that-renders-the-value
                            :more-ctx-data :anything})
      ;; OPTIONALLY
      :on-update (fn [val created-ctx-map {:keys [new-val]}] )
      :on-destroy (fn [created-ctx-map] )
      })
```

--------------------------------

### Set Heap Limit via JVM Option

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Automatically stop recording traces when a specified heap limit in megabytes is reached by setting the `flowstorm.heapLimit` JVM option. This prevents excessive memory consumption.

```jvm
-Dflowstorm.heapLimit=1000
```

--------------------------------

### Run Multiple FlowStorm Debugger Instances

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure and run multiple FlowStorm debugger instances by specifying a different WebSocket port for each instance using the :ws-port option.

```bash
clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}}' -X flow-storm.debugger.main/start-debugger :ws-port 7723
```

--------------------------------

### Configure FlowStorm UI via JVM Options

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

These JVM options can be used to configure FlowStorm's UI settings like title, theme, and styles when not using programmatic configuration.

```bash
-Dflowstorm.title=FlowStormMainDebugger
-Dflowstorm.theme=dark
-Dflowstorm.styles=~/.flow-storm/big-fonts.css
```

--------------------------------

### Babashka Debugger Configuration (deps.edn)

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Modify your deps.edn file to include the FlowStorm alias for debugging Babashka scripts. This sets up necessary dependencies and JVM options.

```clojure
{...
 :aliases {:dev {:classpath-overrides {org.clojure/clojure nil} ;; for disabling the official compiler
                 :extra-deps {com.github.flow-storm/clojure {:mvn/version "1.12.5"}
                              com.github.flow-storm/flow-storm-dbg {:mvn/version "4.5.9"}}
                 :jvm-opts ["-Dclojure.storm.instrumentOnlyPrefixes=user"]}}}
```

--------------------------------

### Configure FlowStorm UI Styles and Theme

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Use these options to customize the FlowStorm debugger's appearance. The `:styles` keyword accepts a path to a CSS file for overwriting default styles. `:theme` can be set to `:auto`, `:light`, or `:dark`. `:title` allows distinguishing multiple debugger instances.

```clojure
user> (local-connect {:styles "~/.flow-storm/big-fonts.css", :theme :dark, :title "FlowStormMainDebugger"})
```

--------------------------------

### Set Before and After Reload Callbacks

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure functions to be executed before and after FlowStorm reloads namespaces. This is useful for managing system state during reloads.

```clojure
(flow-storm.api/set-before-reload-callback! (fn [] (println "Before reloading")))
```

```clojure
(flow-storm.api/set-after-reload-callback!  (fn [] (println "After reloading")))
```

--------------------------------

### Explore Thread Timeline

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Explore a thread timeline by taking elements, mapping them to immutable data structures, or accessing specific entries by index.

```clojure
user> (count timeline)
798
```

```clojure
user> (take 3 timeline)
; (#flow-storm/fn-call-trace [Idx: 0 org.my-app/run-server]
;  #flow-storm/fn-call-trace [Idx: 1 org.my-app/read-config]
;  #flow-storm/fn-call-trace [Idx: 2 org.my-app/check-config])
```

```clojure
user> (get timeline 0)
; #flow-storm/fn-call-trace [Idx: 0 org.my-app/run-server]
```

```clojure
(->> timeline
     (take 3)
     (map ia/as-immutable))

; ({:type :fn-call,
;   :fn-ns "org.my-app",
;   :fn-name "run-server",
;   :ret-idx 797,
;   :fn-call-idx 0,
;   :parent-idx nil,
;   :fn-args [],
;   :form-id -798068730,
;   :idx 0}
;  ...
;  ...)
```

--------------------------------

### UI Plugin Template

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Template for a FlowStorm plugin's UI component. It demonstrates how to register a plugin, define its appearance, and handle lifecycle events like focus and flow clearing.

```clojure
(ns flow-storm.plugins.my-plugin.ui
  (:require [flow-storm.debugger.ui.plugins :as fs-plugins]
            [flow-storm.debugger.runtime-api :as runtime-api :refer [rt-api]])
  (:import [javafx.scene.control Label]))

(fs-plugins/register-plugin
 :my-plugin
 {:label "My plugin"
  :css-resource  "flow-storm-my-plugin/dark.css"
  :dark-css-resource  "flow-storm-my-plugin/dark.css"
  :light-css-resource "flow-storm-my-plugin/light.css"
  :on-focus (fn [{:keys [some-other-data]}] 
              ;; This gets called everytime the plugin tab gets focused
              )
  :on-create (fn [_]
               {:fx/node (Label. 
                          ;; You can call your runtime registered function
                          (str (runtime-api/call-by-fn-key rt-api :plugins.my-plugin/extract-data [0 10])))
                :some-other-data 42})
  :on-flow-clear (fn [flow-id {:keys [some-other-data]}] 
                     ;; this gets called everytime a flow is discarded so you can update your plugin UI accordignly
                   )
  })
```

--------------------------------

### Leiningen Profile for FlowStorm Debugger

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Configure this profile in your `project.clj` to add FlowStorm dependencies. Ensure to exclude the official Clojure dependency if using older Leiningen versions.

```clojure
(defproject my.project "1.0.0" :profiles {:1.12-storm {:dependencies [[com.github.flow-storm/clojure "1.12.5"] [com.github.flow-storm/flow-storm-dbg "4.5.9"]] :exclusions [org.clojure/clojure]}} ...)
```

--------------------------------

### Configure Debugger Host for React Native on Mobile

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

When running a React Native app on a mobile device, specify your machine's IP address as the debugger host if not using adb reverse.

```clojure
:debugger-host <your-box-ip-address>
```

--------------------------------

### Add FlowStorm Dependency to shadow-cljs

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Include the FlowStorm dependency in your shadow-cljs.edn file to enable debugging capabilities.

```clojure
{
... 
 :dependencies [... [com.github.flow-storm/flow-storm-inst "4.5.9"]]

 ;; the next two lines aren't needed but pretty convenient
 :nrepl {:port 9000}
 :my-build-id {:devtools {:preloads [flow-storm.preload]}}
 ...
}
```

--------------------------------

### Configure ADB Reverse for React Native Debugging

Source: https://flow-storm.github.io/flow-storm-debugger/user_guide.html

Set up adb reverse for the debugger websocket port (7722) when debugging React Native apps on a mobile device.

```bash
adb reverse tcp:7722 tcp:7722
```
Tokens:
Raw