Skip to content

Latest commit

 

History

History
179 lines (129 loc) · 7.16 KB

README.md

File metadata and controls

179 lines (129 loc) · 7.16 KB
Raw

/tools/cmd/am-dbg

cd /

Note

Asyncmachine-go is an AOP Actor Model library for distributed workflows, built on top of a lightweight state machine. It has atomic transitions, RPC, logging, TUI debugger, metrics, tracing, and soon diagrams.

am-dbg

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.

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.
  • 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 based, just press ?.
  • 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 into a dedicated pane.
Usage:
  am-dbg [flags]

Flags:
      --am-dbg-addr string      Debug this instance of am-dbg with another one
      --clean-on-connect        Clean up disconnected clients on the 1st connection
      --enable-mouse            Enable mouse support (experimental)
  -h, --help                    help for am-dbg
  -i, --import-data string      ImportFile an exported gob.bt file
  -l, --listen-on string        Host and port for the debugger to listen on (default "localhost:6831")
      --log-file string         Log file path (default "am-dbg.log")
      --log-level int           Log level, 0-5 (silent-everything)
      --prof-srv                Start pprof server on :6060
  -c, --select-connected        Select the newly connected machine, if no other is connected
  -m, --select-machine string   Select a machine by ID on startup (requires --import-data)
  -t, --select-transition int   Select a transaction by _number_ on startup (requires --select-machine)
      --version                 Print version and exit
  -v, --view string             Initial view (tree-log, tree-matrix, matrix) (default "tree-log")

legend

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

Demos

Interactively use the TUI debugger with data pre-generated by libp2p-pubsub-simulator or remote integration tests in one of the available ways below.

Local no install

PubSub:

go run github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest \
  --select-machine sim-p1 \
  --select-transition 25 \
  --import-data https://pancsta.github.io/assets/asyncmachine-go/am-dbg-exports/pubsub-sim.gob.br

Tests:

go run github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest \
  --select-machine d-rem-worker \
  --select-transition 1100 \
  --import-data https://pancsta.github.io/assets/asyncmachine-go/am-dbg-exports/remote-tests.gob.br

Remote no install

PubSub:

Tests:

Steps to Debug

  1. Set up telemetry:

    import amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers"
// ...
amhelp.MachDebugEnv(myMach)

  2. Run am-dbg

  3. Run your code with

    AM_DBG_ADDR=localhost:6831
AM_LOG=2

  4. Your machine should show up in the debugger

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.

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

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

FAQ

How to debug steps of a transition?

Go to the steps timelines (bottom one) using the Tab key, then press left/right like before.

How to export data?

Press alt+s and Enter.

How to filter out canceled transitions?

Press alt+f or Tab until the bottom filter bar receives focus. Now select "Skip Canceled".

How to access the help screen?

Press ? to show the help popup.

monorepo

Go back to the monorepo root to continue reading.