Return to logging.dxt CVS log

Up to Nevrax / code / nel / doc

new display system

/**
 \page log_howto How to log information ?
 \author Olivier Cado

 This document explains how to log some information (into the screen, into a file or to a logging server), e.g. in order to debug your code.
 You need to include the following header files : "nel/misc/debug.h" "nel/misc/log.h".

 \subsection init_log Initialization

 In the initialization of your service (see NLNET::IService), attach some displayers to the global NLMISC::CLog objects
 \e ErrorLog, \e WarningLog, \e InfoLog, \e DebugLog and \e AssertLog.
 NLMISC::CStdDisplayer is for the screen (and VC++ debug window). It is attached by default to all of the five logger objects mentionned above.
 NLMISC::CFileDisplayer is for a file.
 NLMISC::CMsgBoxDisplayer is for a message box.
 NLNET::CNetDisplayer is for a logging server (see CLogService in the server documentation)

 If your program is not a service (i.e. it is not inherited from NLNET::IService),
 don't forget to call \b NLMISC::InitDebug() at the beginning of your program, otherwise
 the logging functions won't work.

 Example :
 \code

 NLMISC::InitDebug(); // if your program does not inherit from NLNET::IService
 NLNET::CNetDisplayer *nd = new CNetDisplayer(); // the address of the Logging Server is automatically retrieved using the Naming Service
 if ( nd->connected() ) // this line is optional: here we don't want the displayer to attempt other connections if the first one failed
 {
     NLMISC::DebugLog.addDisplayer( nd );
 }
 \endcode

 \subsection use_log Logging information
 In your code, use the macros :  \e nlerror, \e nlwarning, \e nlinfo, \e nldebug with a variable number of arguments.
 You have to include the header "nel/misc/debug.h".

 Example :
 \code
 nldebug( "Toto is %d years old", age );
 if ( age < 0 )
 {
     nlerror( "Invalid age for toto : %d", age );
     // the program counter will never be here because nlerror throw an exception to exit
 }
 \endcode

 - How to log a string without repeating the header ?

 The macros nldebug() and nlerror() call some methods of NLMISC::CLog, including displayNL().
 It prints a string with an information header.
 If you don't want to print the header, use the others methods of NLMISC::CLog.

 Example :
 \code
 NLMISC::DebugLog.displayNL ( "Dump of Values :" );
 for ( int j=0; j!=height; ++j )
 {
     for ( int i=0; i!=width; ++i )
     {
         NLMISC::DebugLog.displayRaw( "%d ", Values[j][i] );
     }
     NLMISC::DebugLog.displayRawNL( ": line %d", j );
 }
 \endcode

 \subsection network_transfers Analysing network transfers

 NLNET::NetLog (declared in "nel/net/nel_log.h") is a special logger that allows to send output and input logs to a logging server.
 These logs are produced by the network subsystem and have a special syntax so that an analyser can process them and display the transfers
 graphically in real-time.

 By default, all services (see NLNET::IService) send this kind of logs if they find a logging server.

*/