ccdb Man Page

ccdb — Cray Comparative Debugger

SYNOPSIS

usage: ccdb [–tcp-socket] [–port PORT] [debug_program]

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

Starting in version 5.0 the Cray Comparative Debugger is a http server that presents a full debugging GUI in our browser. ccdb extends the interface of gdbgui https://www.gdbgui.com to use the multi-rank and comparative debugging capabilities of gdb4hpc. Beyond the normal debugger features, this allows the user to run two or more versions of the application side by side and detect when the results have changed.

Getting started

ccdb itself runs a web service on the target machine which you will typically access via an ssh tunnel. So if you are which to run myApp on machine from laptop, you could use these steps:

laptop% ssh machine
machine% cd <myApp working directory>
machine% module load cray-ccdb
machine% ccdb&
-- on a second terminal --
laptop% ssh -L 5000:/tmp/.../ccdb.sock machine

You can also set up the tunnel and run ccdb in a single ssh, but ssh will spam the terminal with messages once ccdb stops.

Then in your browser application, load the address http://localhost:5000. 5000 is the default port for the communication. You may choose a different number port when starting ccdb, say if you want to run more than one instance of ccdb.

This will present you with a debugging GUI ready to run an application. To launch a job, you can enter a gdb4hpc launch command in the text box next to “load binary”.

For example:

launch $App0{10} ./myApp --launcher-args="--exclusive" --args="10"

Help for launch, or any other gdb4hpc command is available via the gdb4hpc console in the lower left, just type help launch.

Currently, you are restricted to using $App0 for the launch handle name, and the {10} is the number of ranks to launch. –launcher-args and –args are the (optional) entries to pass argument to the launcher, e.g. srun, and your application respectively. The other common launch argument is –gpu to enable gpu debugging.

In the future, ccdb will be providing a launch panel to simplify this process.

Networking mode

By default, CCDB hosts its service on a temporary Unix socket file. This file can then be accessed either by SSH forwarding, or using socat to forward to a TCP port. CCDB will provide sample commands to run in both cases. You can also forego hosting on a Unix socket and start CCDB in TCP-only mode by starting with ccdb –tcp-socket.

In TCP mode, 5000 is the default communication port. You can use a different port using the –port option. This can be used to run multiple instances of ccdb. There is also some (small) chance that port 5000 may be use by another application. You aren’t opening the port to the outside world on either machine, all traffic is routed securely through ssh.

Comparative debugging

Handling multiple launches is a work in progress, these instructions are for the immediate term. Expect an easier workflow in new releases.

To launch a second application, open a second tab with the location localhost:5000. This will open another debugger gui view. Use the menu in the upper right (next to the gear icon) to go to the dashboard. Reconnect to your session, modify the launch line to use $App1 and launch. ccdb will launch the application in this window and display its source in the source panel. The applications, however, are still linked into a single session. You can control whether each operation refers to $App0, $App1, or both via the “pe sets” panel. The comparative debugging functionality is then available via the “compare” and “assertion scripts” panels.

Both operations compare data across the applications, but “compare” does it on demand, while assertions scripts do so automatically every time a program location is reached.