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. More...

string	binaryDump (MemBlock inData, int length=0, int bytesPerLine=20)
	get hex and ascii representations in a hex dump format. More...

number	getLogLevel ()
	return the current logging level More...

	initialize (string inLogNameBase, int initMode=LogManager.init_StdOut)
	initialize the LogManager, creating a new log file if necessary More...

LogManager	setLogLevel (int inLogLevel)
	set the current logging level More...

	writeLogEntry (int level, string category, string message)
	write a message to the log, if it is high enough priority More...

Public Attributes
const	init_AppendToExisting = 2
	if an existing file is present, append to it More...

const	init_CreateUniqueNewFile = 0
	append a timestamp to the base name to ensure a unique log files is created More...

const	init_OverwriteExisting = 1
	if an existing file is present, overwrite it More...

const	init_StdErr = 4
	don't create a file, send log output to stderr More...

const	init_StdOut = 3
	don't create a file, send log output to stdout More...

Related Functions
(Note that these are not member functions.)
	getLogManager
	get the singleton instance of the LogManager used by the pdg framework More...

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:

date – the current date (GMT)
time – the current time (GMT)
millisecond time stamp – the number of milliseconds since system startup, as returned by TimerManager.getMilliseconds()
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
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)
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

inData	the binary string you want to dump
length	the number of bytes to dump, or 0 for entire contents of the BinaryString given
bytesPerLine	how 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

inData	the MemBlock you want to dump
length	the number of bytes to dump, or 0 for entire contents of the MemBlock given
bytesPerLine	how 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

inLogNameBase	this is used to help form the log file name
initMode	sets 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

level	the priority level of this message (see above)
category	the category of message
message	the 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

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()

Public Member Functions

Public Attributes

Related Functions

Detailed Description

About Log Manager

Anatomy of a Log Entry:

Usage Examples:

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

User Comments