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:

Default Custom Event Format – determine how to handle all custom events that don't have individual parsing rules.
Custom Events Format File – specify a file that contains parsing rules for individual custom event kinds (overriding the default format).

This topic focuses on the second option, and shows you how to use a XML format file to define parsing rules for one or more custom event kinds.

NOTE: In Tracealyzer, custom events generated by the Monitor utility are displayed as user events.

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 file:

Click Help > Event Definitions Sample. An Explorer window appears, with the Event Definitions Sample folder open to %RTX64SDKDIR3%\Tracealyzer\Event Definitions Sample\
Open the file CustomDefinitions.xml with a text editor 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 The kind parameter passed to the RtGenerateEvent call used to generate this event.
<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.
<Format>...</Format>	Required if neither BlobType nor Fields is present Specifies the string contents 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;
};

This will be presented as a user event in Tracealyzer, and will show up 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>

See the sample CustomDefinitions.xml file for additional examples.