<?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 xml:lang="en" id="GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF"><title>Textual Logging</title><shortdesc>This topic describes the textual logging mechanisms available to help debugging the Communication-related components. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>Most Comms components can output debugging information. These components must be configured to output information, with the configuration procedure dependent on the logging mechanism used by the component. The following mechanisms are used to log the information: </p> <ul><li id="GUID-726B089B-F8E0-5893-9D3F-4AEBD1751BF1"><p> <b>Flogger</b> - This logging mechanism is a file logger. It used to be the standard mechanism for Comms logging, but it is being replaced by CDU (below). </p> </li> <li id="GUID-FC40C065-ED23-5F49-AAA7-F557BD12CD58"><p> <b>Comms Debug Utility (CDU)</b> - This logging mechanism is currently used for the majority of Comms logging. It is the successor to Flogger and adds a two-phase logging system to give flexibility in debugging problems which are difficult to reproduce in debug binary files. It unifies Comms logging into one text file and allows the output to be redirected to RDebug for easier on-target debugging, or on emulator to the fast Windows Debug port. For more information see <xref href="GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF.dita#GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF/GUID-34383668-480A-50DF-A3DB-8DE17D49ED30">Post-processing CDU log files</xref>, <xref href="GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF.dita#GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF/GUID-217068A5-CC0A-5548-898E-C392F2031647">Default CDU</xref> and <xref href="GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF.dita#GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF/GUID-3F3CDC4F-A2C4-5DD4-8E7C-24D67DA8DA3B">Interpreting the log files</xref>. </p> <p> <b>Note:</b> The CDU API is not published and so its APIs cannot be used for adding new logging. </p> </li> <li id="GUID-FBD09686-A6AD-5781-BA2D-E1041B0B4D47"><p> <b>Unified Trace/UTrace/ULogger</b> - This logging mechanism is currently used for a small amount of Comms logging. For more information see <xref href="GUID-ABE77283-EED8-5A33-B574-3B771EF11086.dita">How to Use ULogger with Comms</xref>  </p> </li> <li id="GUID-EBC721D3-8EF5-5C5D-8AC7-F606B809E4E2"><p> <b>Proprietary</b> - This logging mechanism belongs to the component itself. A few components still use their own logging mechanisms, but these usually behave similarly to Flogger in that to obtain the logs the appropriate folder needs to exist while the component is running. </p> </li> </ul> <p> <b> Note:</b> When you enable logging for a component, the component may run significantly slower as it performs the logging. This could make reproducing a problem more difficult if the reduced component execution performance changes the sequence of events leading to the problem. </p> <section id="GUID-34383668-480A-50DF-A3DB-8DE17D49ED30"><title>Post-processing CDU log files</title> <p>The CDU log file format is designed to be viewed unprocessed. However, in some cases post-processing is required. Two post-processing tools are available: </p> <ul><li id="GUID-7C6331FC-D651-5813-B8EF-9762600682BB"><p> <b>Splitlog</b> - is supplied in <codeph>epoc32\tools</codeph> and splits the single <codeph>log.txt</codeph> file into multiple files by each unique tag combination. This tool is used to extract embedded binary logging such as that for PPP described below in <xref href="GUID-935DF48C-F014-5E2A-8BE6-29B00C4FD31D.dita">Component-Specific Debugging Help</xref>. </p> </li> <li id="GUID-27AF2B6F-5108-5A98-AD3E-23445E1ED87C"><p> <b>Networking Message Sequence Display Tool</b> - processes a standard <codeph>log.txt</codeph> file to extract the Comms Framework messages and generates HTML/SVG output files for display on a suitable SVG-enabled browser. </p> <fig id="GUID-02A86F64-2278-5B46-82A4-7243C4790107"><title>

                  Figure 1 - Example SVG output from the Message Sequence Display

                  Tool 

                </title> <image href="GUID-6CE1C2E0-8F57-57D3-9041-929FE30ECEB9_d0e78396_href.png" placement="inline"/></fig> </li> </ul> </section> <section id="GUID-217068A5-CC0A-5548-898E-C392F2031647"><title>Default CDU</title> <p>CDU provides a default configuration file which lists all the known components which use it, and also provides a reference listing of <keyword>iby</keyword> files and their respective component source code and log tags. Figure 2 provides a snapshot of the configuration file: </p> <fig id="GUID-22A390A6-F81E-5ECF-8A48-07D51ABD9037"><title>

             Figure 2 - The default commsdbg.ini file 

          </title> <image href="GUID-0D3060BE-8C0F-564A-8979-C9A88C49C5E8_d0e78415_href.png" placement="inline"/></fig> <p>The default CDU file is located at <filepath>..\comms-infras\commsdebugutility\group\commsdbgdefault.ini</filepath> and is available for the emulator in <filepath>epoc32\&lt;data|release\winscw\&lt;udeb|urel&gt;&gt;\z\resource\commsdbg.ini</filepath>. </p> </section> <section id="GUID-3F3CDC4F-A2C4-5DD4-8E7C-24D67DA8DA3B"><title>Interpreting the log files</title> <p>Comms components have specific log file schemes with some similarities. The following are guidelines for interpreting the files: </p> <ul><li id="GUID-54407D7D-E1FC-50C2-BFF5-961E699C02DE"><p> <b>Errors are logged</b> - when a panic or other serious error condition is encountered. Often the last few log lines includes where the critical condition was reached, since usually the panic code or error code alone is not enough. If not, then often searching for "warning" or "error" in the earlier logging will identify where the problem began. </p> </li> <li id="GUID-26C4961B-BA78-53B0-BEE4-E591D1C1717C"><p> <b>Multi-threaded module output prefixes thread number</b> - ESock and the C32 Serial Server prefix the log lines with the thread number within the specific thread numbering scheme. For example: </p> <codeblock id="GUID-6E3B1FF9-8FC2-5C5A-87E0-7D2BA45BFDCA" xml:space="preserve">esock   esock   a 2e W0: CWorkerThread::ConstructL Init RS ChannelHandler

esock   esock   a    32    W4: SocketServer::InitL() Done!

esock   Booting a 32 W4: CWorkerThread::ConstructL Init ProtocolManager