How to Use ULogger with Comms

This tutorial summarizes one approach for enabling, retrieving and post-processing the ULogger logs for Comms. ULogger is part of the Unified Trace framework which replaces other logging mechanisms for Symbian platform including Flogger and CDU.

The Unified Trace framework has greater flexibility and speed compared to Flogger and CDU.

Introduction

The Comms logging which has been migrated to ULogger is as follows:

Comms Framework Node messages - creation and destruction of Nodes and messages between Nodes.
Mesh Machine messages
data to support the SVG generation

This logging replaces some of what was logged through the "LOG CFNode * ", "LOG Mesh * " and "LOG ESock * " tags. In the case of the ESock tag, the logging which is written to ULogger is also written to CDU.

This usage description assumes that the development tools already include ULogger support.

Note: For more information, see Symbian^3 Tools Guide > Debugging.

Procedure - Using ULogger

Requirements

The following binaries must include logging:

nodemessages.dll
meshmachine.dll
commsfw.dll
serverden.dll
esocksvr.dll

To enable logging for a binary either use the UDEB version of the binary or rebuild the binary with the SYMBIAN_TRACE_ENABLED macro defined.

Steps

Start Eshell - ULogger only supports asynchronous logging, so from EShell start a second instance of EShell.
```
start eshell
```
This allows ULogger to be stopped even if the code under observation does not exit normally.

Set the ULogger Filters - To allow Comms logging enable the following filters:

Level	Description
194	Node Messages
195	Mesh Machine
196	SVG Logging - provides extra logging so that 194 and 195 can be displayed in an SVG file

The following filter is also useful:

Level	Description
3	Kernel Thread ID's - Thread and process creation

Set these filters with the following command:

ulogger -efv 194 195 3 196

Start ULogger - The following command starts ULogger with the filter:
```
 
ulogger -rv
```
Run the code under observation - In the first Eshell session, run the code to be tested or debugged.
Stop ULogger - To stop ULogger and generate the logs, use the command:
```
ulogger -qv
```
Process the binary logs into text - The log file created by ULogger is in a binary format and is located in the c:\logs folder on the device.

To use the log file, the file must be converted to a text format.

The Comms software has a decoder to interpret the ULogger output for Comms. This decoder is an MS Windows-compatible application and is located in …\os\commsfw\commsfwtools\.

An example command to run the decoder is:
```
utracedecoder - -message-def esockmessages.definition.txt ulogger.log > log.txt
```
The decoder uses a definition file to decipher the binary data in the log, and the decoder has definition files configured for the current scope of Comms logging. This example uses the ESock messages definition file, which is located in …\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt.

The output in log.txt contains an interpretation of the original binary logs.
Generating the SVG diagram - The exchange of messages between Nodes can be rendered into a diagram.

From …\os\commsfw\commsfwtools\commstools\svg run parseit.bat specifying the path to the generated log.txt file:
```
parseit.bat /log M:\path_to_log_file\log.txt
```
Example SVG output from the Message Sequence Display Tool

Key to the SVG diagram:
1. Vertical black lines are tagged with names to represent node lifetimes. For example: IPCpr
2. Vertical lines forking from the node lifetime lines are MeshMachine activity lifetimes.
3. Black horizontal lines are message deliveries.
4. Green horizontal lines are message postings.
New message types can be added to the definition files. See the documentation with the utracedecoder component.