re-frame-trace

re-frame-trace is a programmer's dashboard. It allows you to see inside a running re-frame application, helping you to understand it and debug it.

Status: Alpha.

Note the latest version 0.1.14 ALSO requires the latest version of re-frame itself - v0.10.3-alpha2.

How It Might Help You

What it can do for you:

• Help you to learn re-frame. If you are new to re-frame, it will assist you to understand the data flows involved (the dominoes).
• Help you to explore and learn an unfamiliar re-frame codebase. When I click on this "X" button, it shows me what event is dispatch-ed and in what namespace the associated event handler is registered. And, "oh look, that's interesting - four subscriptions recalculated". Etc.
• Help you with debugging. In particular, it will assist you to write and debug event handlers, which is useful because they hold most of the logic in your re-frame apps.
• Help you to find performance problems and/or detect where there is unnecessary computation occurring.

(Okay, so this list is slightly aspirational. re-frame-trace is absolutely useful, and you should use it, but delivery against the ideal above is uneven)

Epoch Oriented

re-frame applications are computationally regular. First an event happens, and then boom, boom, boom go a series of known computational steps (dominoes), in a known order. At the end of it, a re-frame app lapses into a quiescent state waiting for another event to kick off the next iteration of the same cycle.

Each re-frame event and its consequent computation forms a discrete "epoch" which can be inspected, analysed and understood independently of other epochs. This tool is epoch-oriented.

And, yes, there's the ability to do time travel debugging - you can go backwards and forwards through epochs - but that's really not the most interesting aspect of what you get.

It is about Data

As it runs, re-frame generates detailed "trace" which is captured as data (not strings). This trace is like an x-ray of the app's functioning.

In addition, re-frame is as much "data oriented" as it is functional in design. It "flows" data, in a loop, through the functions you provide.

So, data is at the center of re-frame-trace.

Data Dashboard

There's often too much data - too much detail.

So, re-frame-trace tries to be something of a "dashboard" in the sense that it tries to turn "raw data" into "information" through curated analysis, and "roll ups" which deliver insight "at a glance". Then allowing you to "drill into the detail".

Right. So, this tool an epoch-oriented, interactive data dashboard for gaining insights and assisting debugging. It is also a work in progress, so this grand description runs well ahead of what is delivered right now. But we're getting there.

A Visual Sampler

Installation

If you are using leiningen, modify project.clj in the following ways. When puzzling over the various possible leiningen configurations, it's often helpful to look at a sample project.clj.

• Add re-frame-trace as a dev dependency by placing [day8.re-frame/trace "VERSION"] within :profiles :dev :dependencies. For example:

  :profiles
     {:dev
        {:dependencies [[some-other-package  "0.0.0"]
                        [day8.re-frame/trace "0.0.0 (see version above)"]] }}
  

• Locate the :compiler map under :dev and add:

  • :closure-defines {"re_frame.trace.trace_enabled_QMARK_" true}
  • :preloads [day8.re-frame.trace.preload]

  For example:

  {:builds
     [{:id           "dev"
       :source-paths ["src" "dev"]
       :compiler     {...
                      :closure-defines      {"re_frame.trace.trace_enabled_QMARK_" true}
                      :preloads             [day8.re-frame.trace.preload]}}]}
  

cljs-devtools is not required to use re-frame-trace, but it is highly recommended.

Usage

• Make sure you have followed all of the installation instructions above.

• Start up your application.

• Once it is loaded, focus the document window and press ctrl-h to slide open the trace panel and enable tracing.

• When the panel is closed, tracing is disabled.

Troubleshooting

• Try a lein clean
• Make sure you have followed all the installation steps.

How does it work?

re-frame is instrumented - all important activity generates trace data. re-frame-trace consumes this trace data and renders useful visualisations of the re-frame process. Currently, re-frame's tracing capabilities are in alpha and are subject to change at any time. We're testing the utility of the the trace by building an app on top.

By default, re-frame tracing is "compiled out", so it won't impose a performance cost in production. The trade-off here is that you need to explicitly enable it in development.

The preloads option (:preloads [day8.re-frame.trace.preload]) has to be set in order to automatically monkeypatch Reagent to add appropriate lifecycle hooks. Yes this is gross, and yes we will try and make a PR to reagent to add proper hooks, once we know exactly what we need. The preload namespace also injects a div containing the devtools panel into the DOM.

Developing/Contributing

If you want to work on re-frame-trace, see DEVELOPERS.md.

Citations

• open by Bluetip Design from the Noun Project
• reload by Adnen Kadri from the Noun Project
• Camera by Christian Shannon from the Noun Project
• Delete by logan from the Noun Project
• Settings by arjuazka from the Noun Project