<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-ABE77283-EED8-5A33-B574-3B771EF11086" xml:lang="en"><title>How
to Use ULogger with Comms</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This tutorial summarises one approach for enabling, retrieving and post-processing
the <xref href="GUID-B25AB5A9-52A6-50C2-8656-F8ADEE260FC9.dita">ULogger</xref> logs
for Comms. ULogger is part of the Unified Trace framework which replaces other
logging mechanisms for Symbian OS including Flogger and CDU. </p>
<p>The Unified Trace framework has greater flexibility and speed compared
to Flogger and CDU. </p>
<section><title>Introduction</title> <p>The Comms logging which has been migrated
to ULogger is as follows: </p> <ul>
<li id="GUID-677DDC92-E655-50AD-85A3-7B6817F9E12A"><p>Comms Framework Node
messages - creation and destruction of Nodes and messages between Nodes. </p> </li>
<li id="GUID-E496D531-2CF2-5042-8820-BC8CE75CE4C6"><p>Mesh Machine messages </p> </li>
<li id="GUID-E4892E5F-845B-5672-AB90-944A8B7DAEBE"><p>data to support the
SVG generation </p> </li>
</ul> <p>This logging replaces some of what was logged through the "<codeph>LOG
CFNode *</codeph> ", "<codeph>LOG Mesh *</codeph> " and "<codeph>LOG ESock
*</codeph> " tags. In the case of the <codeph>ESock</codeph> tag, the logging
which is written to ULogger is also written to CDU. </p> <p>This usage description
assumes that the development tools already include ULogger support. </p>  </section>
<section><title>Procedure - Using ULogger</title> <p><b>Requirements</b></p> <p> 
          For this tutorial, the code under observation must be run from <xref href="GUID-D90C86C6-B85D-5941-9919-3725A9FFD548.dita">EShell</xref>.          </p> <p> 
          The following binaries must include logging:          </p> <ul>
<li><p>                 <filepath>nodemessages.dll</filepath>            
   </p> </li>
<li><p>                 <filepath>meshmachine.dll</filepath>             
  </p> </li>
<li><p>                 <filepath>commsfw.dll</filepath>                </p> </li>
<li><p>                 <filepath>serverden.dll</filepath>                </p> </li>
<li><p>                 <filepath>esocksvr.dll</filepath>                </p> </li>
</ul><p> To enable logging for a binary either use the UDEB version of the
 binary or rebuild the binary with the <codeph>SYMBIAN_TRACE_ENABLED</codeph> macro
defined. </p></section>
<section><title>Steps</title> <ol>
<li id="GUID-E3B09A4E-C87A-45F9-8DE6-653BA1A2E426"><p>                 <b>Start
Eshell</b> - ULogger only supports asynchronous                 logging, so
from EShell start a second instance of EShell.                </p> <codeblock xml:space="preserve">start eshell</codeblock> <p> 
               This allows ULogger to be stopped even if the code under  
              observation does not exit normally.                </p> </li>
<li id="GUID-8A912D95-8D99-4D2A-9A5E-C51132924DAC"><p>                 <b>Set
the ULogger Filters</b> - To allow Comms logging                 enable the
following filters:                </p><table id="GUID-56D45DFD-FD08-4B16-AB72-E5DD51C888E1">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Level</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <p>                         194                        </p></entry>
<entry> <p>                         Node Messages                        </p></entry>
</row>
<row>
<entry> <p>                         195                        </p></entry>
<entry> <p>                         Mesh Machine                        </p></entry>
</row>
<row>
<entry> <p>                         196                        </p></entry>
<entry> <p>                         SVG Logging - provides extra logging so
that 194 and 195                         can be displayed in an SVG file 
                      </p></entry>
</row>
</tbody>
</tgroup>
</table> <p>                 The following filter is also useful:        
       </p> <table id="GUID-F2BA543D-0396-4552-9546-EF332B6BD747">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Level</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <p>                         3</p></entry>
