Command Line Interface

mdb

mdb is comprised of two sub-commands [attach] and [launch].

They both need to be run in order to start a debug session.

• Firstly, use the launch command to start the mdb debug processes.

• Then, use attach to connect mdb to the debug processes.

See documentation of the respective subcommands for more information.

Usage

mdb [OPTIONS] COMMAND [ARGS]...

attach

Attach to mdb debug server.

Example:

$ mdb attach -x script.mdb

Usage

mdb attach [OPTIONS]

Options

-h, --hostname <hostname>

Hostname where exchange server is running.

Default:

''

-p, --port <port>

Starting port address. Each rank’s port is assigned as [port_address + rank].

Default:

2000

-x, --exec-script <exec_script>

Execute a set of mdb commands contained in a script file. This script will run and then normal shell mode will be resumed unless –interactive=false is also passed.

--interactive <interactive>

Controls whether mdb will spawn an interactive debugging shell or not. Intended use is for with -x/–exec-script.

--log-level <log_level>

Choose minimum level of debug messages: [DEBUG, INFO, WARN, ERROR, CRITICAL]

Default:

'WARN'

--log-file <log_file>

The path to a file to write the logs to. Will create the file if it does not exist. Special values are stderr and stdout, which correspond to the programs standard error and output respectively.

Default:

'mdb-attach.log'

--plot-lib <plot_lib>

Plotting library to use. Recommended default is [termgraph] but if this is not available [matplotlib] will be used. [matplotlib] is best if there are many ranks to debug e.g., -n 100.

Default:

'termgraph'

--connection-attempts <connection_attempts>

Maximum number of failed connection attempts. A connection attempt is made once per second.

Default:

3

launch

Launch mdb debug server.

Example:

$ mdb launch -n 8 -b gdb -t ./simple-mpi.exe – -arg1 value

Usage

mdb launch [OPTIONS] [ARGS]...

Options

-n, -np, --ranks <ranks>

Total number of ranks to debug.

Default:

1

-s, --select <select>

Rank(s) to debug e.g., 0,3-5 will debug ranks 0,3,4 and 5. If empty all ranks will be selected. Note ranks starts with zero index.

-h, --hostname <hostname>

Hostname of machine where exchange server will run. If left empty, it will default to the IP address of the machine that submits the mdb launch command. Note that if running multinode jobs the hostname needs to be resolvable and not just localhost i.e., 127.0.0.1.

Default:

''

--mpi-command <mpi_command>

MPI launcher e.g., mpirun, mpiexec, srun etc.

Default:

'mpirun'

--mpi-config-opt <mpi_config_opt>

mdb will try to automatically detect the option name for the –app/–configfile option. This option overrides the automatic detection.

Default:

''

-p, --port <port>

Starting port address. Each rank’s port is assigned as [port_address + rank].

Default:

2000

-b, --backend <backend>

Debug backend e.g., gdb, lldb etc.

-t, --target <target>

Required Target binary to debug.

--mdb-home <mdb_home>

Directory where mdb SSL/TLS certificate and key are stored.

Default:

'~/.mdb'

--redirect-stdout <redirect_stdout>

Redirect stdout from the target binary. If omitted, stdout will not be redirected.

-r, --auto-restart

Allow mdb launcher to automatically relaunch the job if the debug session ends.

Default:

False

--log-level <log_level>

Choose minimum level of debug messages: [DEBUG, INFO, WARN, ERROR, CRITICAL]

Default:

'WARN'

--connection-attempts <connection_attempts>

Maximum number of failed connection attempts. A connection attempt is made once per second.

Default:

10

Arguments

ARGS

Optional argument(s)

version

Get the version number of mdb.

Usage

mdb version [OPTIONS]

wrapper

Run mdb wrapper for debug backend.

Note: this is not expected to be run manually by the user. It should be called by mdb launch which will pass the appropriate options.

Example:

$ mdb wrapper -m 1 -h localhost -p 2000 -b gdb -t simple-example.exe [ARGS]”

Usage

mdb wrapper [OPTIONS] [ARGS]...

Options

-m, --my-rank <my_rank>

Required Rank of this debug process.

-h, --exchange-hostname <exchange_hostname>

Required Hostname where exchange server is running.

-p, --exchange-port <exchange_port>

Required Port address of exchange server.

-b, --backend <backend>

Required Debug backend e.g., gdb, lldb etc.

-t, --target <target>

Required Target binary to debug.

--redirect-stdout <redirect_stdout>

Redirect stdout from the target binary. If omitted, stdout will not be redirected.

--connection-attempts <connection_attempts>

Maximum number of failed connection attempts. A connection attempt is made once per second.

Default:

10

Arguments

ARGS

Optional argument(s)