RSSL XML Trace Data Converter Tool

The utility is a console application which was designed for decoding and converting XML Fragments from the RSSL Tracing log generated by RFA C++/.NET and EMA/ETA C/C++. It can convert a Hex string inside the field entry to the actual value according to data dictionary (RDMFieldDictionary and enumtype.def). Please note that RSSL Tracing log and the utility was provided for troubleshooting purpose only.

Prerequisites

Required software components:

.NET-.NET 8.0 or later version

Visual Studio 2022- We use Visual Studio 2022 to develop and build the application on Windows.

Optional software components:

Visual Studio Code - IDE for .NET Core development on Windows and macOS.

Other IDE's such as Rider - IDE From Jetbrain for .NET Core projects on macOS.

Getting Started

The application was implemented using .NET standard library and .NET 8.0 so that user can rebuild or republish the application on .NET supported platforms such as Windows, Linux, and Mac OS. Please find more details about the build and publish command from MSDN.

The console application requires RDMFieldDictionary and enumtype.def to decode the raw data in a Hex string format to the actual value. The user can update the data dictionary in the folder "Dict" to the latest version. In case that the application unable to find field definition of the fid or enum value, it will instead write original Hex string in the tracing log. Note that you can download the latest version of data dictionary from the Software Download page.

Overview

The utility is console application which was designed for decoding and converting XML Fragments inside RSSL Tracing log generated by RFA C++/.NET and EMA/ETA C/C++. It can decode Hex string inside fieldEntry XML element to the actual value according to data dictionary from RDMFieldDictionary and enumtype.def. The utility is command line base console application which was developed by using .NET Core Framework so that user can build and run the console application on Windows, Linux and Mac OS according to information from .NET support platforms.

Typically, when the user using RFA or EMA application requesting data for Market Price and Level 2 Market By Price or Market by Order, the response message usually contains a field entry with a field value in Hex string format. The utility can be used to read the XML fragment inside the XML file and then converting the Hex string in the field entry to actual data according to the data type from the data dictionary. Moreover, it can be used to decode the new MRN Real-Time News which is the data from RIC MRN_STORY. The utility also has application's logic to scan XML fragments and consolidate a series of MRN compressed data and then unpack the compressed buffer to a raw JSON data. Then it will write decoded data along with MRN JSON data to a new XML file. The user can open the new XML file with an XML editor to search data. The utility should be able to help a developer to investigate a data relate issue or verify the actual data API sent or receive from a Provider server.

How to collect RSSL Tracing log

The RSSL tracing log was provided for troubleshooting purpose and it's not turn on by default. A user may use the following instruction to turn on the log in RFA C++/.NET and EMA C++ application. Please note that currently, this utility does not support the trace from RFA and EMA java because it can't provide a valid XML trace format. There are some garbage or unexpected text inside the XML fragment and there are mixing between simple logger message and XML data inside the trace so that it causes the XML parsing error. If you want to use the trace log from EMA java with the application, the workaround is to manually remove invalid text or string from XML fragment and save it to a valid XML file.

RFA C++ and .NET application

A user has to add the following configuration to turn on RSSL tracing log. is a connection name which the user is using in the configuration file.

Note that traceMsgFileName is an output of the XML file used by RFA to generate the log. From the example provided above, the output will be RSSLConsumerTrace_.xml where is the process id of the application.

EMA C++ application

For EMA C++ application, to turn on the RSSL Trace log, a user has to copy EmaConfig.xml which provided in EMA Examples folder to project directory or running directory and then add below XML element to EMA configuration file under section Consumer. Note that you have to set XmlTraceToFile to 1 to turn on the log and set it to 0 to turn off the log.

There are applications that setting server name/IP address and the RSSL port from application code and they might need to turn on the RSSL tracing log. This can be achieved by copying the EMA configuration file to running directly.

Though you are not using the Channel config from the configuration file, you can also copy the configuration file to the running directory and set the config under DefaultConsumer or DefaultProvider section.

From the above sample, we set DefaultConsumer to "Consumer_1" then EMA will check the value inside the configuration file and then verify option to turn on trace file from Consumer1. EMA will generate the RSSL Tracing log file name EmaTrace.xml under the running directory.

Utility download

The project and README are available for Download from GitHub.

Running the Utility

To run the utility from the command line, a user can run "dotnet build" and "dotnet run" command to build and run the application. An alternative option is using "dotnet publish" command to create a native executable file and then run the executable file directly.

Launching the tool from the console:

Start a command prompt and change the folder to "\Example.EMARFACPP.Tool.RSSLTraceViewer\rsslxmltracedataconverter", you should see rsslxmltracedataconverter.csproj in the folder. Then run the following command

To build the project then just type dotnet run to run the application. It will automatically compile and build the project and run the application. It shows the following console output after running dotnet run.

Command-line Options

From the previous section, to run the utility, it requires command line argument "-s" following by name or path to RSSL Trace file you want to convert. You can also specify the name of XML output by using -o following by output file name. If the user does not set the output file name, the application will set it to "output.xml" instead. There are "-r" and "-e" that is an optional command line argument to specify a path to your own data dictionary. By default, it will read the dictionary from folder "\Dict". Please make sure that you have folder "Dict" in your running directory.

The following sample is output after running the application with the RSSL Tracing log.

And below outputs is a sample of RSSL trace messages for original message and decoded data from MRN Real-Time News RIC, the utility will write MRN JSON data in the XML comment tag.

Original XML Fragment.

Decoded data inside fieldEntry element containing additional attributes in the fieldEntry that are fieldName and decodedData. For the updateMsg type for domainType RSSL_DMT_NEWS_TEXT_ANALYTICS, it has additional XML comments after the last MRN fragment containing the same GUID.

Note that there is command line option "--verbose" which can print JSON output to console while the utility processing the data.

In addition to using the utility to decode MRN data, as described in the overview section, the application can be used to decoded data for the Level 2 Market Price data and below is a sample output for the Market By Order domain when using the utility convert the data.

Launching the tool from the executable file

There is an option for .NET Core application to publish the project to the native executable file and then you can run executable file directly without using dotnet command on windows, mac os, and Linux. You can refer to MSDN Document for dotnet command line option to publish the project.

To generate a native executable file on Windows, you can run

You should see the following output when executing dotnet publish command.

After executing the command, you can find a native executable file named "rsslxmltracedataconverter.exe", it should be located under the folder "\bin\release\netcoreapp2.1\win-x64" and then you can copy or share the folder in order to run the utility on other Windows.

To use the utility then you can just executing the following command.

For macOS and Linux you can just change the Runtime Identifier from win-x64 to osx-x64 and linux-x64 according to the list from the rid-catalog page.

Then you can run the utility from a publishing folder by executing the command

Just like executing another native application on macOS or Linux.