Debugging

The goal of debugging is to get rid of errors in the code inside your workflow, i.e. transformer code.

To debug your transformer code, you can use either print statements, or a debugging session with breakpoints.

Debugging with print statements

This the easiest form of debugging: add print statements (or echo/cat/cout/printf/…) to your transformer code.

For Python transformers, the transformation is aborted if an exception is raised. Transformer.exception will then contain the exception traceback, stdout and stderr. If no exception is raised, stdout and stderr can be retrieved using Transformer.logs

For bash/Docker transformers, if any launched process returns with a non-zero error code, the transformation is aborted. Transformer.exception will then contain the bash error message, stdout and stderr. If there is no non-zero error code, stdout and stderr can be retrieved using Transformer.logs.

For compiled transformers (i.e. written in C/C++/Fortran/…), you must not do exit(...) with a non-zero exit code: this kills the transformation process immediately, including the machinery to capture stdout and stderr. Instead, make the main int transform(...) function return a non-zero value.

Seamless transformations can be executed anywhere. Therefore, by default, they do not print their stdout or stderr to any terminal while they execute. stdout and stderr are only captured when the transformation has finished. You can overrule this behavior with Transformer.debug.direct_print = True. This will force local evaluation (transformation jobs will not be forwarded to e.g. jobless), and the result of print statements are printed directly to stdout/stderr, or to a file specified in Transformer.debug.direct_print_file. See this test for a demonstration.

Relevant test examples:

• simpler-tf-print.py

• bash-debug.py

• docker-debug.py

See Running tests on how to execute tests.

Debugging sessions

Debugging sessions with breakpoints are directly supported, but only in Visual Studio Code. Other IDEs are currently not supported, but they should be in the future. If you are willing to help, see this GitHub issue.

Debugging sessions with Seamless is best learned by running some of the Seamless tests below. Open a terminal within Visual Studio Code. Start a Seamless container with seamless-bash, the do cd ~/seamless-tests/highlevel, and run any test with ipython -i (any test) or python (any test that doesn’t end with “-shell.py”). Follow the instructions printed on screen.

NOTE: seamless-bash is needed because its exposes ports 5679-5785 for use by debugpy. If you get a “connection refused” error in Visual Studio Code, you probably used seamless-bash-safe instead.

Debug mode: light or sandbox

IMPORTANT: This documentation section is a stub. (shells can be opened only in sandbox mode. Not for compiled transformers)

Debugging Python transformers

IMPORTANT: This documentation section is a stub.

Relevant test examples:

• debugmode-py-light.py

• debugmode-py-sandbox.py

• debugmode-py-shell.py

Debugging bash transformers

IMPORTANT: This documentation section is a stub.

Relevant test examples:

• debugmode-bash-shell.py

• debugmode-docker-shell.py

Debugging compiled transformers

IMPORTANT: This documentation section is a stub.

Relevant test examples:

• debugmode-compiled-light.py

• debugmode-compiled-sandbox.py

Debugging modules

See the modules documentation for more information about modules.

IMPORTANT: This documentation section is a stub.

Debugging Python modules

Relevant test examples:

• debugmode-pymodule-light.py

• debugmode-pymodule-sandbox.py

• debugmode-pypackage-light.py

Debugging compiled modules

Relevant test examples:

• debugmode-compiledmodule-light.py

• debugmode-compiledmodule-sandbox.py