debugger

package
v0.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 15, 2025 License: MIT Imports: 36 Imported by: 0

README

/tools/debugger

cd /

[!NOTE] asyncmachine-go is a declarative control flow library implementing AOP and Actor Model through a clock-based state machine.

To read about am-dbg, go to /tools/cmd/am-dbg. This package is about the implementation, not the end-user application.

/tools/debugger is a cview TUI app with a single state machine consisting of:

  • input events (7 states)
  • external state (25 states)
  • actions (18 states)

This state machine features a decent amount of relations within a large number of states and 5 state groups. It's also a good example to see how easily an AM-based program can be controller with a script in /internal/cmd/am-dbg-video.

See states structure and relations 
// States map defines relations and properties of states.
var States = am.Struct{

    // ///// Input events

    ClientMsg:       {Multi: true},
    ConnectEvent:    {Multi: true},
    DisconnectEvent: {Multi: true},

    // user scrolling tx / steps
    UserFwd: {
        Add:    S{Fwd},
        Remove: GroupPlaying,
    },
    UserBack: {
        Add:    S{Back},
        Remove: GroupPlaying,
    },
    UserFwdStep: {
        Add:     S{FwdStep},
        Require: S{ClientSelected},
        Remove:  SAdd(GroupPlaying, S{LogUserScrolled}),
    },
    UserBackStep: {
        Add:     S{BackStep},
        Require: S{ClientSelected},
        Remove:  SAdd(GroupPlaying, S{LogUserScrolled}),
    },

    // ///// Read-only states (e.g. UI)

    // focus group

    TreeFocused:          {Remove: GroupFocused},
    LogFocused:           {Remove: GroupFocused},
    SidebarFocused:       {Remove: GroupFocused},
    TimelineTxsFocused:   {Remove: GroupFocused},
    TimelineStepsFocused: {Remove: GroupFocused},
    MatrixFocused:        {Remove: GroupFocused},
    DialogFocused:        {Remove: GroupFocused},
    FiltersFocused:       {Remove: GroupFocused},

    StateNameSelected:     {Require: S{ClientSelected}},
    TimelineStepsScrolled: {Require: S{ClientSelected}},
    HelpDialog:            {Remove: GroupDialog},
    ExportDialog: {
        Require: S{ClientSelected},
        Remove:  GroupDialog,
    },
    LogUserScrolled: {
        Remove: S{Playing, TailMode},
        // TODO remove the requirement once its possible to go back
        //  to timeline-scroll somehow
        Require: S{LogFocused},
    },
    Ready:            {Require: S{Start}},
    FilterAutoTx:     {},
    FilterCanceledTx: {},
    FilterEmptyTx:    {},

    // ///// Actions

    Start: {},
    TreeLogView: {
        Auto:   true,
        Remove: SAdd(GroupViews, S{MatrixRain}),
    },
    MatrixView:     {Remove: GroupViews},
    TreeMatrixView: {Remove: GroupViews},
    TailMode: {
        Require: S{ClientSelected},
        Remove:  SAdd(GroupPlaying, S{LogUserScrolled}),
    },
    Playing: {
        Require: S{ClientSelected},
        Remove:  SAdd(GroupPlaying, S{LogUserScrolled}),
    },
    Paused: {
        Auto:    true,
        Require: S{ClientSelected},
        Remove:  GroupPlaying,
    },
    ToggleFilter: {},
    SwitchingClientTx: {
        Require: S{Ready},
        Remove:  GroupSwitchedClientTx,
    },
    SwitchedClientTx: {
        Require: S{Ready},
        Remove:  GroupSwitchedClientTx,
    },
    ScrollToMutTx: {Require: S{ClientSelected}},
    MatrixRain:    {},

    // tx / steps back / fwd

    Fwd: {
        Require: S{ClientSelected},
    },
    Back: {
        Require: S{ClientSelected},
    },
    FwdStep: {
        Require: S{ClientSelected},
    },
    BackStep: {
        Require: S{ClientSelected},
    },

    ScrollToTx: {
        Require: S{ClientSelected},
        Remove:  S{TailMode, Playing},
    },

    // client selection

    SelectingClient: {
        Require: S{Start},
        Remove:  S{ClientSelected},
    },
    ClientSelected: {
        Require: S{Start},
        Remove:  S{SelectingClient},
    },
    RemoveClient: {Require: S{ClientSelected}},
}

