Tracing Visualization

[Abby010]

Description

This program visualizes real-time execution flow of distributed spans in a terminal-based UI (TUI) using React Ink. It allows users to toggle between time-based (--sample 1s) and logical event-based (--sample logical) views while displaying structured span hierarchies with box-drawing characters.

Issues Fixed

• Issue-15, Fixes ENG-234
• Fixes Integrate Tracing (derived from OpenTelemetry) #15

Tasks

• 1. We now have a working visualization (Attaching terminal recordings for reference at the end).
• 2. The core library has been implemented

Final checklist

• Domain specific tests
• Full tests
• Updated inline-comment documentation
• Lint fixed
• Squash and rebased
• Sanity check the final build

Terminal 1: --sample logical

• Preview (https://asciinema.org/a/aFR8RMpu9oR0K5rno8Ko46KsG)
• Runs cli.tsx, utilizing React-Ink to display spans in a hierarchical tree structure based on logical parent-child relationships.
• Organizes spans according to their causal dependencies (e.g., child spans appear under their respective parent spans).
• Ensures that spans are grouped logically rather than by strict timestamp order, helping to visualize the structured execution flow.

Terminal 2: --sample 1s

• Preview (https://asciinema.org/a/YyzawXqKRe6D8p71NIm59QKms)
• Runs cli.tsx, utilizing React-Ink to display spans sorted by their start time rather than logical hierarchy.
• Orders spans sequentially, meaning spans that start earlier appear first, regardless of parent-child relationships.
• Provides a time-centric view, useful for debugging latency and analyzing performance bottlenecks in real-time execution.

NOTE - Closing in favour of #47

[linear]

ENG-234

[aryanjassal]

There are a lot of changes here which shouldn't have been made here. You should only make the smallest amount of changes required. At your level, you should only need to change packages and maybe add one or two new commands.

Compare your new package.json with the one on staging and merge the changes in both.

[Abby010]

I remember this now. I made those changes because I was usingts-node, but since we have migrated to tsx, merging the files isn't necessary. The existing file works with my code.

[aryanjassal]

Then make sure the additions like new bin commands or new packages are reflected in the newer file as well.

[CMCDragonkai]

I don't want any additional dependencies for the tracing system. It be entirely self-contained.

[CMCDragonkai]

Wrong branchname @Abby010. Please close this and create feature-..

[CMCDragonkai]

I'm not sure this will even go into js-logger, so for now it's an experiment. Then we can assess if js-logger is even the right library to be in. It might go into a new one js-tracer.

[CMCDragonkai]

Use setInterval to output alot of synthetic data.

[CMCDragonkai]

Integrating this into js-events would allow this to visualize the js-async-init decorators. So it is a practical usage.

[CMCDragonkai]

We should be able to use the event target to be able to show object lifecycles.

[CMCDragonkai]

Read over the repos js-async-init and js-events, and consider a plan for integration, how would this tracer end up tracing the creation, destruction and start/stop.

[CMCDragonkai]

https://github.com/MatrixAI/js-events/blob/b536114a622c5d6cc45b9953b19441c18df6019e/src/Evented.ts#L18-L34

[CMCDragonkai]

Make use of the event target listeners... and just do it there.

[CMCDragonkai]

Test on Polykey-CLI later - start a new feature branch to do this.

[CMCDragonkai]

Focus on the nodes domain - objects governed by js-async-init.

[CMCDragonkai]

Future data integration into chrome debugger protocol could be useful. That would avoid having us have to build UIs for interpreting the data. It would depend on whether there's a proper span visualizer - since ours is not compatible with opentracer. Our tracing data is a bit different.

But then again, with R1 Claude it should be possible to generate a bunch of UI code for this.

[CMCDragonkai]

@Abby010 can you reference the new PR when you close an old PR, always say Closing in favour of #....

[Abby010]

Closing in favour of #47