PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Public Attributes | Related Functions | List of all members
LogManager Class Reference

used for doing logging with variable debug levels More...

Public Member Functions

string binaryDump (BinaryString inData, int length=0, int bytesPerLine=20)
 get hex and ascii representations in a hex dump format.
 
string binaryDump (MemBlock inData, int length=0, int bytesPerLine=20)
 get hex and ascii representations in a hex dump format.
 
number getLogLevel ()
 return the current logging level
 
 initialize (string inLogNameBase, int initMode=LogManager.init_StdOut)
 initialize the LogManager, creating a new log file if necessary
 
LogManager setLogLevel (int inLogLevel)
 set the current logging level
 
 writeLogEntry (int level, string category, string message)
 write a message to the log, if it is high enough priority
 

Public Attributes

const init_AppendToExisting = 2
 if an existing file is present, append to it
 
const init_CreateUniqueNewFile = 0
 append a timestamp to the base name to ensure a unique log files is created
 
const init_OverwriteExisting = 1
 if an existing file is present, overwrite it
 
const init_StdErr = 4
 don't create a file, send log output to stderr
 
const init_StdOut = 3
 don't create a file, send log output to stdout
 

Related Functions

(Note that these are not member functions.)

 getLogManager
 get the singleton instance of the LogManager used by the pdg framework
 

Detailed Description

used for doing logging with variable debug levels

Precondition
API Stability: 3 - Stable. The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility is guaranteed.

About Log Manager

The Log Manager is a singleton object that generates date-time stamped log entries in a file or to stdout or stderr. The Aries log file format used is compact and very easy to search and filter using Unix command line tools like grep and tail.

Anatomy of a Log Entry:

131023 09:33:51 1382520831167   I4  @LOGINIT   log initialized 2013/10/23 05:33:51 for pdg
   |     |         |            |      |          |
   |     |         |            |      |          +-- log message
   |     |         |            |      |
   |     |         |            |      +-- category
   |     |         |            | 
   |     |         |            +-- level code
   |     |         |           
   |     |         +-- millisecond time stamp
   |     |      
   |     +-- time
   |
   +-- date

The fields are:

  1. date – the current date (GMT)
  2. time – the current time (GMT)
  3. millisecond time stamp – the number of milliseconds since system startup, as returned by TimerManager.getMilliseconds()
  4. level code – a code representing the logging level for this entry, useful for filtering or log monitoring tools. This code is one of:
    1. E0, E1, E2, E3 - Error (levels 0..3)
    2. I4, I5, I6, I7 - Inform (levels 4..7)
    3. V8 or V9 - Verbose (levels 8 & 9)
    4. TRACE - level 10
  5. category – a category of message, very useful for filtering. Generally these reflect areas of functionality that would be monitored or debugged separately, e.g.: "AI", "PATHING", "TURN", etc... (See Note below)
  6. message – the actual log message content
Note
By convention, categories starting with @ are reserved for the messages generated by the LogManager itself. Also, categories FATAL, ERROR, WARN, LOG,INFO, DEBUG, and TRACE are generated by calls to pdg.fatal(), pdg.error(), pdg.warn(), pdg.log(), pdg.info(), pdg.debug() and pdg.trace() calls so using those values as categories is inadvisable.

Usage Examples:

PDG terminal v0.9.3
> pdg.getLogManager().initialize("pdg", pdg.getLogManager().init_StdOut);
> pdg.getLogManager().setLogLevel(10);
131023 09:33:51 1382520831167   I4   @LOGINIT    log initialized 2013/10/23 05:33:51 for pdg
131023 09:33:51 1382520831168   I4   @BLDINFO    Build: [Oct 20 2013 11:55:02] Compiler: [GNU gcc] Target: [x86_64-apple-darwin]
131023 09:33:51 1382520831177   I4   @LOGLVL     setting log level to [10]
> pdg.getLogManager().writeLogEntry(1, "AI", "calculated chance of mission success 93%");
131023 09:34:14 1382520854276   E1   AI          calculated chance of mission success 93%
> pdg.fatal("test fatal error message");
131023 09:34:56 1382520896706   E0   FATAL       test fatal error message
> pdg.error("test error message");
131023 09:34:56 1382520896706   E1   ERROR       test error message
> pdg.warn("test warn message");
131023 09:35:52 1382520952860   E3   WARN        test warn message
> pdg.log("test log message");
131023 09:34:40 1382520880899   I4   LOG         test log message
> pdg.info("test info message");
131023 09:35:38 1382520938037   I5   INFO        test info message
> pdg.debug("test debug message");
131023 09:35:11 1382520911109   I7   DEBUG       test debug message
> pdg.trace("test trace message");
131023 09:35:27 1382520927229   V9   TRACE       test trace message
See Also
TimerManager.getMilliseconds()
pdg.captureConsole()

