18 Debugging Integration Processes
This chapter includes the following sections:
About Sessions and Blueprints
Oracle Data Integrator Studio provides a graphical debugger that allows you to manually step through the steps and tasks of a session. You can use the debugger to identify problems with mappings, procedures, packages, or scenarios. Debugging is performed in the blueprint of an active session.
The blueprint of a session can only be viewed in a tab of the session in Oracle Data Integrator Studio. You will see the same blueprint in different sessions if the mapping/scenario has the same version and timestamp.
Once you edit a mapping, new sessions run based on it will not use a previously cached blueprint: instead, a new blueprint is generated. Every time a mapping is executed, a new blueprint is generated afresh. Only in the case of scenarios do you retain the same blueprint for multiple runs as long as the scenario is not modified. Once the scenario is modified, then a new blueprint is generated for the subsequent sessions.
Blueprint Source and Target Code
The blueprint cannot be edited directly. However, you can edit the Source/Target code for the task that the debugger is currently on in the Session Editor. The edited code is used for all sessions run from a mapping. Even if you delete all of the sessions, the cached blueprint survives and will be reused when you next start a session from the unchanged mapping.
Introduction to Debugging in the Session Editor
In the blueprint in the Session Editor, you can debug a running session or restart a completed session, by manually stepping through the steps and tasks of the session. The blueprint includes a Steps Hierarchy table, which identifies steps and tasks by an ID. The debugger tasks that you can perform include:
-
Setting breakpoints for steps and tasks. Breakpoints are shown graphically in the blueprint, and listed in the Debug Breakpoints view.
-
Viewing and updating/editing source and target code for any task within the session, and running queries to view data.
-
Viewing the values of variables as well as uncommitted data, if the connection is not an Autocommit connection.
-
Viewing all active debug sessions, and disconnecting or connecting to debuggable sessions.
-
Viewing all threads for the connected session.
Icons
The debug execution can be controlled by the debug commands in the debug toolbar:
Icon | Command | Description |
---|---|---|
Add Breakpoint |
Toggles a breakpoint at the currently selected line in the blueprint, currently selected task in the procedure, or currently selected step in a package. |
|
Start Debug Session |
Starts a debugging session for the editor in focus. In a Session Editor, this command can be used to restart a session. |
|
Connect To Debug Session |
Connects to a debugging session running on an agent. This opens the currently running session and allow to step through the execution. It is not possible to connect to a local agent. |
|
Disconnect Debug Session |
Disconnects the current debugging session. After the debugging session is disconnected, the execution continues and any breakpoint is ignored. It is possible to reconnect to a disconnected session. It is not possible to disconnect from a session running on a local agent. |
|
Current Cursor |
Highlights the current cursor in the blueprint, and opens the Session Editor, if not already open. |
|
Get Data |
Inserts the SQL code of the currently selected task into the SQL command field of the Debug Data window. Both Source Task Data and Target Task Data windows are populated. |
|
Step into |
Steps to the beginning of the first child node of the currently selected node. If the currently selected node does not have a child, this is disabled. |
|
Run to Task End |
Runs to the end of the currently selected task. If the task has children, execute all children until the end of the task is reached. This is disabled if it is not at the beginning of a task. |
|
Run to Next Task |
Runs to the beginning of the next task. If at the last task in a list of tasks, go to the end of the parent task. |
|
Run to Step End |
Runs to the end of the current step. Executes all tasks until the end of the step is reached. |
|
Run to Next Step |
Runs to the beginning of the next step. |
|
Pause |
Suspends the current execution. The execution can be continued by stepping through the steps/tasks, or by resuming execution. |
|
Resume |
Resumes execution at the current cursor and continues until the session is finished or a breakpoint is reached. |
Differences between Debugging Packages, Mappings, and Procedures
There are differences in where you can set breakpoints when debugging packages, mappings, and procedures:
-
Breakpoints cannot be set on a mapping.
-
In a procedure, breakpoints can be set on tasks
-
In a package, you can set breakpoints on a step.
Starting a Debugging Session
You can start a debug session for an object by accessing a Debug command in the context menu or toolbar. Starting a debug session launches the Start Debug Session Dialog. See Debug Session Options.
Starting a Session from the Toolbar
To start a debug session from the toolbar in Oracle Data Integrator Studio:
-
In the Projects view, select a mapping, package, procedure, or scenario.
-
From the toolbar, select Start Debug Session.
-
In the Debug window, configure options described in Debug Session Options.
-
Click OK.
An information message indicates that the session is started.
Starting a Session from the Navigator Tree
To start a debug session from the navigator tree in Oracle Data Integrator Studio:
-
In the navigator tree, select a mapping, package, procedure, or scenario.
-
Right-click and select Debug.
-
In the Debug window, configure options described in Debug Session Options.
-
Click OK.
An information message indicates that the session has started.
Starting a Session from the Main Menu
To start a debug session from the main menu of Oracle Data Integrator Studio:
-
Select Run > Debug > Start Debug Session.
-
In the Debug window, configure options described in Debug Session Options.
-
Click OK.
An information message indicates that the session has started.
Starting a Session for a Scenario
To start a debug session for a scenario:
Connecting to a Running Debugging Session
You can connect the debugger to a debuggable session on an agent registered with the current repository. The session that the debugger connects to has to be a debuggable session and started prior to opening the Connect to Debug Session dialog box. It is not possible to connect to sessions running locally without an agent.
To connect to a session:
Stepping through a Blueprint in the Session Editor
The blueprint shows all of the steps and task hierarchy of the selected session, and allows you to go through individual commands.
When you start a session, the Session Editor in its Blueprint view opens, if the Associate to Current Client option has been selected. Otherwise, in the debug toolbar, select Current Cursor to open the Session Editor.
Steps and Tasks
Each row in a blueprint represents a step or task. Tasks in a blueprint can be container tasks, and can execute serially or in parallel. Tasks inside a container task are leaf nodes that get executed. Sessions based on mappings have only one step, while sessions based on packages can have multiple steps.
Using the Debugging Cursor
You can place the cursor before or after the execution of a line. The debugger highlights half a cursor position before or after the line.
Figure 18-1 shows a cursor position before the execution of a line:
Figure 18-1 Cursor Positioned Before a Step
Description of "Figure 18-1 Cursor Positioned Before a Step"
Using Breakpoints
You can set breakpoints on blueprint steps and tasks to suspend execution for debugging purposes.
Debugging Data
Use the Debug Data tab to query data in the context of the current debugger task.
The data window has two tabs, Source Task Data and Target Task Data, to query the data servers associated with the source and the target for the current task. The Get Data command in the main toolbar inserts the SQL code of the current task into both Source Task Data and Target Task Data fields. The window provides a field to enter a SQL command and execute it by clicking the Run SQL Code button.
SQL commands use the transaction context of the current session, uncommitted data can be queried. If there are multiple tasks at debug execution in the session, the commands use the context of the task synced to the data window.
Debugging Variables
Use the Debug Variables tab to view all the variables used in the current session, and see how a variable may change as you step through the steps and tasks. You can change the value of a variable to affect the execution of the session.
You can view the following information for each variable:
Properties | Description |
---|---|
Name |
Name of the variable. |
Value |
Value of the variable. Can be modified to change execution. |
Type |
Type of the variable. |
Managing Debugging Sessions
You can see a list of all active debug sessions in the Debug Session window by selecting Window > Debugger > Debug Sessions.
From the Debug Sessions window, you can connect or disconnect the listed sessions.
Properties | Description |
---|---|
Agent |
Agent executing the session. |
Session Number |
ID of the session. |
Session Name |
Name of the session. |
Session Connected |
Shows whether the session is connected or not connected to the debugger client. |
Restart Execution
In the session window, you can restart a stopped session.
To restart a session:
-
In the upper left of the session window, select Restart Execution.
The Restart Execution window appears.
-
To select the agent to execute the session, select one of the following options:
-
Use the Previous Agent: <agent name> to use the agent that was used to execute a previous session.
-
Choose another Agent: to select the agent that you want to use to execute the session. Select Internal to use the ODI Studio built-in agent.
-
-
Select the Log Level. Log level 6 has the same behavior as log level 5, but with the addition of variable and sequence tracking.
-
Click OK to restart the indicated session and to close the dialog.
You see an informational message, 'Session Launched', and the session is added to the Debug Sessions list.
To restart a failed session in debug mode: