Workflow of an rdebug debugging session

rdebug requires two connections:

  • The worker connection: this is where one's stored routine is executed.
  • The debugger session: this session controls the flow of the worker; this is the session that "steps-into", "steps-over", watches variables, modifies them; looks at metadata.

The debugger needs to attach itself to the worker. This is done by figuring out the worker's session ID. The relevant routines must be compiled with debug mode beforehand. Both sessions are then ready for the debugging session.

The following illustrates the general workflow of a debugging session, looking at both the debugger and the worker. For this illustration, we assume debugging the routine test.take_action().

General workflow

worker session: get connection ID.

mysql [worker]> SELECT CONNECTION_ID();
|            2819 |

debugger session: compile routine with debug info.

mysql [debugger]> use common_schema;
mysql [debugger]> call rdebug_compile_routine('test', 'take_action', true);
Start a debug session, attach to worker session using its connection ID:
mysql [debugger]> call rdebug_start(2819);
Optionally set verbose mode on:
mysql [debugger]> call rdebug_set_verbose(true);
Begin controlling the worker. In this worker we work by stepping through the routine:
mysql [debugger]> call rdebug_step_over();
The debugger is now awaiting action to be taken by the worker.

worker session: issue the routine.

mysql [worker]> call test.take_action();

debugger session: at this time the debugger has control over the worker. Due to verbose mode, it dumps thread stack status, watches local variables, shows next statement to execute. The debugger may further control the flow of the worker:

(status dump)
mysql [debugger]> call rdebug_step_over();
(status dump)
mysql [debugger]> call rdebug_step_over();
(status dump)
mysql [debugger]> call rdebug_watch_variables();
(variables dump)
mysql [debugger]> call rdebug_set_variable('my_local_variable', 'my_new_value');
(status dump)
mysql [debugger]> call rdebug_step_over();
(status dump)
mysql [debugger]> call rdebug_step_out();
mysql [debugger]> 
At this workflow we finally exit via rdebug_step_out(), or we may choose to keep running rdebug_step_over() until test.take_action() completes. Either way, both worker and debugger complete the debugging session.

debugger session: do proper cleanup:

mysql [debugger]> call rdebug_stop();
At this point all debug-session info is cleared. However, the test.take_action() routine is still compiled with debug mode; you may choose to keep them that way (it will act as normal when not under a debugger control, but will have excessive code). At some point you will want to remove debugging info from the routine:
mysql [debugger]> call rdebug_compile_routine('test', 'take_action', false);

Workflow variations

One may choose to set a breakpoint on test.take_action(). For that, one needs to know what breakpoints are available. debugger session: detect breakpoint info:

mysql [debugger]> call rdebug_show_routine('test', 'take_action');
(dump of routine code with special numbers -- breakpoint IDs)
See rdebug_show_routine() for an output sample. Breakpoints can be set via:
mysql [debugger]> call rdebug_set_breakpoint('test', 'take_action', 126, null);
(assuming 126 is a relevant breakpoint ID).

The test.take_action() routine can be executed until it reaches said breakpoint:

mysql [debugger]> call rdebug_run();


rdebug, rdebug API


Shlomi Noach
common_schema documentation