/tools/cmd/am-vis/README.md

am-vis

am-vis renders diagrams from dbg telemetry by creating a graph of interconnected state machines. The graph is based on fragmented data they provide via:

• state schema
  • states
  • relations
  • tags
• LogOps (level 3)
  • pipes
  • RPC connections
• transitions
  • active states

The rendering uses ELK (Eclipse Layout Kernel) and is done by D2 (embedded). At the moment it can only render from file dumps, with the live-server version is yet to come.

Installation

Available options:

1. Download a release binary
2. Install go install github.com/pancsta/asyncmachine-go/tools/cmd/am-vis@latest
3. Run directly go run github.com/pancsta/asyncmachine-go/tools/cmd/am-vis@latest

Features

$ 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

Graphs can be programmatically filtered using the rendering config:

type Renderer 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

• rendering from live connections
• browser viewer with auto-reload
• 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

Gallery

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

Transition Sequence

Transitions can be plotted as sequence diagrams and rendered to SVG and ASCII. Currently am-dbg does it automatically with --output-tx and places files inside --dir. Support in am-vis CLI coming soon.

This is the same steps diagram as the second timeline of am-dbg and includes:

• all called and touched states
• called steps
• relation steps
• handler calls
• cancellations

┌────────────────┐     ┌───────┐     ┌───────┐
│ ReplaceStories │     │ Start │     │ Ready │
└────────┬───────┘     └───┬───┘     └───┬───┘
         │                 │             │
         │ called          │             │
         ├──┐              │             │
         │  │              │             │
         │◄─┘              │             │
         │                 │             │
         │ activate        │             │
         ├──┐              │             │
         │  │              │             │
         │◄─┘              │             │
         │                 │             │
         │                 │ require     │
         │                 │◄────────────┤
         │                 │             │
         │                 │ require     │
         │                 │◄────────────┤
         │                 │             │
         │ ReplaceStoriesState           │
         ├──┐              │             │
         │  │              │             │
         │◄─┘              │             │
         │                 │             │

Credits

• D2
• mermaid-ascii