Analyzing Debug Output

Output from debugpoints is stored in the Java Profiler Heap Dump version 1.0.2 format.

Every time a debugpoint is hit during execution, the debug information is saved as a heap dump segment. Once execution finishes, you have two options to analyze the debug output:
  • Use the textual representation of the debug information obtained via the dbms_mle.parse_debug_output function.

  • Export the BLOB sink containing the debug output to an hprof file and use any of a number of existing developer tools to analyze the information.

Topics

Textual Representation of Debug Output

The function dbms_mle.parse_debug_output takes as input a BLOB containing the debug information in the heap dump format and returns a JSON representation of the debug information.

The output of dbms_mle.parse_debug_output is an array of DebugPointData objects. DebugPointData represents the debug information logged every time a debugpoint is hit and comprises of an array of Frame objects. Each Frame includes the location in source code where the information was collected (the at field) and the names and values of local variables logged at that location (the values field). Note that the keys of Frame.values are the names of the variables logged and the values are the values of those variables.

Example 9-6 demonstrates how you can specify a debugpoint in a sample JavaScript program and then use the function dbms_mle.parse_debug_output to produce a textual representation of the debug output.

Example 9-6 Obtain Textual Representation of Debug Output

The debugging shown later in this example is performed on the JavaScript function fib defined in the module fibunacci_module:

CREATE OR REPLACE MLE MODULE fibunacci_module 
LANGUAGE JAVASCRIPT AS
export function fib( n ) {

    if (n < 0) {
        throw Error("must provide a positive number to fib()");
    }
    if (n < 2) {
        return n;
    } else {
        return fib(n-1) + fib(n-2);
    }
}
/

CREATE OR REPLACE FUNCTION fib( p_value number)
RETURN NUMBER
AS MLE MODULE fibunacci_module
SIGNATURE 'fib(number)';
/

A debugpoint is placed at line 9 and then the DBMS_MLE.PARSE_DEBUG_OUTPUT function is used to view the debug information:

SET SERVEROUTPUT ON;
DECLARE
    l_debugspec JSON;
    l_debugsink BLOB;
    l_debuginfo JSON;
    l_value     NUMBER;
BEGIN
    l_debugspec := JSON ('
    {
        version : "1.0",
        debugpoints : [
            {
                "at" : {
                    "name" : "FIBUNACCI_MODULE",
                    "line" : 9
                },
                "actions" : [
                    { "type" : "watch", "id" : "n" }
                ],
            },
        ]
    }
    ');
    -- create a temporary lob to store the raw 
    -- debug output
    DBMS_LOB.CREATETEMPORARY( l_debugsink, false );

    DBMS_MLE.ENABLE_DEBUGGING( l_debugspec, l_debugsink );

    -- run the application code    
    l_value := fib(4);

    DBMS_MLE.DISABLE_DEBUGGING;

    -- retrieve a textual representation of the debug
    -- output
    l_debuginfo := DBMS_MLE.PARSE_DEBUG_OUTPUT( l_debugsink );
    DBMS_OUTPUT.PUT_LINE(
        json_serialize(l_debuginfo pretty)
    );
END;
/

Result:

[
  [
    {
      "at": {
        "name": "USER1.FIBUNACCI_MODULE",
        "line": 9
      },
      "values": {
        "n": 4
      }
    }
  ],
  [
    {
      "at": {
        "name": "USER1.FIBUNACCI_MODULE",
        "line": 9
      },
      "values": {
        "n": 3
      }
    }
  ],
  [
    {
      "at": {
        "name": "USER1.FIBUNACCI_MODULE",
        "line": 9
      },
      "values": {
        "n": 2
      }
    }
  ],
  [
    {
      "at": {
        "name": "USER1.FIBUNACCI_MODULE",
        "line": 9
      },
      "values": {
        "n": 2
      }
    }
  ]
]

Analyzing Debug Output Using Developer Tools

As an alternative to analyzing the textual representation of debug output, you also have the option to utilize tools such as JDeveloper, NetBeans, and Oracle Database Actions.

Once execution has finished, you can use the tool of your choice to inspect the values of local variables or to inspect the graph of variables at each point in time.

Integration with new tools can be developed as needed (e.g., Chrome Dev Tools) and UIs can be designed that are tailored specifically to the MLE use case.

Note:

Oracle Database Actions supports MLE post-execution debugging starting with Oracle Database 23ai, Release Update 23.1.2.

See Also:

Using Oracle SQL Developer Web for more information about using Database Actions with MLE