Using RTX64 Monitor (RTX64 4.2 and Earlier)

NOTE: This content applies to RTX64 Monitor in RTX64 4.2 and earlier versions. For information on RTX64 Monitor in RTX64 4.3 and later, see Using RTX64 Monitor (RTX64 4.3 and Later).

Use RTX64 Monitor to dynamically start and stop monitoring, set session triggers for automatic monitoring, change the events being monitored from the defaults set in the Control Panel, and convert the session folders created by the Monitor Utility into human readable text files which show the details of each event in the order in which the events happened.

NOTE: Monitoring causes as much as one microsecond of latency depending on the real time operation. It is recommended that you only enable and start monitoring during development and that you disable monitoring in production. The amount of latency depends on how many kinds of events are being monitoring and how frequently those events occur in real-time applications. Monitoring fewer kinds of events reduces the impact of monitoring on latency.

NOTE: RTX64 collects additional monitoring session data to support collection of pre-start-trigger events.

Opening the RTX64 Monitor utility

Understanding Monitor Status

The RTX64 Subsystem has these monitoring states:

Disabled – The default state. The Subsystem has not been configured to monitor any events. This state is optimized for Subsystem performance and should be used when you deploy your real-time application. Transitioning from this state into an Enabled state introduces non-deterministic behavior.
Enabled – The Subsystem has enabled code paths that will allow for the collection of events. This state is optimized for event collection, not for Subsystem performance. As a result, this state performs with higher latencies than the Disabled state.
Started – Monitoring is actively collecting events. Monitoring must be Enabled before you can start a monitoring session.
Paused – An active monitoring session is currently paused.

The current monitoring status is displayed across all pages in the RTX64 Monitor dialog. Depending on the current state, you can do the following:

Disabled – Customize session events, manage triggers, and start a monitoring session. Starting a monitoring session from this state introduces non-determinism while monitoring is Enabled.
Enabled – Customize session events, manage triggers, and start a monitoring session. Monitoring is deterministic when started from this state.
Started – Customize the events that are being collected in the current session, manage triggers for the next session, and stop the current session.
Paused – Customize the events that are being collected in the current session, manage triggers for the next session, and resume the current session.

Monitor Settings

The Monitor utility dialog contains four pages:

Page	Description
Start a session	Manually start, pause, and stop a monitoring session.
Set session triggers	Use triggers to start collection automatically.
Customize event collection	Customize monitor events to collect.
Manage session logs	Convert a session log to a text file. You can also delete session logs from this page.

NOTE: The changes you make to the Monitor utility settings are lost when the Subsystem is stopped.

To Start/Pause/Stop a session:

You can manually start, pause, and stop monitoring sessions in the Start a session page.

To start a session, click Start. The Monitoring Status changes to Started and indicates the sub-folder name. Sub-folder names are of the form YYYYMMDD_HHMMSS_NNN, where NNN is an integer between 000 and the total number of monitoring sessions started within that second. Each time you start monitoring, a new session folder is created.

If you click Start while monitoring is currently disabled, you are warned "Enabling monitoring may cause some non-determinism." Select Yes or No. You can enable monitoring and set defaults for event collection in the Control Panel.

Once monitoring is running, all events selected for collection are captured in session data files. You can change event selection while a session is running through the Customize event collection page in the Monitor utility.

If you have configured triggers, a message appears on the Start a session page. Since monitoring starts automatically when triggers are enabled, you do not need to start monitoring manually.

You can pause event collection during the current session without creating a new session file. To pause a session, click Pause. To resume the session, click Start.
To manually stop a session, click Stop.

Set session triggers:

In the Set session triggers page you can associate monitor events with a trigger to start event collection automatically.

Select the check box(es) for the event(s) you want to associate with a trigger, or select the Monitoring Events check box to associate all events with a trigger.

To configure Custom Events, expand the Custom Events tree, and then:

To associate all custom events with triggers, click All Custom Events.
To associate specific custom events with triggers, click Select Custom Events. Then:
Click Add and enter the unique identifier for the custom event. This identifier corresponds to parameter kind in the API RtGenerateEvent, which is used to generate custom events. It must be within the range 0-999.
Select the check box for the custom event(s) you want to associate with a trigger.
To delete a custom event, select the event and then click Delete.

When you have finished selecting trigger events, click Set.

NOTE: A new session may start depending on the events selected.

IMPORTANT! Selected event triggers are automatically set when you close the RTX64 Monitor utility.

Page Behavior

