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

am-dbg TUI Debugger

am-dbg is a lightweight, multi-client debugger which can handle hundreds of simultaneous streams from asyncmachines. It’s built around a timeline of transitions and allows for precise searches and drill-downs of state mutations.

Installation

• Download a release binary
• Install go install github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest
• Run directly go run github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest

Features

• states tree: list of all states and relations of the selected state machine, with their clock ticks, search-as-you-type, and error highlighting.
• log view: highlighted log view with the current transition being selected.
• address bar: navigate the hitory with 2 entries per machine.
• stepping through transitions: draws relations graph lines of the resolutions process in the states tree.
• time travel: transition and steps timelines allow to navigate in time, even between different state machines.
• transition info: show number, machine time, type, states, states, and human time of each transition.
• import / export: using Brotli and encoding/gob, it’s easy to save and share dump files.
• filters: filters narrow down both the number of transitions, and log messages.
• rain view: high-level view of transitions with error highlighting and human time, one per line.
• client list: all the currently nad previously connected state machines, with search-as-you-type, error highlighting, and remaining transitions marker.
• fast jumps: jump by 100 transitions, or select a state from the tree and jump to its next occurrence.
• keyboard navigation: the UI is keyboard accessible, just press the ? key.
• mouse support: most elements can be clicked and scrolled.
• SSH access: an instance of the debugger can be shared directly from an edge server via a built-in SSH server.
• log rotation: older entries will be automatically discarded in order.
• log reader: extract entries from LogOps and SemLogger into a dedicated pane.
  • source event: navigate to source events, internal or external.
  • queue: shows the full queue, queued and executed times for this mutation.
  • handlers: list executed handlers.
  • contexts: list state contexts and mach time.
  • subscriptions: list awaited clocks.
  • piped states: list all inbound and outbound pipes.
• partial layout: some elements of the UI can be hidden, so many instances can create dashboards

Usage:
  am-dbg [flags]

Flags:
      --clean-on-connect         Clean up disconnected clients on the 1st connection (default true)
      --dbg-am-dbg-addr string   Debug this instance of am-dbg with another one
      --dbg-go-race              Go race detector is enabled
      --dbg-id string            ID of this instance (default "am-dbg")
      --dbg-log-level int        Log level produced by this instance, 0-5 (silent-everything)
      --dbg-prof-srv string      Start pprof server
  -d, --dir string               Output directory for generated files (default ".")
      --enable-clipboard         Enable clipboard support (default true)
      --enable-mouse             Enable mouse support (experimental) (default true)
      --filter-group             Filter transitions by a selected group (default true)
      --filter-log-level int     Filter transitions to this log level, 0-5 (silent-everything) (default 2)
  -f, --fwd-data string          Forward incoming data to other instances (eg addr1,addr2)
  -h, --help                     help for am-dbg
  -i, --import-data string       Import an exported gob.br file
  -l, --listen-on string         Host and port for the debugger to listen on (default "localhost:6831")
      --log-ops-ttl string       Max time to live for logs level LogOps (default "24h")
      --max-mem int              Max memory usage (in MB) to flush old transitions (default 1000)
      --output-clients           Write a detailed client list into am-dbg-clients.txt inside --dir
      --output-diagrams int      Level of details for diagrams (svg, d2, mermaid) in --dir (0 off, 1-3 on). EXPERIMENTAL
      --output-tx                Write the current transition with steps into am-dbg-tx.md inside --dir
  -c, --select-connected         Select the newly connected machine, if no other is connected
      --select-group string      Startup group
  -m, --select-machine string    Select a machine by (partial) ID on startup (requires --import-data)
  -t, --select-transition int    Select a transaction by _number_ on startup (requires --select-machine)
      --tail                     Start from the lastest tx (default true)
      --ui-diagrams              Start a web diagrams viewer on a +1 port (EXPERIMENTAL) (default true)
      --version                  Print version and exit
  -v, --view string              Initial view (tree-log, tree-matrix, matrix) (default "tree-log")
      --view-narrow              Force a narrow view, independently of the viewport size
      --view-rain                Show the rain view
  -r, --view-reader              Enable Log Reader
      --view-timelines int       Number of timelines to show (0-2) (default 2)

Steps to Debug

1. Set up telemetry:

   import amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers"
   // ...
   // var myMach *am.Machine
   // var myMach am.Api
   amhelp.MachDebugEnv(myMach)
   

2. Run am-dbg

3. Run your code with

   # 1 expands to localhost:6831
   AM_DBG_ADDR=1
   # 3 is LogOps level
   AM_LOG=3
   # enable semantic logging
   AM_LOG_FULL=1
   

4. Your machine should show up in the debugger

Demos

Interactively use the TUI debugger with data pre-generated by a secai bot:

go run github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest \
  --import-data https://assets.asyncmachine.dev/am-dbg-exports/secai-cook.gob.br \
  mach://cook

Dashboard

Small-scale dashboards can be achieved by using the --fwd-data param, with multiple instances am-dbg as destinations. It will duplicate all the memory allocations and won’t scale far, but it will work. Check out /config/dashboards directory for preconfigured zellij layouts.

Steps for SSH Server

Download an SSH release binary or use go install:

• go install github.com/pancsta/asyncmachine-go/tools/am-dbg-ssh@latest

am-dbg-ssh is an SSH version of asyncmachine-go debugger serving local
dumps via --import-file.

You can connect to a running instance with any SSH client.

Usage:
  am-dbg-ssh -s localhost:4444 [flags]

Flags:
  ... (same am-dbg)
  -s, --ssh-addr string          SSH host:port to listen on (default "localhost:4444")