feat(am-vis): add diagram generator

[pancsta]

am-vis is a dbg protocol based distributed diagram renderer. It creates a graph of interconnected machines, based on fragmented data they provide via:

• state schema
  • states
  • relations
  • tags
• logs L2
  • pipes
  • RPC connections
• transitions
  • active states

It does not persist transitions and only knows the latest active states. The rendering uses ELK and is done by:

• D2 (shipped, mid-sized diagrams)
• Mermaid (basic support, not shipped, small-sized diagrams)

This prototype reads am-dbg-dump.gob.br export file and renderes some predefined configurations. machIds need to be adjusted to the dumped machine IDs.

Config

Graphs can be filtered using the rendering config:

type Visualizer struct {
    // Render only these machines as starting points.
    RenderMachs []string
    // Render only machines matching the regular expressions as starting points.
    RenderMachsRe []*regexp.Regexp
    // Skip rendering of these machines.
    RenderSkipMachs []string
    // Distance to render from starting machines.
    RenderDistance int
    // How deep to render from starting machines. Same as RenderDistance, but only
    // for submachines.
    RenderDepth int
    
    // Render states bubbles.
    RenderStates bool
    // With RenderStates, false will hide Start, and without RenderStates true
    // will render Start.
    RenderStart bool
    // With RenderStates, false will hide Exception, and without RenderStates true
    // will render Exception.
    RenderException bool
    // With RenderStates, false will hide Ready, and without RenderStates true
    // will render Ready.
    RenderReady bool
    // Render states which have pipes being rendered, even if the state should
    // not be rendered.
    RenderPipeStates bool
    // Render group of pipes as mach->mach
    RenderPipes bool
    // Render pipes to non-rendered machines / states.
    RenderHalfPipes bool
    // Render detailed pipes as state -> state
    RenderDetailedPipes bool
    // Render relation between states.
    RenderRelations bool
    // Style currently active states.
    RenderActive    bool
    // Render the parent relation. Ignored when RenderNestSubmachines.
    RenderParentRel bool
    // Render submachines nested inside their parents. See also RenderDepth.
    RenderNestSubmachines bool
    // Render a tags box for machines having some.
    RenderTags            bool
    // Render RPC connections
    RenderConns bool
    // Render RPC connections to non-rendered machines.
    RenderHalfConns bool
    // Render a parent relation to and from non-rendered machines.
    RenderHalfHierarchy bool
    // Render inherited states.
    RenderInherited     bool
    // Mark inherited states.
    RenderMarkInherited bool
}

TODO

• refactor to support
  • am-vis import-render mydiag --import-file dump.gob.br --output-svg --render-opt1=true ...
  • am-vis live-render mydiag --output-svg --render-opt1=true ...
• extract rendering
  • parallel rendering within a single am-vis instance
• config file, watch for changes
• extract pkg/graph
• cleanups

Later / out of scope

• add a TUI version of the rendering config
• use D2 API instead of gluing strings
• support GC, store machine time for enter / exit
• add G6 renderer for large graphs

Legend

• yellow border = machine requested by ID
• white border = machine close or deep enough from a requested one
• no border = not fully rendered machine for grouped inbound and outbound edges
• yellow state = active
• double border state = own / non-inherited state
• blue state = Ready active
• green state = Start active

Previews

It's recommended to view the SVGs using SVG Navigator.

%%{init: {'flowchart': {'defaultRenderer': 'elk'}} }%%
flowchart LR
	classDef _active color:black,fill:yellow;
	subgraph a[nc-TCWP-cli-140116<br>#node-client]
		direction TB
		b([WorkerRequested])
		b --o c
		d([WorkerDisconnected])
		e([Exception])
		f([SuperDisconnecting])
		g([WorkerReady])
		g --x b
		h([ErrWorker])
		h --o e
		i([Ready])
		i --o g
		j([SuperConnecting])
		c([SuperReady])
		k([WorkerDisconnecting])
		l([WorkerPayload])
		m([Start])
		n([WorkerConnecting])
		o([ErrSupervisor])
		o --o e
		p([WorkerConnected])
		q([ErrNetwork])
		q --o e
		r([Heartbeat])
		s([ErrHandlerTimeout])
		s --o e
		t([Healthcheck])
		u([SuperConnected])
		v([SuperDisconnected])
		class p,g,i,u,c,m _active;
	end

Loading

[pancsta]

Partially released in #229.

[pancsta]

Caching shipped in #268.

[pancsta]

$ am-vis render-dump --help

Render diagrams of interconnected state machines.

Examples:

# single machine
am-vis render-dump mymach.gob.br mach://MyMach1/t234

# bird's view with distance of 2 from MyMach1
am-vis --bird -d 2 \
        render-dump mymach.gob.br mach://MyMach1/TX-ID

# bird's view with detailed pipes
am-vis --bird --render-detailed-pipes \
        render-dump mymach.gob.br mach://MyMach1/TX-ID

# map view with inherited states
am-vis --render-inherited \
        render-dump mymach.gob.br mach://MyMach1/t234

# map view
am-vis --map render-dump mymach.gob.br

Usage: am-vis render-dump [--dump-file DUMP-FILE] [MACHURL]

Positional arguments:
  MACHURL

Options:
  --dump-file DUMP-FILE, -f DUMP-FILE
                         Input dbg dump file [default: am-dbg-dump.gob.br]

Global options:
  --render-distance RENDER-DISTANCE, -d RENDER-DISTANCE [default: 0]
  --render-depth RENDER-DEPTH [default: 0]
  --render-start [default: false]
  --render-ready [default: false]
  --render-exception [default: false]
  --render-states [default: true]
  --render-inherited [default: true]
  --render-pipes [default: false]
  --render-detailed-pipes [default: true]
  --render-relations [default: true]
  --render-conns [default: true]
  --render-parent-rel [default: true]
  --render-half-conns [default: true]
  --render-half-pipes [default: true]
  --render-nest-submachines [default: false]
  --render-tags [default: false]
  --bird, -b             Use the bird's view preset
  --map, -b              Use the map view preset
  --output-elk           Use ELK layout [default: true]
  --output-filename OUTPUT-FILENAME, -o OUTPUT-FILENAME [default: am-vis]
  --help, -h             display this help and exit