Defining Parsing Rules for Custom Events in Tracealyzer

Custom monitoring events—shown as user events in Tracealyzer—are generated by the function RtGenerateEvent. The Settings menu in Tracealyzer contains options that allow you to define how custom events are displayed:

This topic focuses on the second option and shows you how to use an XML format file to define parsing rules for one or more custom event kinds. If you want to display raw data in custom event, you will need to use an XML format file to parse the binary names from that data. You would then use the Signal Setup dialog, available under View > Signal Setup in the User Event Signal Plot (Advanced) view, to create signals for plotting user events data.

To use a custom XML format file:

  1. Click File > Settings. The Settings dialog appears.
  2. Click RTX64 Settings.
  3. Under Custom Events, click Browse and browse for the XML event definitions file you want to use.
  4. Click OK.

NOTE: If you load a custom XML file while a monitoring session is open in Tracealyzer, you must either reload the session or restart Tracealyzer for the custom XML to take effect.

Sample XML Format File

Tracealyzer provides a sample XML format file that includes various examples of parsing rules. You can use this sample as a reference when you create your own XML format file.

To open the Sample file:

  1. Open Explorer and navigate to %RTX64SDKDIR4%\Tracealyzer\Event Definitions Sample\
  2. Open the file CustomDefinitions.xml with a text or XML editor.

Understanding the XML Format File

The XML format file supports the following tags:

Elements Description Example
<EventDefinitions>...</EventDefinitions>

Required

The root element containing one or more event elements.

<Event>...</Event>

Required

One or more event elements corresponding to custom event kinds passed to RtGenerateEvent.

<Code>...</Code>

Required

Specifies which custom event kind (0 – 999, inclusive) the <Event> element applies to.

<Channel>...</Channel>

Required

An arbitrary string to display in the event's label in Tracealyzer. This string appears in the user event in the Trace View.

More than one channel name can be defined in the XML file.

The <Channel> string can be different for each custom event kind specified in the <Code> element, which makes it easier to write a regular expression that matches exactly one custom event kind.

<Format>...</Format>

 Required if neither BlobType nor Fields is present
Specifies the string representation of the event. .NET Composite Formatting syntax can be used in this string to insert the string representation of fields defined by <Field> elements (below).

<BlobType>...</BlobType>

Required if neither Format nor Fields is present
Displays the data block as a string or a single hex- formatted block of data.

See BlobType Values below.

<Fields>...</Fields>

Required if neither Format nor BlobType is present

Specifies a list of fields in the data block. This is useful when you pass a C struct to RtGenerateEvent. This tag should contain one or more <Field> tags.

<Field>...</Field>

 Specifies one field in the data to be interpreted as a specific type.

<Type>...</Type>

Required
The data type of the field.

See Field Type Values below.

<Offset>...</Offset>

 Required
The offset in bytes from the start of the data block to this field. It's up to the user to account for any compiler generated table pointers and alignment padding.

<Name>...</Name>

Optional

The name of this field. Specifying a name will make it easier to reference in the event <Format> tag (otherwise the field index can be used) and will result in a nicer format if the <Format> tag of the Event is omitted.

This syntax is identical to .NET Composite Formatting as used in String.Format and Console.WriteLine.

For more information, see the MSDN article at https://msdn.microsoft.com/en-us/library/txafckwd(v=vs.110).aspx

<Size>...</Size>

 Required if Type is blob
The size in bytes of this field.

<BlobType>...</BlobType>

Required if Type is blob
This is used to treat the field data as a string or a single hex formatted block of data.

See BlobType Values below.

BlobType Values

BlobType can be used in the <Event> and <Field> tags. This table lists the valid options for BlobType.

Option Description
hex Display the block as binary data and format using hex.
ansi Display the block as a null terminated ANSI string.
unicode Display the block as a null terminated Unicode string.
utf8 Display the block as a null terminated UTF-8 string.

Field Type Values

This table lists all valid values for the Type member of the Field.

Value Description
byte, u8, uint8_t A single 8-bit unsigned integer, also known as a byte.
u16, uint16_t A 16-bit unsigned integer.
u32, uint32_t A 32-bit unsigned integer.
u64, uint64_t A 64-bit unsigned integer.
i16, int16_t A 16-bit signed integer.
i32, int32_t A 32-bit signed integer.
i64, int64_t A 64-bit signed integer.
float, float32, f32, single A 32-bit floating point value.
double, float64, f64 A 64-bit floating point value.
blob A byte array, size defined by Size tag, display method defined by BlobType tag.

Example

The following example shows how to create XML to display data in a C struct in a custom user event in Tracealyzer: 

<!--
This event contains a point. The C struct may look something like this:
 
struct Point
{
float x, y;
};
 
Using the XML definitions below, the data will be displayed in Tracealyzer as something like:
[Points] (4.52 ; 3.23)
 
The Format string can contain references to fields, as well as .NET format specifiers.
-->
<Event>
  <Code>1001</Code>
  <Channel>Points</Channel>
  <Format>({x:0.00} ; {y:0.00})</Format>
  <Fields>
     <Field>
        <Type>float</Type>
	 <Offset>0</Offset>
	 <Name>x</Name>
     </Field>
     <Field>
	 <Type>float</Type>
	 <Offset>4</Offset>
	 <Name>y</Name>
     </Field>
  </Fields>
</Event>

 

Related Topics ABOUT TRACEALYZER:

rELATED tOPICS ABOUT MONITORING: