Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site













SourceForge.net Logo

U++ Logging

 

U++ logging infrastructure is based on output stream, which is capable of outputting log lines into decided output facilities (files, console output, syslog).

 

Logging itself is then based on set o macros that output values to this stream, usually using AsString or operator<<(Stream&, ...) to convert values.

 

This stream is accessible through UppLog() function and its default version is provided by U++, however it can be replaced (using SetUppLog).

 

Multithreading note: Standard log stream handles serialization of output in its implementation  (and any possible replacement should do that too), so it is possible to use single output stream in all threads.

 

Entity List

 

void StdLogSetup(dword options, const char *filepath = NULL, int filesize_limit = 10 * 1024 * 1024)

This function setups standard U++ logging. filepath is the path of .log file (if logging to file is active), filesize_limit is maximum size of log (if LOG_FILE options is active), if achieved, a new log file is created. options is a combination of bit flags:

 

LOG_FILE

Output log to file (this is default). The default path of file is ConfigFile("program_name.log").

LOG_COUT

Output log to standard output.

LOG_CERR

Output log to error output.

LOG_DBG

Output log to debugger (Win32 specific).

LOG_SYS

Output log to syslog (POSIX specific).

LOG_TIMESTAMP

Prepend local time timestamp to each log line (not with LOG_SYS, as syslog already does this).

LOG_TIMESTAMP_UTC

Prepend universal time timestamp to each log line (not with LOG_SYS).

LOG_APPEND

When starting a program, append log to existing file instead of replacing it.

LOG_ROTATE(x)

When starting a new log file, up to x older logs is preserved (renamed with extension '.1', '.2' etc...).

LOG_ROTATE_GZIP

Older preserved log files are compressed using gzip (except the most recent log '.1'.

 


 

Stream& StdLog()

Returns a reference to standard log stream.

 


 

String GetStdLogPath()

Returns the path of current log, if any.

 


 

const char LOG_BEGIN = '\x1e';

Putting this character into standard log stream adds one tabulator of indentation to all subsequent lines (moves text "right").

 


 

const char LOG_END = '\x1f';

Putting this character into standard log stream removes one tabulator of indentation to all subsequent lines (moves text "left").

 


 

Stream& UppLog()

Returns a reference to current log stream.

 


 

void SetUppLog(Stream& log)

Sets the current log stream to log (must be an object with global lifetime).

 

 

 

Logging macros

 

Standard logging macros come in 3 basic flavors. "Normal" macros (LOG, DUMP, ...) only emit code in debug mode, "Debugging" macros (DLOG, DDUMP, ..., first letter is 'D') only compile in debug mode and their presence causes release mode compilation to fail (this is to prevent any forgotten debugging macros in code) and finally "Release" macros (RLOG, RDUMP, ..., first letter is 'R') produce output even in release mode.

 

LOG(x), DLOG(x), RLOG(x)

Outputs a single line to log.

DUMP(x), DDUMP(x), RDUMP(x)

Outputs a variable - adds a variable name before value -  defined as LOG(#x << "=" << x)

DUMPC(x), DDUMPC(x), RDUMPC(x)

Outputs a Vector or Array or Index of values.

DUMPM(x), DDUMPM(x), RDUMPM(x)

Outputs a VectorMap or ArrayMap.

TIMING(x), DTIMING(x), RTIMING(x)

Establishes profiling timing inspector which profiles since definition till the end of block, profiling values are printed to log at the program exit.

LOGHEX(x), DLOGHEX(x), RLOGHEX(x)

Outputs value as hexadecimal dump, currently works with String.

DUMPHEX(x), DDUMPHEX(x), RDUMPHEX(x)

Outputs variable as hexadecimal dump, like LOGHEX but puts variable name into log.

 

In addition to this it is common practice to use 'local' macros that can be switched on/off for given modules files; standard approach is to add

 

#define LLOG(x)    // DLOG(x)

 

at the start of files with local logging, then activate logging by uncommenting the DLOG.

 

U++ has also concept of "modular" logging, where specific logging macros can be created that are bound to some global boolean entity (usually INI_BOOL). Creation of these modular logs is simplified by macro:

 

#define LOG_(flag, x)     do { if(flag) RLOG(x); } while(false)

 

One such predefined type exists, USRLOG, that is indended to log user actions (like opening windows, pressing keyboard keys) and can be activated by IniBool Ini::user_log (and also by setting user_log=true in .ini file):

 

#define USRLOG(x)         LOG_(Ini::user_log, x)

 

Last edit by cxl on 11/07/2016. Do you want to contribute?. T++