You can read the source at /tools/debugger and states at /tools/debugger/states.

Integration Tests

/tools/debugger/test contains integration tests which use a local worker instance, which is then controlled with Add1Block and Add1AsyncBlock from /pkg/helpers to perform test scenarios. None of the tests ever calls time.Sleep, as everything is synchronized via asyncmachine's clock. The local test worker doesn't have UI and uses tcell.SimulationScreen instead.

Remote Worker

/tools/debugger/test/remote contains integration tests which use a remote worker to execute the same suite. The worker has to be started separately using task am-dbg-worker, and because it's a regular TUI app, this one has a UI which can be seen and controlled by the user (on top of the test suite itself).

Debugging Workers

Because both local and remote workers are state machines, they can export telemetry to a debugger instance. In aRPC Tutorial one can find a video demo presenting a debugging session of a remote worker. To activate remote debugging, please set AM_TEST_DEBUG=1 and run task am-dbg-dbg prior to tests. Remote tests are run via task test-debugger-remote.

Video Walkthrough

Schema

State schema from /tools/debugger/states/ss_dbg.go.

schema

monorepo

Go back to the monorepo root to continue reading.

Documentation

Overview

Package debugger provides a TUI debugger with multi-client support. Runnable command can be found in tools/cmd/am-dbg.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllocMem added in v0.9.0 

func AllocMem() uint64

func RpcGetter added in v0.7.0 

func RpcGetter(d *Debugger) func(string) any

TODO migrate to Provide-Delivered

Types

type Client 

type Client struct {
	// bits which get saved into the go file
	Exportable
	// current transition, 1-based, mirrors the slider
	CursorTx1 int
	// current step, 1-based, mirrors the slider
	CursorStep          int
	SelectedState       string
	SelectedReaderEntry *logReaderEntryPtr
	ReaderCollapsed     bool
	// contains filtered or unexported fields
}

type Debugger 

type Debugger struct {
	*am.ExceptionHandler
	Mach *am.Machine

	Clients    map[string]*Client
	Opts       Opts
	LayoutRoot *cview.Panels
	Disposed   bool
	// selected client
	// TODO atomic, drop eval
	C   *Client
	App *cview.Application
	// printer for numbers
	P *message.Printer
	// TODO GC removed machines
	History       []*MachAddress
	HistoryCursor int
	// contains filtered or unexported fields
}

func New added in v0.6.4 

func New(ctx context.Context, opts Opts) (*Debugger, error)

New creates a new debugger instance and optionally import a data file.

func (*Debugger) AddressFocusedEnd added in v0.9.0 

func (d *Debugger) AddressFocusedEnd(_ *am.Event)

func (*Debugger) AddressFocusedState added in v0.9.0 

func (d *Debugger) AddressFocusedState(e *am.Event)

func (*Debugger) AnyState added in v0.8.1 

func (d *Debugger) AnyState(e *am.Event)

AnyState is a global final handler

func (*Debugger) BackEnter 

func (d *Debugger) BackEnter(e *am.Event) bool

func (*Debugger) BackState 

func (d *Debugger) BackState(e *am.Event)

func (*Debugger) BackStepEnter 

func (d *Debugger) BackStepEnter(_ *am.Event) bool

func (*Debugger) BackStepState 

func (d *Debugger) BackStepState(_ *am.Event)

func (*Debugger) Client added in v0.7.0 

func (d *Debugger) Client() *Client

Client returns the current Client. Thread safe via Eval().

func (*Debugger) ClientMsgEnter 

func (d *Debugger) ClientMsgEnter(e *am.Event) bool

func (*Debugger) ClientMsgState 

func (d *Debugger) ClientMsgState(e *am.Event)

func (*Debugger) ClientSelectedEnd 

