Release 0.1.22
-----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQEcBAABCAAGBQJai3knAAoJEKbk3FKDtdzsIlUH/31306DmBEkP+50o2iJSCTBT GKBQv/0zCcJqJLApWLQRdAS/foCfavwhmtQqXrz1p1pNVdg2UPW0QkAvqufWROa9 1DGUyar8qEPOVIeHsolh8Q5qSubUBFqkjbM/a2s/69UXNM6Jt93fJGeP/ua2nSTx 6xVmDVWUZ2uCO3lMcAKTmx/54Z/9fHJaEVlSJ3kL3tWwxtzmoV/lHMhHPIIrTmYF 6JrjfH/yfXeffDQ4SzUZAe0ssUKAEBgTWU9cvA1Y1PO0rryGhx6MYU2sramRfTGW MQTQA2/fjFPT8xzwqe8yP8NVG2IljdlISx838oyYGTTIvesbescAyvG0Q016L2Y= =slHV -----END PGP SIGNATURE----- Merge tag '0.1.22' into react-16 Release 0.1.22
This commit is contained in:
Daniel Compton
commit
79dea9e7ce
12
README.md
12
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# re-frame-trace
|
||||
|
||||
`re-frame-trace` let's you inspect the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination. A 10x programmer is the one with 10x more knowledge and insight.
|
||||
`re-frame-trace` let's you instrument, and then inspect, the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination.
|
||||
|
||||
### It Is Epoch Oriented
|
||||
|
||||
|
|
@ -99,13 +99,15 @@ features, and build a cognative map of how the code is structured.
|
|||
|
||||
> Some of the claims above are aspirational. `re-frame-trace` [remains a WIP](https://github.com/Day8/re-frame-trace/issues/118).
|
||||
|
||||
## Sausage
|
||||
## Of Sausage And Sizzle
|
||||
|
||||
We debated internally about the name `re-frame-trace`. While `-trace` is accurate, it is 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. Anyway, `-insight` and `-illumination` are the benefits, but they made the name waaaay too long. Naming things - it's just a nightmare! As is inertia. So, `-trace` it remains.
|
||||
Internal discussion about a name meandered for a while. Initially, it was `re-frame-trace`, which is accurate, sure, but it is also 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). Side stepping the issue, I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines.
|
||||
|
||||
**Update:** a name change to `re-frame-10x` is on the cards. Disapointingly, my latest suggestion, `TenMinutesByTractor`, was also rejected. I shake my head. Why can noone see that we're all "code farmers" by profession?
|
||||
Now, the tool's benifits are `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it really is a nightmare!
|
||||
|
||||
## A Visual Sampler
|
||||
Finally, `-10x` cheekily materialised, delivering 100 decibels of audacious sizzle, and consequently a challenge for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so go make that tool, smarty pants.
|
||||
|
||||
## A 1000 words
|
||||
|
||||
Slightly out of date, but indicative ...
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1 @@
|
|||
This directory holds help documents accessed directly from the UI.
|
||||
|
||||
The `re-frame-trace` UI contains
|
||||
various (helpful) hyperlinks which point to documents kept within this directory.
|
||||
The `re-frame-trace` UI contains hyperlinks to the various documents in this directory. Within the UI, these hyperlinks have text like "guide me to greatness" and "why?", which indicates the purpose of the docs herein.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,49 @@
|
|||
This document explains the operation of the "Replay" button, and how to use **The HotPlay Workflow**.
|
||||
|
||||
### Epoch Navigation
|
||||
|
||||
By using the backwards and forwards arrows, `re-frame-trace` allows you to navigate through Epochs.
|
||||
At any one moment, you are inspecting a single Epoch, for which we'll use the term "The Observed Epoch".
|
||||
|
||||
### On Click
|
||||
|
||||
When you click the "Replay" button, you are asking `re-frame-trace` to perform
|
||||
an "Action Replay" of "The Observed Epoch", and this happens in two Steps:
|
||||
- **Step 1** - the value in `app-db` is reset to the value it contained immediately prior to "The Observed Epoch"
|
||||
- **Step 2** - the event which caused "The Observed Epoch" is re-dispatched
|
||||
|
||||
So, Step 1 is "reestablish initial conditions" and Step 2 is "do it all again".
|
||||
|
||||
#### Further Notes:
|
||||
- In Step 1, the reset of `app-db` will trigger computation and trace.
|
||||
Subscriptions and views are run as the application returns to the "prior state",
|
||||
but none of the associated trace is captured. It is all ignored.
|
||||
- Trace arising from Step 2 forms a normal, new Epoch. The Observed Epoch (which we are replaying)
|
||||
is still there, untouched.
|
||||
- New Epochs (Step 2) are always added to the end of the Epoch list (never inserted amongst old Epochs).
|
||||
- The user's experience is that they click the "Replay" button
|
||||
and immediately view the result. So, after Step 2, the user is auto-navigated to this new epoch.
|
||||
|
||||
### Useful?
|
||||
|
||||
It facilitates "The HotPlay Workflow":
|
||||
- A. You `Observe` an Epoch (in `re-frame-trace`) to see if an event was correctly processed
|
||||
- B. You notice a problem, and you `Edit` (fix) the event handler (or subs handler, view, etc) via Cursive, Emacs, etc.
|
||||
- C. Figwheel will re-compile and `Hotload` your correction
|
||||
- D: You click the `Replay` button
|
||||
- E: Back to A
|
||||
|
||||
Because of `Replay's` "Step 1", you get identical "initial conditions" for
|
||||
each iteration of the workflow, and this is true blessing. It removes the nagging
|
||||
cognative load of "allowing for" slightly shifting state and its consequences, or
|
||||
the effort of manually reestablishing identical application state before each iteration.
|
||||
|
||||
WARNING: obviously this only works when the state is contained within your SPA. When
|
||||
there's authorative remote state (a remote database?) there'll be more involved in
|
||||
returning to initial conditions each iteration.
|
||||
|
||||
### The Workflow Name
|
||||
|
||||
The initials of this Observe/Edit/Hotload/Replay process are OEHR, which, well, doesn't exactly roll off the tounge like REPL.
|
||||
So we call it "HotPlay" because "Hotload" and "Replay" are the two central pieces of tech. We love you Figwheel.
|
||||
|
||||
|
|
@ -1,22 +1,24 @@
|
|||
This document briefly explains why `re-frame-trace` gives you an option to
|
||||
ignore unchanged layer 2 subscriptions.
|
||||
In the "subs" tab, you have the option to
|
||||
ignore unchanged layer 2 subscriptions. This document explains why.
|
||||
|
||||
### Background
|
||||
|
||||
The `re-frame` docs
|
||||
[make a distinction](https://github.com/Day8/re-frame/blob/master/docs/SubscriptionInfographic.md)
|
||||
`re-frame`
|
||||
[makes a distinction](https://github.com/Day8/re-frame/blob/master/docs/SubscriptionInfographic.md)
|
||||
between `layer 2` and `layer 3` subscriptions:
|
||||
- `layer 2` subscriptions extract data directly from `app-db` and should be
|
||||
trivial in nature. There should be no computation in them beyond
|
||||
- **`layer 2` subscriptions extract data directly from `app-db`**. They should be
|
||||
trivial in nature, which is to say there should be no computation in them beyond
|
||||
what is necessary to extract a value from `app-db`
|
||||
- `layer 3` subscriptions take values from `layer 2` nodes as inputs, and
|
||||
compute a materialised view of those values. Just to repeat: they never directly
|
||||
extract values from `app-db`. They create new values where necessary, and because of it
|
||||
they to do more serious CPU work. So we never want to run a
|
||||
`layer 3` subscriptions unless it is necessary.
|
||||
- **`layer 3` subscriptions never take values from `app-db`**. Instead, they have
|
||||
`layer 2` nodes as inputs (or other `layer 3`), and they do the more serious CPU work of computing
|
||||
a materialised view of those values.
|
||||
|
||||
|
||||
We never want to run a `layer 3` subscriptions unless it is necessary, whereas `layer 2`
|
||||
subscriptions are so trivial that we don't mind running them unnecessarily.
|
||||
|
||||
This structure delivers efficiency. You see, **all** (currently instantiated) `layer 2` subscriptions
|
||||
will run **every** time `app-db` changes in any way. All of them. Every time.
|
||||
**will run every time `app-db` changes in any way**. All of them. Every time.
|
||||
And `app-db` changes on almost every event, so we want them to be computationally
|
||||
trivial.
|
||||
|
||||
|
|
@ -25,7 +27,7 @@ propagation of values through the signal graph will be pruned.
|
|||
The more computationally intensive `layer 3` subscriptions, and ultimately
|
||||
the views, will only recompute if and when there has been a change in their data inputs.
|
||||
|
||||
We don't want your app recomputing views only to find that nothing has changed. Inefficient.
|
||||
We don't want your app recomputing views only to find that nothing has changed. That would be inefficient.
|
||||
|
||||
### Back To Tracing
|
||||
|
||||
|
|
|
|||
|
|
@ -1,54 +1,50 @@
|
|||
This document highlights important aspects of the "Timing" tab.
|
||||
Some notes on the "Timing" tab in `re-frame-trace`.
|
||||
|
||||
## Be Cautious And Sceptical
|
||||
## Be Sceptical Of The Numbers
|
||||
|
||||
There are two issues with the displayed numbers:
|
||||
Two reasons:
|
||||
|
||||
1. Accurately timing something in the browser is almost
|
||||
1. Accurately timing something in the browser is
|
||||
a fool's errand. One moment it takes 1ms and the next it
|
||||
takes 10ms, and you’ll never know why. Noisy.
|
||||
|
||||
So, don't ever base your decisions on one set of timings. Run
|
||||
the same event at least a few of times.
|
||||
So, don't ever draw conclusions from one set of timings.
|
||||
Click the "replay" button ([#115](https://github.com/Day8/re-frame-trace/issues/155))
|
||||
a few times to ensure the numbers are stable.
|
||||
|
||||
In the future, we'd like to add a 'Run It Again' button, which
|
||||
you can click a few times to see if you get stable numbers.
|
||||
Perhaps you'll beat us to it, and create a PR for this
|
||||
feature?
|
||||
|
||||
2. Don't freak out about any apparent slowness, yet.
|
||||
2. Don't freak out about any apparent slowness. Not initially, anyway.
|
||||
|
||||
After all, you're running a dev build, right, not the
|
||||
production build? And I'm guessing you're also
|
||||
running a dev build of React?
|
||||
|
||||
And using `re-frame-trace` will slow things
|
||||
down too, what with all that creating and analysing of trace.
|
||||
running a dev build of React? And `re-frame-trace` will itself also add
|
||||
drag, what with all that creating and analysing of trace.
|
||||
|
||||
So, run the production version of your app first, before
|
||||
deciding you have a performance problem. Something what
|
||||
takes 100ms in dev might take 20ms in prod.
|
||||
takes 100ms in dev might take 10ms in prod.
|
||||
|
||||
The Timing Tab is not really about absolute numbers so
|
||||
much as the relative time taken to do the different
|
||||
"parts" of an Epoch. Is one View very slow for some
|
||||
reason, compared to others?
|
||||
And, even then, remember point 1 (above).
|
||||
"parts" of an Epoch. Is most the time going in views, or
|
||||
maybe one view in particular? Or in
|
||||
one subscription, compared to the others?
|
||||
And, even then, keep in mind point 1 (above).
|
||||
|
||||
## Know Your Epoch Timeline
|
||||
|
||||
The Timing Tab is easier to understand once you have internalised the
|
||||
following graphic which shows how, operationally, the six dominoes play out,
|
||||
over time, within the browser.
|
||||
over time, within the browser.
|
||||
|
||||
<img src="https://raw.githubusercontent.com/Day8/re-frame/master/images/epoch.png">
|
||||
|
||||
## Other Tips
|
||||
|
||||
You should probably have [React DevTools](https://github.com/facebook/react-devtools)
|
||||
installed because it is useful. But, it can also add drag and noise to timing results,
|
||||
so disable it when trying to get more accurate timing figures.
|
||||
It might be useful to have [React DevTools](https://github.com/facebook/react-devtools)
|
||||
installed because it can show you visually, what is rerednering. Neat idea. But, realise it
|
||||
can also add drag and noise to timing results, so disable it when trying to get more
|
||||
accurate timing figures.
|
||||
|
||||
Here is (React 16) advice on [debugging React performance with Chrome Devtools](https://building.calibreapp.com/debugging-react-performance-with-react-16-and-chrome-devtools-c90698a522ad)
|
||||
|
||||
The [re-frame.core/debug](https://github.com/Day8/re-frame/blob/master/src/re_frame/std_interceptors.cljc) middleware is relatively slow, and runs interleaved with your application's events being processed. re-frame-trace gives you the same information in the app-db panel, but saves the calculations until after your application has finished running, so you don't get the performance cost included in your timing.
|
||||
The [re-frame.core/debug](https://github.com/Day8/re-frame/blob/master/src/re_frame/std_interceptors.cljc) interceptor is relatively slow, and runs interleaved with your application's events being processed. re-frame-trace gives you the same information in the app-db panel, but saves the calculations until after your application has finished running, so you don't get the performance cost included in your timing.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
(defproject day8.re-frame/trace "0.1.21-react16"
|
||||
(defproject day8.re-frame/trace "0.1.22-react16"
|
||||
:description "Tracing and developer tools for re-frame apps"
|
||||
:url "https://github.com/Day8/re-frame-trace"
|
||||
:license {:name "MIT"}
|
||||
|
|
|
|||
|
|
@ -5,6 +5,7 @@
|
|||
|
||||
;; Use this namespace with the :preloads compiler option to perform the necessary setup for enabling tracing:
|
||||
;; {:compiler {:preloads [day8.re-frame.trace.preload] ...}}
|
||||
(js/console.warn "re-frame-trace has been renamed to re-frame-10x: (https://clojars.org/day8.re-frame/re-frame-10x). Update to newer versions of this library by using the `day8.re-frame/re-frame-10x` artifact ID. Thanks!")
|
||||
(rf/clear-subscription-cache!)
|
||||
(trace/init-db!)
|
||||
(defonce _ (trace/init-tracing!))
|
||||
|
|
|
|||
Loading…
Reference in New Issue