Member Function Documentation

string binaryDump ( BinaryString  inData,
int  length = 0,
int  bytesPerLine = 20 
)

get hex and ascii representations in a hex dump format.

Parameters
inDatathe binary string you want to dump
lengththe number of bytes to dump, or 0 for entire contents of the BinaryString given
bytesPerLinehow many bytes should be on each row of the output
Note
a BinaryString is a JavaScript string where each character's integer value is from [0..255]. Normal JavaScript strings are UTF-16, so they have 2 bytes per character, but for these purposes we ignore the high byte.
string binaryDump ( MemBlock  inData,
int  length = 0,
int  bytesPerLine = 20 
)

get hex and ascii representations in a hex dump format.

Parameters
inDatathe MemBlock you want to dump
lengththe number of bytes to dump, or 0 for entire contents of the MemBlock given
bytesPerLinehow many bytes should be on each row of the output
getLogLevel ( )

return the current logging level

Returns
a numeric value representing the current logging level
See Also
setLogLevel()
initialize ( string  inLogNameBase,
int  initMode = LogManager.init_StdOut 
)

initialize the LogManager, creating a new log file if necessary

The following information is output to the log whenever the log manager is initialized:

131023 09:33:51 1382520831167   I4   @LOGINIT    log initialized 2013/10/23 05:33:51 for pdg
131023 09:33:51 1382520831168   I4   @BLDINFO    Build: [Oct 20 2013 11:55:02] Compiler: [GNU gcc] Target: [x86_64-apple-darwin]

The @LOGINT line gives the local Date/Time (YYYY/MM/DD) when the Log Manager was initialized, and the "for {name}" portion echoes the inLogNameBase passed in. The @BLDINFO reports the PDG version, app build date/time, compiler and target platform.

initMode is one (and only one) of:

  • init_CreateUniqueNewFile - appends a timestamp to log file base name to ensure a unique file is created
  • init_OverwriteExisting - if an existing file is present, overwrite it completely
  • init_AppendToExisting - if an existing file is present, append to it
  • init_StdOut - don't create a file, instead send log output to stdout
  • init_StdErr - don't create a file, instead send log output to stderr
Parameters
inLogNameBasethis is used to help form the log file name
initModesets the mode the LogManager will use for outputting log entries
setLogLevel ( int  inLogLevel)

set the current logging level

The log level is the lowest priority (highest numerical value) of log message that will actually be logged. Any lower priority (higher numeric value) messages will be filtered.

Whenever the log level is changed, a message reflecting that change in log level is echoed to the log, e.g.:

131023 09:33:51 1382520831177   I4   @LOGLVL     setting log level to [10]
See Also
getLogLevel()
writeLogEntry()
writeLogEntry ( int  level,
string  category,
string  message 
)

write a message to the log, if it is high enough priority

Write a message to the log. If the level is lower priority (higher numeric value) than the current log level, the message will be filtered and not written to the log. Category is a short string used to define the area of functionality the logging is about, useful for debugging to narrow down the number of log entries you need to examine. Message is the actual log message

Note
see binaryDump() for converting binary data to a hex dump

Log levels (highest to lowest priority, lowest to highest numeric value):

fatal = 0, 
error = 2, 
inform = 4, 
detail = 6, 
verbose = 8, 
trace = 10,
Parameters
levelthe priority level of this message (see above)
categorythe category of message
messagethe actual log message
See Also
binaryDump()
setLogLevel()
pdg.fatal()
pdg.error()
pdg.warn()
pdg.log()
pdg.info()
pdg.debug()
pdg.trace()

Friends And Related Function Documentation

getLogManager
related

get the singleton instance of the LogManager used by the pdg framework

Returns
LogManager singleton object

Member Data Documentation

init_AppendToExisting = 2

if an existing file is present, append to it

This flag is passed as initMode to LogManager.initialize() to cause the new log entries to be appended to an existing file. If no file exists, a new one will be created.

See Also
initialize()
init_CreateUniqueNewFile = 0

append a timestamp to the base name to ensure a unique log files is created

This flag is passed as initMode to LogManager.initialize() to cause the a new unique log file to be created.

See Also
initialize()
init_OverwriteExisting = 1

if an existing file is present, overwrite it

This flag is passed as initMode to LogManager.initialize() to cause the new log entries to overwrite an existing file with the same name. If no file exists, a new one will be created.

See Also
initialize()
init_StdErr = 4

don't create a file, send log output to stderr

This flag is passed as initMode to LogManager.initialize() to cause the log entries to be sent to stderr instead of to a file. No existing files are altered and no new files are created.

See Also
initialize()
init_StdOut = 3

don't create a file, send log output to stdout

This flag is passed as initMode to LogManager.initialize() to cause the log entries to be sent to stdout instead of to a file. No existing files are altered and no new files are created.

See Also
initialize()

User Comments