Monitor model debugger

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Developing monitor models > Debugging monitor models
Monitor model debugger

The debugger that is included with the IBM Business Monitor development toolkit enables you to debug the runtime behavior of monitor models. For each inbound event definition or time-based trigger in the monitor model, the debugger shows the processing steps that occur when an inbound event is received or a time-based trigger fires. It also shows the processing steps that update KPIs and measures. Using the debugger, you can inspect the contents of inbound events as they are received, metrics, counters, stopwatches, and KPIs as they are created or updated, and outbound events as they are populated and emitted.
The following figure shows a monitor model in the Debug perspective. The Debug Source view in the lower part of the screen is a page in the Monitor Model editor. This arrangement enables you to switch to the Monitor Details Model page to view your model in a more familiar form and modify it as you find problems. You can then validate your fixes using the debugger without switching to a different perspective.

In the Debug perspective, there are seven areas that you can use in debugging, as labeled with numbers in the previous figure and described in the following table.

Number Name Description
1 Debug
This view shows the debug configuration, the server, and the monitoring context instance or instances, KPI context, or cube that is currently being updated. Nested monitoring contexts are shown in nesting order, with the current monitoring context at the top of the list and the parent and grandparent monitoring contexts under it.
Until you send an event, the monitor model is waiting to receive an inbound event and stepping is disabled. However, you can still explore the detailed steps for each element in the High-Level Steps list, as described in the following sections.
2 High-Level Steps in the Debug Source view
The High-Level Steps list shows all the inbound event definitions and time-based trigger definitions in the monitor model that you are debugging, grouped by monitoring context definition. It also shows all KPI context and cube definitions in the monitor model. Even before an event has been sent, you can open each monitoring context definition, click each step in the High-Level Steps list, and explore the processing details in the Detailed Steps list. In many cases, this exploration provides useful information about the logic of your monitor model and can help you identify problems early in the model development cycle.
The processing steps generated for inbound event definitions or time-based trigger definitions represent the effects of these model elements in a monitoring context (or KPI context). Inbound event definitions and time-based trigger definitions are listed because those are the elements that can initiate a sequence of steps in a running monitor model. The steps are executed when a matching event arrives, or when a time-based trigger fires. The steps generated for a KPI context contain steps to update the value for each KPI. These steps are processed after all monitoring context instances that are affected by the current event have been updated, so that any metric changes will be reflected in the new KPI value.
The steps generated for measures calculate the total aggregation of all underlying metrics, regardless of any dimensional filtering. While the High-Level Steps list shows a single step for the update of all KPIs defined in a KPI context, and all measures defined in a cube, the corresponding Detailed Step lists contain the steps for each individual KPI or measure.
In the production server, the time-based triggers are evaluated periodically at model-defined intervals. In the debugger, you control when they are evaluated.
The event definitions are shown and processed in the order in which they exist in the monitor model. Event definitions in a higher-level monitoring context come before those in lower-level monitoring contexts, and event definitions in the same monitoring context are displayed in XML document order.
It is important to realize that the processing happens sequentially and proceeds through each event definition. Processing starts with the filter condition for the first event definition, proceeds to the second event definition, and so on. Each incoming event is checked against all event definitions and is accepted for processing by zero or more of them. For each event definition that accepts the event, the processing steps in the Detailed Steps list occur.
3 Detailed Steps in the Debug Source view
The Detailed Steps list shows the processing steps for each inbound event definition, time-based trigger definition, KPI context definition, and cube definition. Click a step to see more detail if available, such as the filter condition of an inbound event definition or an expression that updates the value of a metric.
The first step for each inbound event definition is to see if the incoming event matches the filter condition, which is an expression that evaluates to true or false based on the contents of the event.
For example, to select events reporting incoming orders only if the order total is greater than $500, if the date falls within a certain period, or both, you would define a filter condition to test for those criteria.
If an incoming event does not meet the condition, it is processed by the next event definition in the High-Level Steps list.
If an event matches the filter condition, the correlation expression is evaluated next. The correlation expression tries to match the inbound event with one or more monitoring context instances. Depending on the number of matching instances found (none, one, or more than one) the action defined in the monitor model is carried out. Typical actions are to deliver the event to a matching instance or to create a new instance if none was found. If the event is not delivered to any new or existing instance, processing goes to the next event definition in the High-Level Steps list.
The rest of the detailed steps occur in the monitoring context, KPI context, or cube instance to which the event was delivered and show the effect on each metric, counter, KPI, measure, and so on. The steps generated for a KPI context (or cube) update the value for each KPI (or measure). They are processed after all monitoring context instances that are affected by the current event have been updated, so that any metric changes will be reflected in the new value for the KPI (or measure). To explore event processing one step at a time, you must set breakpoints on steps to suspend the processing of an event and then proceed in single-step mode from that point onwards.
4 Breakpoints
The Breakpoints view displays all of the breakpoints that are set. In this view, you can remove, disable, or enable individual breakpoints. You can also remove or skip all breakpoints.
Breakpoints that have been set for other executable files in your workspace, such as Java™ programs, are also visible in this view but have no effect while you are debugging a monitor model.
5 Instances
The Instances view shows all of the monitoring context instances (not just the active one) and the associated data. It provides a system-wide view of the values of all metrics, counters, stopwatches, and so on in the running monitor model.
The Instances view is active only after an event has been received and a context instance has been created. You cannot change the values in this view.
To refresh the Instances view to see the latest data, click Refresh
.
For more information about the Instances view, see "Viewing data while debugging."
6 Event Queues
The Event Queues view has three tabs.