func (d *Debugger) ClientSelectedEnd(e *am.Event)

func (*Debugger) ClientSelectedState 

func (d *Debugger) ClientSelectedState(e *am.Event)

func (*Debugger) ConnectEventEnter 

func (d *Debugger) ConnectEventEnter(e *am.Event) bool

func (*Debugger) ConnectEventState 

func (d *Debugger) ConnectEventState(e *am.Event)

func (*Debugger) ConnectedClients 

func (d *Debugger) ConnectedClients() int

func (*Debugger) CurrentTx 

func (d *Debugger) CurrentTx() *telemetry.DbgMsgTx

CurrentTx returns the current transition. Thread safe via Eval().

func (*Debugger) DisconnectEventEnter 

func (d *Debugger) DisconnectEventEnter(e *am.Event) bool

func (*Debugger) DisconnectEventState 

func (d *Debugger) DisconnectEventState(e *am.Event)

func (*Debugger) Dispose added in v0.6.4 

func (d *Debugger) Dispose()

func (*Debugger) ExceptionState added in v0.8.0 

func (d *Debugger) ExceptionState(e *am.Event)

ExceptionState creates a log file with the error and stack trace, after calling the super exception handler.

func (*Debugger) ExportDialogEnd 

func (d *Debugger) ExportDialogEnd(e *am.Event)

func (*Debugger) ExportDialogState 

func (d *Debugger) ExportDialogState(_ *am.Event)

func (*Debugger) FwdEnter 

func (d *Debugger) FwdEnter(e *am.Event) bool

func (*Debugger) FwdState 

func (d *Debugger) FwdState(e *am.Event)

func (*Debugger) FwdStepEnter 

func (d *Debugger) FwdStepEnter(_ *am.Event) bool

func (*Debugger) FwdStepState 

func (d *Debugger) FwdStepState(_ *am.Event)

func (*Debugger) GcMsgsEnter added in v0.9.0 

func (d *Debugger) GcMsgsEnter(e *am.Event) bool

func (*Debugger) GcMsgsState added in v0.8.0 

func (d *Debugger) GcMsgsState(e *am.Event)

func (*Debugger) GetMachAddress added in v0.9.0 

func (d *Debugger) GetMachAddress() *MachAddress

GetMachAddress returns the address of the currently visible view (mach, tx).

func (*Debugger) GetParentTags added in v0.9.1 

func (d *Debugger) GetParentTags(c *Client, tags []string) []string

func (*Debugger) GoToMachAddress added in v0.9.0 

func (d *Debugger) GoToMachAddress(addr *MachAddress, skipHistory bool) bool

GoToMachAddress tries to render a view of the provided address (mach, tx).

func (*Debugger) HealthcheckState added in v0.8.0 

func (d *Debugger) HealthcheckState(_ *am.Event)

func (*Debugger) HelpDialogEnd 

func (d *Debugger) HelpDialogEnd(e *am.Event)

func (*Debugger) HelpDialogState 

func (d *Debugger) HelpDialogState(_ *am.Event)

func (*Debugger) ImportData 

func (d *Debugger) ImportData(filename string)

func (*Debugger) LogReaderVisibleEnd added in v0.8.0 

func (d *Debugger) LogReaderVisibleEnd(e *am.Event)

func (*Debugger) LogReaderVisibleState added in v0.8.0 

func (d *Debugger) LogReaderVisibleState(e *am.Event)

func (*Debugger) MatrixRainState added in v0.7.0 

func (d *Debugger) MatrixRainState(_ *am.Event)

func (*Debugger) MatrixViewEnd 

func (d *Debugger) MatrixViewEnd(_ *am.Event)

func (*Debugger) MatrixViewState 

func (d *Debugger) MatrixViewState(_ *am.Event)

func (*Debugger) NextTx 

func (d *Debugger) NextTx() *telemetry.DbgMsgTx

NextTx returns the next transition. Thread safe via Eval().

func (*Debugger) PausedState 

func (d *Debugger) PausedState(_ *am.Event)

func (*Debugger) PlayingEnd 

func (d *Debugger) PlayingEnd(_ *am.Event)

