[BACK] Return to logging.dxt CVS log [TXT][DIR] Up to Nevrax / code / nel / doc

Diff for /code/nel/doc/logging.dxt between version 1.4 and 1.5

version 1.4, 2001/02/05 16:11:36 version 1.5, 2001/05/04 09:58:23
Line 1 
Line 1 
 /** /**
  \page log_howto How to log information ?  \page log_howto How to log information (for debugging purpose) ?
  \author Olivier Cado  \author Olivier Cado
   \date Updated May 4 2000
  
  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.  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 \section basic_debug Basic usage of the debugging system
  The debugging sytem allows to log information at various levels. Include the header file "nel/misc/debug.h".
  
  In the initialization of your service (see NLNET::IService), attach some displayers to the global NLMISC::CLog objects The main functionalities are offered by the macros nldebug, nlinfo, nlwarning and also nlerror and nlassert, and by their variant forms (see debug.h). They allow to display strings, with open arguments, using the "printf" syntax. In the default behaviour, the text passed to nldebug is displayed into stdout in NL_DEBUG mode, but not in NL_RELEASE. The logged texts are also written into a file called "log.log" in the working directory. These macros print the strings with an information header.
  \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 :  Example :
  \code  \code
   sint32 age = -2;
  NLMISC::InitDebug(); // if your program does not inherit from NLNET::IService  nldebug( "Toto is %d years old", age );
  NLNET::CNetDisplayer *nd = new CNetDisplayer(); // the address of the Logging Server is automatically retrieved using the Naming Service  if ( age < 0 )
  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 );      nlerror( "Invalid age for toto : %d", age );
  
       // the program will not come here because nlerror throws an exception to exit
  }  }
  
   STDOUT (logger thread_id file line: debug_string):
   DBG 1234 myfile.cpp 10: Toto is -2 years old
   ERR 1234 myfile.cpp 13: Invalid age for toto : -2
   Abort
  
   FILE OUTPUT (date time logger debug_string):
   01/04/11 18:24:50 DBG: Toto is -2 years old
   01/04/11 18:24:50 ERR: Invalid age for toto : -2
  \endcode  \endcode
  
  \subsection use_log Logging information Because NeL allows to create multithreaded programs, these macros use mutual exclusions (mutex) to ensure no data is corrupted and the displayed text not interlaced.
  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 : \section adv_log Advanced usage of the logging system
  
  You may want to customize the logging system directly, for your own needs. Include "nel/misc/log.h".
  
  \subsection init_log Initialization
  If your program is not a "service" in the NeL terms (i.e. if it is not built on NLNET::IService),
  first call createDebug() to create the basic global loggers \e ErrorLog, \e WarningLog, \e InfoLog, \e DebugLog and \e AssertLog (the ones that are used by the nlerror, nlwarning, nlinfo, nldebug and nlassert macros).
  
  Then, you can attach some displayers to the global loggers (NLMISC::CLog objects).
  - NLMISC::CStdDisplayer is for stdout (the console, the VC++ output 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 nelns documentation).
  - You can can create your own displayer, in order to print the logged text onto a new target (for example, see the class CChatDisplayer in Snowballs 0.2) or to customize the filter on the header.
  
  Example (we assume CNetDisplayer allows to log via the network):
  \code  \code
  nldebug( "Toto is %d years old", age ); 
  if ( age < 0 )  createDebug(); // automatically done in a "service"
   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
  {  {
      nlerror( "Invalid age for toto : %d", age );      NLMISC::DebugLog.addDisplayer( nd );
      // the program counter will never be here because nlerror throw an exception to exit 
  }  }
  \endcode  \endcode
  
  - How to log a string without repeating the header ?  \subsection use_log Logging information
  
  The macros nldebug() and nlerror() call some methods of NLMISC::CLog, including displayNL().  How to log a string without repeating the header ? Use the methods of NLMISC::CLog.
  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 :  Example :
  \code  \code
Line 62 
Line 76 
  }  }
  \endcode  \endcode
  
  */
  
  \subsection network_transfers Analysing network transfers  \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.  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.
Line 70 
Line 86 
  
  By default, all services (see NLNET::IService) send this kind of logs if they find a logging server.  By default, all services (see NLNET::IService) send this kind of logs if they find a logging server.
  
 */ 

Legend:
Removed from v.1.4 
changed lines
 Added in v.1.5