<entry> <p>                         Kernel Thread ID's - Thread and process
creation                        </p></entry>
</row>
</tbody>
</tgroup>
</table> <p>                 Set these filters with the following command:
               </p> <codeblock xml:space="preserve">ulogger -efv 194 195 3 196
 </codeblock> </li>
<li id="GUID-72C31641-7F65-4AA8-83BB-752E7A6EE77E"><p>                 <b>Start
ULogger</b> - The following command starts ULogger                 with the
filter:                </p> <codeblock xml:space="preserve">
 
ulogger -rv</codeblock> </li>
<li id="GUID-CEDCDC01-1E86-4A67-9822-D94370DAF5E8"><p>                 <b>Run
the code under observation</b> - In the first Eshell                 session,
run the code to be tested or debugged.                </p> </li>
<li id="GUID-8EA473A7-6609-48C2-8E66-BA56D0178669"><p>                 <b>Stop
ULogger</b> - To stop ULogger and generate the                 logs, use the
command:                </p> <codeblock xml:space="preserve">ulogger -qv</codeblock> </li>
<li id="GUID-AC7549F8-4010-45D6-8C76-9322C16C86A1"><p>                 <b>Process
the binary logs into text</b> - The log file                 created by ULogger
is in a binary format and is located in the                 <filepath>c:\logs</filepath> folder
on the device.                </p> <p>                 To use the log file,
the file must be converted to a text format.                             
  </p> <p>                 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 <filepath>…\os\commsfw\commsfwtools\</filepath>.
               </p> <p>                 An example command to run the decoder
is:                </p> <codeblock xml:space="preserve">utracedecoder - -message-def esockmessages.definition.txt ulogger.log &gt; log.txt</codeblock> <p> 
               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  
              <filepath>…\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt</filepath>.
                               </p> <p>                 The output in log.txt
contains an interpretation of the original                 binary logs.  
             </p> </li>
<li id="GUID-73E7C874-4487-492C-875C-642ECEBDF74F"><p>                 <b>Generating
the SVG diagram</b> - The exchange of                 messages between Nodes
can be rendered into a diagram.                </p> <p>                 From <filepath>…\os\commsfw\commsfwtools\commstools\svg</filepath> run
                <filepath>parseit.bat</filepath> specifying the path to the
generated log.txt file:                </p> <codeblock xml:space="preserve">parseit.bat /log M:\path_to_log_file\log.txt</codeblock><fig id="GUID-F6E85A8D-09B3-40A1-B3DC-5B968C3F1A4C">
<desc>Example SVG output from the Message Sequence Display Tool </desc>
<image href="GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e90460_href.png" placement="inline"/>
</fig> <p>                 Key to the SVG diagram:                </p> <ol>
<li id="GUID-64C07144-E5BD-465E-915F-1A867AD62FAB"><p>                   
   Vertical black lines are tagged with names to represent node          
            lifetimes. For example: <codeph>IPCpr</codeph>               
     </p> </li>
<li id="GUID-4BEE656D-9DEB-402B-B3A9-3A5C822B5E99"><p>                   
   Vertical lines forking from the node lifetime lines are               
       MeshMachine activity lifetimes.                     </p> </li>
<li id="GUID-BA5C28EF-856F-45CD-B6B8-AD1C0D663CA1"><p>                   
   Black horizontal lines are message deliveries.                     </p> </li>
<li id="GUID-61D41E05-7269-4A95-843D-E536141E56E0"><p>                   
   Green horizontal lines are message postings.                     </p> </li>
</ol> <p>                     New message types can be added to the definition
files. See the documentation with the utracedecoder component.           
     </p> </li>
</ol></section>
</conbody><related-links>
<link href="GUID-A3E77067-7982-5803-A274-0C8F2562B483.dita"><linktext>Unified Trace
Solution</linktext></link>
<link href="GUID-9006B4EE-194E-50FA-A803-F9EAA13E14AA.dita"><linktext>How to Use
the ULogger Configuration File</linktext></link>
</related-links></concept>