Debugging a Virtual Schema Adapter running on an Exasol cluster usually requires remote debugging. Because typically the debugger is not run directly on the cluster node itself and more importantly not inside the container in which the Virtual Schema Adapter runs.
Consequently you need to establish a network connection between the Java virtual machine that runs the adapter and the Java Debugger (jdb).
In this article you will learn how to:
- Start the Java debugger in "listen mode" on your machine
- Set up the Java VM to attach to a remote debugger
If you debug a Java application locally on your machine, the roles are clear: the Java VM is the "server" and the debugger user interface the "client".
In the diagram below you see such a regular "forward connection"
.-------------------------.
| Cluster node |
| .--------------------. | .--------------------.
| | UDF container | | | Developer machine |
| | .--------------. | | | .--------------. |
| | | Java VM | | | network | | JDB | |
| | | o<-o<-o<----------------| | |
| | | Debug server | | | connection | | Debug client | |
| | '--------------' | | | '--------------' |
| '--------------------' | '--------------------'
'--------------------------'
With remote debugging you can switch the roles — and that is in fact often the better choice.
If the debug server is on the side of the Virtual Schema, that means you need to get incoming network connections through to the node the cluster is running on and then into the container. Both are not trivial and often outside of a regular users control. Port forwarding for example requires administrator privileges.
If you turn the roles of client and server around, then the Java VM that runs the Virtual Schema creates an outgoing connection and that is in typical network scenarios a standard case.
.-------------------------.
| Cluster node |
| .--------------------. | .--------------------.
| | UDF container | | | Developer machine |
| | .--------------. | | | .--------------. |
| | | Java VM | | | network | | JDB | |
| | | |---------------------->o | |
| | | Debug client | | | connection | | Debug server | |
| | '--------------' | | | '--------------' |
| '--------------------' | '--------------------'
'--------------------------' listening on port
Given that the developer machine is reachable from the cluster node — which in integration tests environments often is the case — this setup is more robust.
This section explains how to start the user-facing part of the Java Debugger in listen-mode.
The following command starts the command line JDB in listen mode
jdb -listen 8000You are not limited to the command line JDB. All modern IDEs that include the Java Debugger have a means of configuring the debugger in listen mode. In this example we will use the debugger built into the Eclipse IDE.
- In the Menu click "Run"
- Click "Debug Configurations..."
- In dialog "Debug Configurations
- Select the entry "Remote Java Application"
- Click "New launch configuration" (white paper icon)
- In "Project" enter "virtual-schema-jdbc-adapter"
- In "Connection Type" select "Standard (Socket Listen)"
- In "Connection Properties" choose a port that is not in use on your machine (e.g. 8000)
- Check the box "Allow termination of remote VM"
You can see the filled out configuration dialog below.
In this section you will see how to set up the Virtual Schema so that you can run a remote debugger in parallel while executing the Virtual Schema Adapter.
Debug options need to be set when creating a virtual schema. Below you see an example of what you have to add compared to a regular virtual schema creation if you want remote debugging with a reverse connection.
CREATE OR REPLACE JAVA ADAPTER SCRIPT ADAPTER.ATHENA_ADAPTER AS
%jvmoption -agentlib:jdwp=transport=dt_socket,server=n,address=<host>:<port>,suspend=y;
-- ...
/The parameter jvmoption is passed down to the Java VM that runs the Virtual Schema.
Here's what the parts of those VM options mean:
| Parameter | Meaning |
|---|---|
agentlib:jdwp=transport=dt_socket |
Use the Java Debug Wire Protocol over a socket connection |
server=n |
Switches the VM side of the debugging chain to client mode |
address=<host>:<port> |
Host name or IP address and port of the debugger in listen mode |
suspend=y |
Establish the debug connection before running the program |
Once your debugger is listening and the adapter script configuration is properly set, you can start the actual debugging.
One of the most common mistakes when trying this out the first time is to forget setting a breakpoint. If you do this, then the Java VM inside the language container will connect to you debugger, but the adapter script will simply run through.
If you want to do real debugging, you need at least one breakpoint before you start.
Please refer to the documentation of your IDE or the Java debugger to learn how to set a breakpoint.
Earlier versions of Virtual Schema were based on Java 8. At that time you could set the environment variable JAVA_TOOL_OPTIONS to define the debugger options.
Recent releases use Java 11 and that variant does not work anymore. Use %jvmoptions instead.
If you want to work in a implement-debug cycle, make sure your debugger settings keep the debugger listening after the remote VM finished. Otherwise you will get a "VM crashed" error that is caused by the VM not being able to attach to the remote debugger because it is not listening.