tdbg Debugger

Introduction

The tdbg debugger is a powerful terminal-based interface for debugging
applications using the Debug Anything Protocol. It allows developers to
connect to a running application via a WebSocket connection and provides tools
to monitor and control the execution flow of the application.

Installation

tdbg is run from the terminal and does not require installation. Simply
ensure that the executable is in your path or run it from the location where it
is stored.

Usage

To start debugging with tdbg, you will need the WebSocket URL of the running
application and a registration code if required.

``plaintext
Usage: tdbg [options] [wsurl]

Arguments:
wsurl WebSocket URL (default: "ws://127.0.0.1:6400")

Options:
-r, --registration_code Registration code to connect to the debugger server
-n, --name Name for this session
-l, --log_activity Log all DAP messages to the debug log
`

If your application requires a registration code, be sure to add it to the command line.

If you set the TDBG_DEBUG_FILE prior to launching tdbg, it will log it's internal
activity to the file you provide, this can be helpful when debugging the interaction
with a new service.

Launching tdbg

When you launch tdbg, you will be greeted by the following panes:

- Code Viewer Area: Shows the current state of the code being debugged.
- Watch List: Located at the top right, this area allows monitoring the values of variables.
- System Log: Below the code area, it logs messages from the system being debugged.
- Command Input Area: At the bottom, where you input commands to control the debugger.
- Status Line: At the very bottom, displaying the current status of the debugger.

Navigation

- Use standard keyboard navigation for the command input (left/right arrows, Ctrl+A, Ctrl+E).
- Up Arrow and Down Arrow to scroll through command history.
- Tab to cycle between the different panes.
- In the watch area, use up/down arrows to move between watch variables and Enter to open them in the data explorer.
- Press f in the data explorer window to toggle between normal and flattened JSON display.

Understanding Contexts in tdbg

In tdbg, a context represents a unique execution environment or thread
within your application. It encapsulates the state of the application at a
specific point in time, including variables, the call stack, and the command
that's currently executing. Managing contexts is crucial for debugging complex
applications where multiple threads or tasks may be operating concurrently.
Each context is isolated; when you switch contexts, tdbg updates to show the
state of the newly selected context. This allows you to focus on and step
through the execution of discrete sections of your code, providing a powerful
tool to pinpoint and resolve issues effectively.

Commands

$3

Connect to the debugger. Defaults are used if not provided.

$3

Reconnect to the last debugger.

$3

Disconnect from the current debugger.

$3

Display the value of an expression in the watch area.

$3

Remove an expression from the watch area.

$3

Pause the current or next running context if none is active.

$3

Resume execution in the current context.

$3

Output the value of an expression in the console. Shortcut: v

$3

Open an expression in the data explorer. Shortcut: x

$3

Select the context to debug from available options.

$3

Move one step forward in execution. Shortcut: n

$3

Show help information.

$3

Quit the debugger.

Getting Help

To display a list of available commands and their descriptions, type help in the command input area.




A sample Debugging Session

A typical debugging session with tdbg allows you to interactively step
through the execution of your application, inspect variables, and control the
execution flow. Here's how a basic session unfolds:

$3

1. Launch tdbg it will connect to the server to debug.
2. Issue the pause command, which tells the server to stop at the next
possible breakpoint for any new job that is started. This may create a new
execution context.

$3

- When a new context is generated, tdbg will log a message indicating that new contexts are available.
- Use the select command to view and choose from the available contexts. Choosing a context will load its current state into the debugger.

$3

- Once you've selected a context, you can step through the code using the
next command. This steps through the execution flow one step at a time.
- After each step, the context's data will be updated, allowing you to monitor
changes to variables and application state in real-time.

$3

- To inspect a variable, use the view or explore command with the
variable's name, prefixed by a dollar sign (e.g., $person for a variable
named person).
- DTL's expression syntax is used here, enabling not just variable inspection
but also the evaluation of expressions. For example, strftime("%F", $date)
could be used to format a date.
- You can set up a watch for any variable or expression using the watch
command, which will display its value in the watch area.

$3

- Issue the resume command to allow the remote system to continue execution.
The system may either run to completion or stop at the next developer-defined
pause point.

$3

- When the current context completes, the screen will clear, signaling that you
can select a new context if available.
- Debug log messages from the server will be displayed in the log area,
providing insights into the execution process and issues.

$3

- To end your debugging session, simply issue the quit command.

Using the pause, next, explore, and watch` commands in tandem allows you
to conduct a thorough inspection of how a process operates, offering you the
granularity needed to diagnose and fix issues effectively.