Using debuggers and other tools

These sections describe a general, non-language specific introduction to using a debugger or other diagnostic tool on an AE process.

Running on the Host

As a general rule, you should perform debugging on the host. Therefore, the AEs and requests must be running on the host. There are two techniques for getting requests to run on the host:

  • For scalar, table, and aggregate functions, the SQL function receives all literal arguments. 
    SELECT applyOperationV1Sf('+', 1, 2, 3);
SELECT * FROM TABLE WITH FINAL(applyOperationV1Tf('+', 1, 2, 3));
  • For a table function only, register the AE with the option --noparallel.

This option causes the AE to run on the host so that it can receive data arguments from normal tables as well as literals. The option --noparallel cannot be used with scalar functions. However, the table functions and scalar functions use the same AE API, so a scalar function AE can easily be called from an SQL table function for debugging purposes (because a table function has a superset of scalar function capabilities). To do so, register the AE written as a scalar function as a table function. Most table function AEs cannot be registered as scalar functions unless they return exactly one output row for every input row and have exactly one column in a row.

Two Debugger Methods

There are two general approaches when using a diagnostic/debugger tool on an AE process.

  • Attach to an already running process.
  • Have the AE runtime run the diagnostic/debugger tool that then loads the AE.

With the attach approach, you must supply the AE process ID, and the process must wait for the tool to be attached.

Local AE and Spin Files

For a local AE, a spin file mechanism is available. When activated, the AE runtime looks for the file specified by the AE ENV variable. If the file exists, the AE runtime sleeps for a while and then checks again for file existence. The AE runtime also prints information about the process to the standard error log file. Looping continues until the file is renamed or deleted.

Example

spinning in process id=15796, thread id=15797 on file /tmp/spin_ae.on

Once the tool is attached, you delete or rename the file. Then the AE resumes normal execution.

Example

mv /tmp/spin_ae.on /tmp/spin_ae.off

The spin file mechanism is turned on using an AE environment variable.

--environment "'NZAE_HOST_ONLY_NZAE_SPIN_FILE_NAME'='/tmp/spin_ae.on'"

Note how the NZAE_HOST_ONLY_ prefix is used to prevent accidental use of the spin file mechanism on the SPUs.

Remote AE

Because a remote AE is usually a long running process, attaching a tool like GDB is usually much easier. Use the nzaejobcontrol function to ping the remote AE for get process ID and other information needed by the debugger.