The Input Queue tab shows the sequence of events that will be sent to the debugger after the current event has been processed. The input queue does not show the event that is currently being processed by the debugger (which can be seen in the Variables tab).
The Retry Queue tab shows the events that failed because evaluating the correlation expression for an inbound event returned no matching instances and the event delivery option for no correlation matches specifies "Retry." You can send events from the retry queue to the input queue to resubmit them. (You will typically resubmit events only after first processing other events that create or update some monitoring contexts, so that the event can be retried successfully.)
The Error Queue tab shows the events that failed because evaluating the correlation expression for an inbound event returned no matching instances, one matching instance, or multiple matching instances and the event delivery option for this outcome specified "Treat as error." The error queue also shows events that failed during processing for other reasons.

The number of events in each queue is shown on the tab next to the queue name.
To filter the events, type text into the filter text box.
To refresh the Event Queues view to see the latest events, click Refresh
.
To display the inbound event definition (or definitions) that each event matches, click Classify Events
.
You cannot change the values in this view. For more information about the Event Queues view, see "Working with event queues."
7 Variables
The Variables view shows the context data in scope while you are debugging. This context data includes the incoming event and the monitoring context instance or instances, KPI context, or cube that is currently being updated. As you step through your model in the debugger, the Variables view shows the values within that context. As you move to another context during your debugging session, the Variables view changes to reflect the new context.
The Variables view is active only when an inbound event is being processed. After an event arrives, you can inspect the content of the inbound event in the Variables view. You can also inspect outbound events as they are created and emitted from the debugger. You cannot change the values in this view.
For more information about the Variables view, see "Viewing data while debugging."

Toolbar icons

After an event arrives and its processing has been suspended at a breakpoint, you can perform an action by clicking the icons on the toolbar of the Debug view. These icons are described in the following table.

Icon Name Action
(F5)
Step Into Advance to the next step in the Detailed Steps sequence.
(F6)
Step Over Advance to the next step in the Detailed Steps sequence at the same level and process any substeps without stopping.
For example, if you are on the first processing step for an instance (after the correlation step), click this icon to continue with the next step. Any substeps (for example, steps dependent on a trigger) are processed without stopping.
(F7)
Step Return Advance to the next step at the parent level after processing any remaining steps at the current level without stopping.
For example, if you are on the first processing step for an instance (after the correlation step), click this icon to finish processing the sequence of steps for the current instance and stop at the first processing step for the next instance selected by correlation, or, if there are no more instances to process, stop at the first step for the next inbound event definition. As another example, if you are on the first processing step for an inbound event definition, click this icon to finish all processing for this inbound event definition and stop at the first processing step for the next inbound event definition.
(F8)
Resume Run to the next available breakpoint. If there is no breakpoint, the processing of the event (and any subsequent events in the input queue) runs to completion.

Use Step Filters Suspend the processing flow whenever the debugger reaches a correlation step.

Terminate End the debugging session. The Debug Source view closes, and you can switch back to the Business Monitoring perspective. The terminated session remains in the Debug view in the upper left. You can clean it up by clicking Remove All Terminated Launches
.

Remove All Terminated Launches Clean up the Debug view by removing all terminated debugging sessions.

