Add FlowStorm, a tracing debugger for Clojure(Script)

[ilmotta]

Summary

This PR adds FlowStorm v3.7.5, a well known (tracing) debugger for Clojure(Script). The kinds of things you can do with it are beyond my ability and time to explain in this humble PR description. See Demo section for a real example in our codebase, but we are all encouraged to check out many other features (see Resources section below).

Demo

I recorded a simple example (please, watch in fullscreen) showing you how I can debug the event handler to login. After that, you see me stepping back and forth in all available expressions. The output of each expression or symbol is displayed on the right panel. At the end, you also see me defining a var from within the debugger, which is then available in my user namespace and which can be manipulated and inspected as if it was defined right from within my text editor (REPL is connected of course). This is very useful when analyzing larger/more data structures, since you are no longer dealing with raw print statements.

demo-flow-storm.webm

To summarize, with this tool, you can debug almost any cljs function in status-mobile. FlowStorm in CLJS is not as capable as on the JVM, but its main features work well enough.

How do I use it?

Please, check the markdown diff in this PR: doc/debugging.md.

When would you use FlowStorm in status-mobile?

You can use it all the time if you want, but FlowStorm can be a powerful tool to understand complex pieces of code. Consider those large subscriptions or event handlers. Or also all those components full of calculations. Understanding some of these things is no easy task, even with a REPL. It is not a replacement for re-frisk, those are very different tools and each have their place.

Resources

• Repository: https://github.com/flow-storm/flow-storm-debugger
• Documentation: https://flow-storm.github.io/flow-storm-debugger
• Features: https://github.com/flow-storm/flow-storm-debugger#features
• YouTube demos: https://github.com/flow-storm/flow-storm-debugger#some-demo-videos-newers-at-the-top

Platforms

• Android
• iOS

Areas that may be impacted

None.

Steps to test

The tool should work on iOS, but I kindly ask a developer with iOS to double-check. The e2e test suite is more than enough to guarantee this PR won't cause regressions.

status: ready

[ilmotta]

FYI: websocket is a must. Without it, FlowStorm can't run.

[status-im-auto]

Jenkins Builds

❔	Commit	#️⃣	Finished (UTC)	Duration	Platform	Result
✔️	bc0f58f	#2	2024-05-15 21:59:53	~4 min	tests	📄log
✔️	bc0f58f	#2	2024-05-15 22:02:43	~7 min	android-e2e	🤖apk 📲
✔️	bc0f58f	#2	2024-05-15 22:02:45	~7 min	android	🤖apk 📲
✔️	bc0f58f	#2	2024-05-15 22:05:45	~10 min	ios	📱ipa 📲

[jakubgs]

Appreciate the expansion of debugging docs.

[briansztamfater]

This looks promising, I will try to test it during this week. Code-wise I have no objections, I will approve it as soon as I have some time to checkout the branch and test it locally 🚀

[ilmotta]

This looks promising, I will try to test it during this week. Code-wise I have no objections, I will approve it as soon as I have some time to checkout the branch and test it locally 🚀

Much appreciated @briansztamfater 💯

[clauxx]

Yesss, thank you!!! Looks great, can't wait to try it out while developing

[yqrashawn]

Got class not found hansel/instrument/utils__init.class, rebase to dev solved the issue

[ulisesmac]

Hey @ilmotta

I checked it and It seems very powerful, I inspected some variables while sending a transaction since it's a complex part of our code and it looks interesting!

It reminds me to the debugger that IntelliJ has for JVM Clojure, you are able to add breakpoints and inspect the memory at any point.

One problem with my editor is when I add the #trace line, IntelliJ thinks it's an error so it starts to indent the code weird and mistakenly highlights some vars as errors 😢

Another downside is the UI, It's not clear enough for me but probably it's a matter of getting used to it.

Right now, I'd say I'd prefer the REPL most of the time, but I there are some flows where I need to check what values were passed to a function compared to the current ones, so this debugger will help A LOT! 🎉 .

I'll check what other features it has Later.

It's a good addition, thanks for the PR!

[ilmotta]

Hey @ilmotta

I checked it and It seems very powerful, I inspected some variables while sending a transaction since it's a complex part of our code and it looks interesting!

It reminds me to the debugger that IntelliJ has for JVM Clojure, you are able to add breakpoints and inspect the memory at any point.

One problem with my editor is when I add the #trace line, IntelliJ thinks it's an error so it starts to indent the code weird and mistakenly highlights some vars as errors 😢

Another downside is the UI, It's not clear enough for me but probably it's a matter of getting used to it.

Right now, I'd say I'd prefer the REPL most of the time, but I there are some flows where I need to check what values were passed to a function compared to the current ones, so this debugger will help A LOT! 🎉 .

I'll check what other features it has Later.

It's a good addition, thanks for the PR!

You described exactly how I perceive FlowStorm. As a tool, I missed many times, especially because I used in Clojure JVM more. The more I use it, the more I see its utility.

One problem with my editor is when I add the #trace line, IntelliJ thinks it's an error so it starts to indent the code weird and mistakenly highlights some vars as errors

There's probably a way to make IntelliJ understand #trace, but I'm clueless.

zprint also tries to format whatever comes after #trace. Not a big deal for most, but for someone like me who auto-format according to zprint rules on every save, it's a bit annoying. But can be improved in a separate PR, especially because code should never be merged with #trace this shouldn't be a problem.

Many thanks for testing the PR!