The options available from the Set session triggers page depend on the current monitoring status.

NOTE: The following states assume the Subsystem is started. When the Subsystem is not started, the Set session triggers page is grayed out.

When monitoring is...	Set session triggers functionality is...
Disabled	Enabled. You can set session triggers.
Enabled	Enabled. You can set session triggers.
Started	Disabled (grayed out). Pause or stop the current session to set session triggers.
Paused	Enabled. You can set session triggers.
Stopped	Enabled. You can set session triggers.

Configuring Session Collection Behavior

You can change the maximum number of events to collect and determine whether you would like to collect pre-trigger events directly from the Set session triggers page. These settings override the default configurations set in the RTX64 Control Panel.

NOTE: These settings can only be changed when monitoring is paused or stopped.

Setting	Description	Action
Maximum number of events to collect	Configures the maximum number of events to collect in a monitor session.	Select a radio button: Unlimited – choose this option to collect events until the monitoring session is manually stopped. This is the default option. Only collect this many events – specify a value for the maximum number of events to collect during a monitor session. The default value is 20,000 events.
Number of pre-trigger events to collect	Configures the number of pre-trigger events, if any, to collect. Pre-trigger events are events that occur before the event type that triggers the start of a monitoring session. NOTE: This setting requires at least one session trigger to be set. It is grayed-out when none are set.	Specify a value for the number of pre-trigger events to collect during a monitor session. The default value is 0 events (no pre-trigger events collected). When set to a nonzero value, all monitoring events in excess of that value that occur before the trigger happens will not be saved. NOTE: When Maximum number of events to collect is set to Only collect this many events, the number of pre-trigger events to collect must not exceed it.

Setting

Description

Action

Maximum number of events to collect

Configures the maximum number of events to collect in a monitor session.

Select a radio button:

Unlimited – choose this option to collect events until the monitoring session is manually stopped. This is the default option.
Only collect this many events – specify a value for the maximum number of events to collect during a monitor session. The default value is 20,000 events.

Number of pre-trigger events to collect

Configures the number of pre-trigger events, if any, to collect. Pre-trigger events are events that occur before the event type that triggers the start of a monitoring session.

NOTE: This setting requires at least one session trigger to be set. It is grayed-out when none are set.

Specify a value for the number of pre-trigger events to collect during a monitor session. The default value is 0 events (no pre-trigger events collected).

When set to a nonzero value, all monitoring events in excess of that value that occur before the trigger happens will not be saved.

NOTE: When Maximum number of events to collect is set to Only collect this many events, the number of pre-trigger events to collect must not exceed it.

Customize event collection:

In the Customize event collection page, you can dynamically change which events you are monitoring by selecting/clearing check boxes for specific events. The events in the drop-down are identical to those listed in the Control Panel. Changes take place immediately and are in effect while the Subsystem is running and when Monitoring is enabled via the Control Panel.

To include network-related events, such as RT-TCP/IP Stack events, select the check box Include network events in next session. When selection of this check box is cleared, network-related events will not be collected.

NOTE: The changes you make to event collection in the Monitor utility do not affect the persistent settings in the Control Panel.

NOTE: If you have configured triggers, the associated events must be selected in the Customize event collection page for the events to be collected when triggered.

NOTE: Use the Monitoring events check box to select all or clear all events.

Manage session logs:

In the Manage session logs page, you can convert monitoring data from a monitor session file (.monx) to a readable log file (.txt). You can also delete older sessions that you no longer need.

NOTE: Converting data can take several moments if the session contains a large amount of data.

NOTE: You cannot convert a session file that is actively being updated. Attempts to do this will result in an error. To convert monitoring data from an active session, you must first stop monitoring.

Click Manage session logs.
In the Session file to convert field, specify the monitor session file (.monx) you want to convert. Click Browse to navigate for the session file.
Specify the path of the Output file (.txt). By default, the output file is the session folder in which the log selected for conversion resides. Click Browse to change the default location.
Click Convert.

The text file is automatically launched in your default text editor when the conversion is completed. Each text file is 500 MB and has the form YYYYMMDD_HHMMSS_xxx.N.txt, where N is an integer from 1 to the number of 500 MB text files required to contain the information in the original binary file.

If you start running low on space, you might need to manually delete session folders. To delete session folders:

Browse for the session folder you want to delete.

Subfolders use the naming convention YYYYMMDD_HHMMSS_NNN, where NNN is an integer between 000 and the total number of monitoring sessions for that second.

Click Delete.