To understand better what keys to press, it might be helpful to think about the steps in a tree structure, as in the following example (which does not contain KPIs or measures).
1.  InboundEventDefinition_1
1.1  |--------Evaluate filter condition
1.2  |--------Evaluate correlation expression
1.3  |--------(for all monitoring context instances receiving the event)
1.3.1    |------------- Reset stopwatch
1.3.2    |------------- Increment counter counterName
1.3.3    |------------- Update metric metricName
1.3.4    |------------- Evaluate trigger lowThreshold
1.3.4.1      |-------------- Assign values for outbound event lowThresholdAlert
1.3.4.2      |-------------- Emit outbound event lowThresholdAlert
2.  InboundEventDefinition_2
2.1  |--------Evaluate filter condition
2.2  |--------Evaluate correlation expression
2.3  |--------(for all monitoring context instances receiving the event)
2.3.1    |------------- Increment counter counterName
2.3.2    |------------- Update metric metricName
3.  TimeBasedTrigger_1
3.1  |-------Evaluate filter condition
3.2  |-------Evaluate correlation expression
3.3  |-------(for all monitoring context instances receiving the event)
3.3.1    |------------ Evaluate trigger refreshAlert
3.3.1.1      |------------ Assign values for outbound event refreshAlert
3.3.1.2      |------------ Emit outbound event refreshAlert 
The numbers in the following table are based on the tree structure in this example and show the processing sequence that results when you use Step Into, Step Over, and Step Return, starting from various points in the overall sequence of steps.

Step Into (F5)

Step Over (F6)

Step Return (F7)

Advance to the next step. Advance to the next step in the sequence at the same level, and process any substeps without stopping. Advance to the next step at the parent level, after processing any remaining steps at the current level without stopping.

1.1 > 1.2 > 1.3.1 > 1.3.2 > 1.3.3 > 1.3.4 > 1.3.4.1 > 1.3.4.2 > 2.1 (or 1.3.1 if there is another instance to be processed in the sequence)

1.1 > 1.2 > 1.3.1 > 1.3.2 > 1.3.3 > 1.3.4 > 2.1 (or 1.3.1 if there is another instance to be processed in the sequence)

1.1 > 2.1 > 3.1
Another example: 1.3.3 > 2.1 (or 1.3.1 if there is another instance to be processed in the sequence)

Debugging monitor models

