Table of Contents
Debug message macros (defined in header file src/lib/cstdmf/debug.hpp) are designed to be used in place of printf() for outputting debug information.
The use of debug message macros instead of printf() allows for more systematic treatment of debug messages. For example, BigWorld server supports centralised logging and filtering for debug messages.
Before being able to use a debug message macro, you must include one of the following declarations in your .cpp file:
-
DECLARE_DEBUG_COMPONENT( modulePriority ), or
-
DECLARE_DEBUG_COMPONENT2( watcherLocation, modulePriority )
The argument modulePriority is a number (usually 0) used for filtering debug messages. For more details, see Filtering by Priority.
These macros also create a watcher entry allowing the modulePriority to be modified. The watcher entry is one of the following:
-
logger/cppThresholds/
<source_filename>, or -
logger/cppThresholds/watcherLocation/
<source_filename>
Debug output macros accept the same parameters as printf(). The printf() function has the syntax below:
int printf( const char * format [argument]... )
An example usage of a debug output macro:
TRACE_MSG( "%s is %d", someString, someInteger );
There are several debug message macros, named in the form <priority>_MSG, as described below:
-
TRACE_MSG ‐ Priority: 0
Tracing program flow, e.g., entering a method.
-
DEBUG_MSG ‐ Priority: 1
Displaying debugging information, e.g., showing the value of a variable.
-
INFO_MSG ‐ Priority: 2
Displaying general information, e.g., the start of a process.
-
NOTICE_MSG ‐ Priority: 3
Displaying information that is more important than INFO, but definitely not an error.
-
WARNING_MSG ‐ Priority: 4
Displaying potential errors.
-
ERROR_MSG ‐ Priority: 5
Displaying definite errors.
-
CRITICAL_MSG ‐ Priority: 6
Displaying critical errors (i.e., errors that cause the program to stop running).
-
HACK_MSG ‐ Priority: 7
Temporary messages used during development. Reserved for BigWorld internal use only.
-
SCRIPT_MSG ‐ Priority: 8
Messages printed from a Python script. Reserved for BigWorld internal use only.
Debug messages are output to the console on Linux and to the debugger on Windows. For components with access to the game time (such as BaseApp and CellApp), it is automatically added to the start of the message.
In addition to outputting to the console (or debugger), the debug messages are also sent to all MessageLogger processes on the network.
Apart from the filtering options available in MessageLogger, logging (i.e., the sending of messages) to a particular MessageLogger can be disabled by specifying the IP address of the MessageLogger machine in the watcher value logger/del. For details on MessageLogger, see the document Server Operations Guide's section Cluster Administration Tools → Message Logger.
The amount of debug output generated by a server component can be controlled through a combination of module priority and filter threshold. A debug message is discarded if its priority is less than the value of variable filterThreshold added to modulePriority.
The variable modulePriority is initialised by the
macro DECLARE_DEBUG_COMPONENT, but can be later changed
using the watcher value
logger/cppThresholds/<source_filename>.
The variable filterThreshold is initialised to zero, but can be changed using the watcher value logger/filterThreshold.
All log messages have an explicit priority value. The DebugMessagePriority enumeration in header file src/lib/cstdmf/debug.hpp defines these values as below:
-
0 ‐ MESSAGE_PRIORITY_TRACE
-
1 ‐ MESSAGE_PRIORITY_DEBUG
-
2 ‐ MESSAGE_PRIORITY_INFO
-
3 ‐ MESSAGE_PRIORITY_NOTICE
-
4 ‐ MESSAGE_PRIORITY_WARNING
-
5 ‐ MESSAGE_PRIORITY_ERROR
-
6 ‐ MESSAGE_PRIORITY_CRITICAL
-
7 ‐ MESSAGE_PRIORITY_HACK
-
8 ‐ MESSAGE_PRIORITY_SCRIPT
This value is used to filter the messages that are printed and sent to the logger. If the message priority is greater than, or equal to the filter threshold value, then the message is allowed. For example, a threshold of MESSAGE_PRIORITY_INFO only allows INFO messages, and higher ‐ which means that TRACE and DEBUG messages will be filtered out.