func (*Debugger) PlayingState 

func (d *Debugger) PlayingState(_ *am.Event)

func (*Debugger) PrevTx 

func (d *Debugger) PrevTx() *telemetry.DbgMsgTx

PrevTx returns the previous transition. Thread safe via Eval().

func (*Debugger) ProcessFilterChange added in v0.8.0 

func (d *Debugger) ProcessFilterChange(ctx context.Context, filterTxs bool)

func (*Debugger) ReadyEnd added in v0.8.0 

func (d *Debugger) ReadyEnd(_ *am.Event)

func (*Debugger) ReadyState added in v0.8.0 

func (d *Debugger) ReadyState(_ *am.Event)

func (*Debugger) RedrawFull 

func (d *Debugger) RedrawFull(immediate bool)

RedrawFull updates all components of the debugger UI, except the sidebar.

func (*Debugger) RemoveClientEnter 

func (d *Debugger) RemoveClientEnter(e *am.Event) bool

func (*Debugger) RemoveClientState 

func (d *Debugger) RemoveClientState(e *am.Event)

func (*Debugger) ScrollToMutTxState added in v0.7.0 

func (d *Debugger) ScrollToMutTxState(e *am.Event)

ScrollToMutTxState scrolls to a transition which mutated the passed state, If fwd is true, it scrolls forward, otherwise backwards.

func (*Debugger) ScrollToStepEnter added in v0.9.0 

func (d *Debugger) ScrollToStepEnter(e *am.Event) bool

func (*Debugger) ScrollToStepState added in v0.9.0 

func (d *Debugger) ScrollToStepState(e *am.Event)

ScrollToTxState scrolls to a specific transition (cursor position 1-based).

func (*Debugger) ScrollToTxEnter 

func (d *Debugger) ScrollToTxEnter(e *am.Event) bool

func (*Debugger) ScrollToTxState 

func (d *Debugger) ScrollToTxState(e *am.Event)

ScrollToTxState scrolls to a specific transition (cursor position 1-based).

func (*Debugger) SelectingClientEnter 

func (d *Debugger) SelectingClientEnter(e *am.Event) bool

func (*Debugger) SelectingClientState 

func (d *Debugger) SelectingClientState(e *am.Event)

func (*Debugger) SetCursor1 added in v0.9.1 

func (d *Debugger) SetCursor1(cursor int, skipHistory bool)

func (*Debugger) SetFilterLogLevel added in v0.6.4 

func (d *Debugger) SetFilterLogLevel(lvl am.LogLevel)

func (*Debugger) Start added in v0.6.4 

func (d *Debugger) Start(clientID string, txNum int, uiView string)

func (*Debugger) StartEnd 

func (d *Debugger) StartEnd(_ *am.Event)

func (*Debugger) StartState 

func (d *Debugger) StartState(e *am.Event)

func (*Debugger) StateNameSelectedEnd 

func (d *Debugger) StateNameSelectedEnd(_ *am.Event)

func (*Debugger) StateNameSelectedState 

func (d *Debugger) StateNameSelectedState(e *am.Event)

func (*Debugger) StateNameSelectedStateNameSelected 

func (d *Debugger) StateNameSelectedStateNameSelected(e *am.Event)

StateNameSelectedStateNameSelected handles cursor moving from a state name to another state name case.

func (*Debugger) SwitchedClientTxState added in v0.7.0 

func (d *Debugger) SwitchedClientTxState(_ *am.Event)

func (*Debugger) SwitchingClientTxState added in v0.7.0 

func (d *Debugger) SwitchingClientTxState(e *am.Event)

func (*Debugger) TailModeEnd added in v0.8.0 

func (d *Debugger) TailModeEnd(_ *am.Event)

func (*Debugger) TailModeState 

func (d *Debugger) TailModeState(_ *am.Event)

func (*Debugger) TimelineStepsFocusedEnd 

func (d *Debugger) TimelineStepsFocusedEnd(_ *am.Event)

func (*Debugger) TimelineStepsFocusedState 

func (d *Debugger) TimelineStepsFocusedState(_ *am.Event)

