debugger

package
v0.8.0-pre Latest Latest
Warning

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

 Go to latest Published: Nov 13, 2024 License: MIT Imports: 33 Imported by: 0

README

go report coverage go reference last commit release matrix chat

/tools/debugger _ cd /

[!NOTE] Asyncmachine-go is an AOP Actor Model library for distributed workflows, built on top of a lightweight state machine (nondeterministic, multi-state, clock-based, relational, optionally-accepting, and non-blocking). It has atomic transitions, RPC, logging, TUI debugger, metrics, tracing, and soon diagrams.

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

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 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
	CursorTx 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
	// 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) AnyAny added in v0.6.4 

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

AnyAny is a global 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) FiltersFocusedEnd added in v0.6.0 

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

func (*Debugger) FiltersFocusedEnter added in v0.8.0 

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

func (*Debugger) FiltersFocusedState added in v0.6.0 

func (d *Debugger) FiltersFocusedState(e *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) GcMsgsState added in v0.8.0 

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

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) 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.

func (*Debugger) SelectingClientEnter 

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

func (*Debugger) SelectingClientState 

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

func (*Debugger) SetCursor added in v0.8.0 

func (d *Debugger) SetCursor(cursor int)

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) ToggleFilterState added in v0.6.0 

func (d *Debugger) ToggleFilterState(_ *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 FilterName added in v0.8.0 

type FilterName string
const (
	FilterSummaries FilterName = "hide-summaries"
)

type Focusable 

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

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
	// Address 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
	// Screen overload for tests & ssh
	Screen tcell.Screen
	// Debugger's ID
	ID string
	// version of this instance
	Version string
	// TODO
	MsgMaxAmount int
	// TODO
	MsgMaxAge time.Duration
	NoGc      bool
}

type OptsFilters added in v0.6.4 

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

type RelCol 

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

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.