Number	Name	Description
1	Debug	This view shows the debug configuration, the server, and the monitoring context instance or instances, KPI context, or cube that is currently being updated. Nested monitoring contexts are shown in nesting order, with the current monitoring context at the top of the list and the parent and grandparent monitoring contexts under it. Until you send an event, the monitor model is waiting to receive an inbound event and stepping is disabled. However, you can still explore the detailed steps for each element in the High-Level Steps list, as described in the following sections.
2	High-Level Steps in the Debug Source view	The High-Level Steps list shows all the inbound event definitions and time-based trigger definitions in the monitor model that you are debugging, grouped by monitoring context definition. It also shows all KPI context and cube definitions in the monitor model. Even before an event has been sent, you can open each monitoring context definition, click each step in the High-Level Steps list, and explore the processing details in the Detailed Steps list. In many cases, this exploration provides useful information about the logic of your monitor model and can help you identify problems early in the model development cycle. The processing steps generated for inbound event definitions or time-based trigger definitions represent the effects of these model elements in a monitoring context (or KPI context). Inbound event definitions and time-based trigger definitions are listed because those are the elements that can initiate a sequence of steps in a running monitor model. The steps are executed when a matching event arrives, or when a time-based trigger fires. The steps generated for a KPI context contain steps to update the value for each KPI. These steps are processed after all monitoring context instances that are affected by the current event have been updated, so that any metric changes will be reflected in the new KPI value. The steps generated for measures calculate the total aggregation of all underlying metrics, regardless of any dimensional filtering. While the High-Level Steps list shows a single step for the update of all KPIs defined in a KPI context, and all measures defined in a cube, the corresponding Detailed Step lists contain the steps for each individual KPI or measure. In the production server, the time-based triggers are evaluated periodically at model-defined intervals. In the debugger, you control when they are evaluated. The event definitions are shown and processed in the order in which they exist in the monitor model. Event definitions in a higher-level monitoring context come before those in lower-level monitoring contexts, and event definitions in the same monitoring context are displayed in XML document order. It is important to realize that the processing happens sequentially and proceeds through each event definition. Processing starts with the filter condition for the first event definition, proceeds to the second event definition, and so on. Each incoming event is checked against all event definitions and is accepted for processing by zero or more of them. For each event definition that accepts the event, the processing steps in the Detailed Steps list occur.
3	Detailed Steps in the Debug Source view	The Detailed Steps list shows the processing steps for each inbound event definition, time-based trigger definition, KPI context definition, and cube definition. Click a step to see more detail if available, such as the filter condition of an inbound event definition or an expression that updates the value of a metric. The first step for each inbound event definition is to see if the incoming event matches the filter condition, which is an expression that evaluates to true or false based on the contents of the event. For example, to select events reporting incoming orders only if the order total is greater than $500, if the date falls within a certain period, or both, you would define a filter condition to test for those criteria. If an incoming event does not meet the condition, it is processed by the next event definition in the High-Level Steps list. If an event matches the filter condition, the correlation expression is evaluated next. The correlation expression tries to match the inbound event with one or more monitoring context instances. Depending on the number of matching instances found (none, one, or more than one) the action defined in the monitor model is carried out. Typical actions are to deliver the event to a matching instance or to create a new instance if none was found. If the event is not delivered to any new or existing instance, processing goes to the next event definition in the High-Level Steps list. The rest of the detailed steps occur in the monitoring context, KPI context, or cube instance to which the event was delivered and show the effect on each metric, counter, KPI, measure, and so on. The steps generated for a KPI context (or cube) update the value for each KPI (or measure). They are processed after all monitoring context instances that are affected by the current event have been updated, so that any metric changes will be reflected in the new value for the KPI (or measure). To explore event processing one step at a time, you must set breakpoints on steps to suspend the processing of an event and then proceed in single-step mode from that point onwards.
4	Breakpoints	The Breakpoints view displays all of the breakpoints that are set. In this view, you can remove, disable, or enable individual breakpoints. You can also remove or skip all breakpoints. Breakpoints that have been set for other executable files in your workspace, such as Java™ programs, are also visible in this view but have no effect while you are debugging a monitor model.
5	Instances	The Instances view shows all of the monitoring context instances (not just the active one) and the associated data. It provides a system-wide view of the values of all metrics, counters, stopwatches, and so on in the running monitor model. The Instances view is active only after an event has been received and a context instance has been created. You cannot change the values in this view. To refresh the Instances view to see the latest data, click Refresh . For more information about the Instances view, see "Viewing data while debugging."
6	Event Queues	The Event Queues view has three tabs. The Input Queue tab shows the sequence of events that will be sent to the debugger after the current event has been processed. The input queue does not show the event that is currently being processed by the debugger (which can be seen in the Variables tab). The Retry Queue tab shows the events that failed because evaluating the correlation expression for an inbound event returned no matching instances and the event delivery option for no correlation matches specifies "Retry." You can send events from the retry queue to the input queue to resubmit them. (You will typically resubmit events only after first processing other events that create or update some monitoring contexts, so that the event can be retried successfully.) The Error Queue tab shows the events that failed because evaluating the correlation expression for an inbound event returned no matching instances, one matching instance, or multiple matching instances and the event delivery option for this outcome specified "Treat as error." The error queue also shows events that failed during processing for other reasons. The number of events in each queue is shown on the tab next to the queue name. To filter the events, type text into the filter text box. To refresh the Event Queues view to see the latest events, click Refresh . To display the inbound event definition (or definitions) that each event matches, click Classify Events . You cannot change the values in this view. For more information about the Event Queues view, see "Working with event queues."
7	Variables	The Variables view shows the context data in scope while you are debugging. This context data includes the incoming event and the monitoring context instance or instances, KPI context, or cube that is currently being updated. As you step through your model in the debugger, the Variables view shows the values within that context. As you move to another context during your debugging session, the Variables view changes to reflect the new context. The Variables view is active only when an inbound event is being processed. After an event arrives, you can inspect the content of the inbound event in the Variables view. You can also inspect outbound events as they are created and emitted from the debugger. You cannot change the values in this view. For more information about the Variables view, see "Viewing data while debugging."

Icon	Name	Action
(F5)	Step Into	Advance to the next step in the Detailed Steps sequence.
(F6)	Step Over	Advance to the next step in the Detailed Steps sequence at the same level and process any substeps without stopping. For example, if you are on the first processing step for an instance (after the correlation step), click this icon to continue with the next step. Any substeps (for example, steps dependent on a trigger) are processed without stopping.
(F7)	Step Return	Advance to the next step at the parent level after processing any remaining steps at the current level without stopping. For example, if you are on the first processing step for an instance (after the correlation step), click this icon to finish processing the sequence of steps for the current instance and stop at the first processing step for the next instance selected by correlation, or, if there are no more instances to process, stop at the first step for the next inbound event definition. As another example, if you are on the first processing step for an inbound event definition, click this icon to finish all processing for this inbound event definition and stop at the first processing step for the next inbound event definition.
(F8)	Resume	Run to the next available breakpoint. If there is no breakpoint, the processing of the event (and any subsequent events in the input queue) runs to completion.
	Use Step Filters	Suspend the processing flow whenever the debugger reaches a correlation step.
	Terminate	End the debugging session. The Debug Source view closes, and you can switch back to the Business Monitoring perspective. The terminated session remains in the Debug view in the upper left. You can clean it up by clicking Remove All Terminated Launches .
	Remove All Terminated Launches	Clean up the Debug view by removing all terminated debugging sessions.