func (*Debugger) TimelineStepsScrolledEnd added in v0.9.0 

func (d *Debugger) TimelineStepsScrolledEnd(_ *am.Event)

func (*Debugger) TimelineStepsScrolledState added in v0.9.0 

func (d *Debugger) TimelineStepsScrolledState(_ *am.Event)

func (*Debugger) ToggleToolEnter added in v0.10.1 

func (d *Debugger) ToggleToolEnter(e *am.Event) bool

func (*Debugger) ToggleToolState added in v0.10.1 

func (d *Debugger) ToggleToolState(e *am.Event)

func (*Debugger) Toolbar1FocusedEnd added in v0.10.1 

func (d *Debugger) Toolbar1FocusedEnd(_ *am.Event)

func (*Debugger) Toolbar1FocusedState added in v0.10.1 

func (d *Debugger) Toolbar1FocusedState(e *am.Event)

func (*Debugger) Toolbar2FocusedEnd added in v0.10.1 

func (d *Debugger) Toolbar2FocusedEnd(_ *am.Event)

func (*Debugger) Toolbar2FocusedState added in v0.10.1 

func (d *Debugger) Toolbar2FocusedState(e *am.Event)

func (*Debugger) TreeMatrixViewEnd 

func (d *Debugger) TreeMatrixViewEnd(_ *am.Event)

func (*Debugger) TreeMatrixViewState 

func (d *Debugger) TreeMatrixViewState(_ *am.Event)

func (*Debugger) UserBackState 

func (d *Debugger) UserBackState(_ *am.Event)

func (*Debugger) UserBackStepState 

func (d *Debugger) UserBackStepState(_ *am.Event)

func (*Debugger) UserFwdState 

func (d *Debugger) UserFwdState(_ *am.Event)

func (*Debugger) UserFwdStepState 

func (d *Debugger) UserFwdStepState(_ *am.Event)

type Exportable 

type Exportable struct {
	MsgStruct *telemetry.DbgMsgStruct
	MsgTxs    []*telemetry.DbgMsgTx
}

type Focusable 

type Focusable struct {
	cview.Primitive
	*cview.Box
}

type MachAddress added in v0.9.0 

type MachAddress struct {
	MachId    string
	TxId      string
	MachTime  uint64
	HumanTime time.Time
	// TODO support step
	Step int
}

func (*MachAddress) Clone added in v0.9.0 

func (ma *MachAddress) Clone() *MachAddress

func (*MachAddress) String added in v0.9.0 

func (a *MachAddress) String() string

type MachTime added in v0.9.0 

type MachTime struct {
	Id   string
	Time uint64
}

type MsgTxParsed 

type MsgTxParsed struct {
	StatesAdded   []int
	StatesRemoved []int
	StatesTouched []int
	// TimeSum is machine time.
	TimeSum       uint64
	ReaderEntries []*logReaderEntryPtr
}

type Opts added in v0.6.4 

type Opts struct {
	SelectConnected bool
	CleanOnConnect  bool
	EnableMouse     bool
	ShowReader      bool
	// MachAddress to listen on
	ServerAddr string
	// Log level of the debugger's machine
	DbgLogLevel am.LogLevel
	DbgLogger   *log.Logger
	// Filters for the transitions and logging
	Filters *OptsFilters
	// File path to import (brotli)
	ImportData string
	// File to dump client list into.
	ClientList string
	// Screen overload for tests & ssh
	Screen tcell.Screen
	// Debugger's ID
	ID string
	// version of this instance
	Version  string
	MaxMemMb int
	Log2Ttl  time.Duration
}

type OptsFilters added in v0.6.4 

type OptsFilters struct {
	SkipCanceledTx  bool
	SkipAutoTx      bool
	SkipEmptyTx     bool
	SkipHealthcheck bool
	LogLevel        am.LogLevel
}

type RelCol 

type RelCol struct {
	// contains filtered or unexported fields
}

type ToolName added in v0.10.1 

type ToolName string
const (
	ToolFilterSummaries ToolName = "hide-summaries"
)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.