Previous: , Up: Debugging tools   [Contents][Index]


9.2 Debugger command reference

To use these commands at the REPL, they must be preceded by a comma. Evaluate ,help goblins for a convenient listing of all Goblins commands.

Command: vats

Print a listing of all vats in the current Guile process.

Command: enter-vat vat

Enter a sub-REPL where all expressions are evaluated within the context of vat. vat may be either a vat object or a vat identifier number (see the output of ,vats for that information.)

All of the following commands rely upon the vat context established by the ,enter-vat command.

Command: vat-log-enable

Enable vat event logging for the current vat.

Command: vat-log-disable

Disable vat event logging for the current vat.

Command: vat-tail [n]

Display the most recent n messages (10 by default) in the current vat. Every event is printed with its corresponding Lamport timestamp that can be used to identify the event within the vat. These timestamps are used to form a partial ordering of events across many vats and do not represent when an event happened in real time.

Command: vat-trace [timestamp]

Display a backtrace of events starting from timestamp in the current vat. If timestamp is not specified, then the automatically chosen timestamp varies depending upon if the Goblins debugger is active. If the debugger is active, then the timestamp of the current vat event is used, otherwise the current vat time is used.

Command: vat-tree [timestamp #:full?]

Display a tree view of events starting at timestamp in the current vat. If timestamp is not specified, the current vat time is used. By default, a lot of system-level messages (mostly about promise resolution) are omitted from the output for readability reasons. If full? is #t then the full event tree will be printed.

Command: vat-graph [timestamp]

Generate an image of the event tree for timestamp in the current vat using Graphviz. If timestamp is not specified, the current vat time is used.

Images are stored in /tmp/goblins-repl-images. When using Geiser in Emacs, the resulting image will be conveniently rendered inline. Otherwise, the output will look like #<Image: /tmp/geiser-repl-images/17GfwYo8ums9Lit6.png>.

Command: vat-resolve promise

Wait for promise to resolve and print the result. When the promise is fulfilled, the resulting value will be printed. When the promise is broken, an error message will be printed. Pressing Ctrl+C will interrupt the wait and return control to the Guile prompt.

Command: vat-errors

Display a list of errors that have occurred in the current vat and their associated timestamps. The event timestamps can be used as the basis for a debugging session via ,vat-debug.

Command: vat-debug [timestamp]

Debug the error associated with the event at timestamp by opening a sub-REPL with a debugging context focused on the vat trace of the chosen event. If timestamp is not specified, the current vat time is used.

The following commands only work in the context of the vat debugger, either started manually via ,vat-debug or as the result of an exception being raised when evaluating code within an ,enter-vat REPL. Within the vat debug REPL, much like Guile’s stack-based debugger, there is a focus on one event (analogous to a stack frame) in the trace. The focused event can be changed by moving up and down the event trace, and the state of the vat at the time of the focused event can be inspected.

Command: vat-up

Move to the previous event in the current vat debug trace.

Command: vat-down

Move to the next event in the current vat debug trace.

Command: vat-top

Move to the oldest event in the current vat debug trace.

Command: vat-bottom

Move to the most recent event in the current vat debug trace.

Command: vat-jump timestamp

Move to the event for timestamp in the current vat debug trace.

Command: vat-peek refr [args ...]

Travel back in time and send args to the actor reference refr as it existed just before the focused event happened. This works by querying the actormap snapshot that has been captured for this event. refr must be near to the vat to which the focused event belongs.


Previous: Debugger tutorial, Up: Debugging tools   [Contents][Index]