Skip to content

Commit 8745914

Browse files
committed
Improve readme
1 parent 7b7b41a commit 8745914

File tree

1 file changed

+41
-7
lines changed

1 file changed

+41
-7
lines changed

workflow-trace-viewer/README.md

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Workflow Trace Viewer
22

3-
A Compose for Desktop app that can be used to view Workflow traces.
3+
A Compose for Desktop application that visualizes and debugs Workflow execution traces. This tool helps developers understand the hierarchical structure and execution flow of their Workflow applications by providing both file-based and live streaming trace visualization.
44

55
## Running
66

@@ -10,20 +10,54 @@ It can be run via Gradle using:
1010
./gradlew :workflow-trace-viewer:run
1111
```
1212

13-
By Default, the app will be in file parsing mode, where you are able to select a previously recorded workflow trace file for it to visualize the data.
1413

15-
By hitting the bottom switch, you are able to toggle to live stream mode, where data is directly pulled from the emulator into the visualizer. A connection can only happen once. If there needs to be rerecording of the trace, the emulator must first be restarted, and then the app must be restarted as well. This is due to the fact that any open socket will consume all render pass data, meaning there is nothing to read from the emulator.
14+
## Usage Guide
1615

17-
It is ***important*** to run the emulator first before toggling to live mode.
16+
By default, the app will be in file parsing mode, where you are able to select a previously recorded workflow trace file for it to visualize the data. Once the workflow tree is rendered in [File](#file-mode) or [Live](#live-mode) mode, you can switch frames (see [Terminology](#Terminology)) to see different events that fired. All nodes are color coded based on what had happened during this frame, and a text diff will show the specific changes. You can open the right node panel and left click a box get a more detailed view of the specific node, or right click to expand/collapse a specific node's children.
17+
18+
<img src="https://github.com/square/workflow-kotlin/raw/wenli/improve-visualizer/workflow-trace-viewer/docs/demo.gif" width="320" alt="Demo" />
19+
20+
21+
#### File Mode
22+
23+
Once a file of the live data is saved, it can easily be uploaded to retrace the steps taken during the live session. Currently, text/json files that are saved from recordings only contain raw data, meaning it is simply a list of lists of node renderings.
24+
25+
<img src="https://github.com/square/workflow-kotlin/raw/wenli/improve-visualizer/workflow-trace-viewer/docs/file_mode.gif" width="320" alt="File Mode" />
26+
27+
#### Live Mode
28+
29+
By hitting the bottom switch, you are able to toggle to live stream mode, where data is directly pulled from the emulator into the visualizer. To do so:
30+
1. Start the app (on any device)
31+
2. Start the app, and toggle the switch to enter Live mode
32+
3. Select the desired device
33+
34+
Once in Live mode, frames will appear as you interact with the app. You may also save the current data into a file saved in `~/Downloads` to be used later (this action will take some time, so it may not appear immediately)
35+
36+
Render pass data is passively stored in a buffer before being sent to the visualizer, so you do not need to immediately open/run the app to "catch" everything. However, since the the buffer has limited size, it's strongly recommended to avoid interacting with the app — beyond starting it — before Live mode has been triggered; this helps to avoid losing data.
37+
38+
<img src="https://github.com/square/workflow-kotlin/raw/wenli/improve-visualizer/workflow-trace-viewer/docs/live_mode.gif" width="320" alt="Live Mode" />
39+
40+
### Note
41+
42+
A connection can only happen once. There is currently no support for a recording of the trace data due to the fact that an open socket will consume all render pass data when a connection begins. To restart the recording:
43+
44+
1. (optional) Save the current trace
45+
2. Switch out of Live mode
46+
3. Restart the app
47+
4. Switch back to Live mode, and the
1848

1949
### Terminology
2050

21-
**Trace**: A trace is a file — made up of frames — that contains the execution history of a Workflow. It includes information about render passes, how states have changed within workflows, and the specific props being passed through. The data collected to generate these should be in chronological order, and allows developers to step through the process easily.
51+
`Trace`: A trace is a file — made up of frames — that contains the execution history of a Workflow. It includes information about render passes, how states have changed within workflows, and the specific props being passed through.
2252

23-
**Frame**: Essentially a "snapshot" of the current "state" of the whole Workflow tree. It contains relevant information about the changes in workflow states and how props are passed throughout.
53+
`Frame`: Essentially a "snapshot" of the current "state" of the whole Workflow tree. It contains relevant information about the changes in workflow states and how props are passed throughout.
2454

2555
- Note that "snapshot" and "state" are different from `snapshotState` and `State`, which are idiomatic to the Workflow library.
2656

2757
### External Libraries
2858

29-
[FileKit](https://github.com/vinceglb/FileKit) is an external library made to apply file operations on Kotlin and KMP projects. It's purpose in this app is to allow developers to upload their own json trace files. The motivation for its use is to quickly implement a file picker.
59+
[FileKit](https://github.com/vinceglb/FileKit) is an external library made to apply file operations on Kotlin and KMP projects. This simplified the development process of allowing file selection
60+
61+
## Future
62+
63+
This app can be integrated into the process of anyone working with Workflow, so it's highly encouraged for anyone to make improvements that makes their life a little easier using this app.

0 commit comments

Comments
 (0)