class methods
global functions
ofLog provides an interface for writing text output from your app. It's basically a more useful version of cout or printf where output can be filtered and written to the console or to a file.
Sometimes you want to be able to see when something has happened inside the code, but don't need to draw something visually. Oftentimes it's more then enough to print out the state of a few variables when debugging. Other times you need to know if a crash happened while your app was running somewhere, so you log messages and variables to a file you can read after the program crashes.
Log Levels
You can also set the logging level so only messages above a certain priority are shown. This is useful if you want see lots of messages when debugging, but then set a higher level so only warnings and errors appear for users. See ofSetLogLevel(logLevel) for more detail.
Log levels are (in order of priority):
OF_LOG_VERBOSE
OF_LOG_NOTICE
OF_LOG_WARNING
OF_LOG_ERROR
OF_LOG_FATAL_ERROR
OF_LOG_SILENT
Note: OF_LOG_SILENT is a special value which disables all messages.
Usage
There are 2 ways you can use ofLog:
Functional: as a function taking a message
// send a single string message, setting the log level
ofLog(OF_LOG_NOTICE, "the number is " + ofToString(10));
// the legacy printf style
ofLog(OF_LOG_NOTICE, "the number is %d", 10);
See ofLog(logLevel, &message) & ofLog(logLevel, format*, ...) for more details.
Stream: as a stream using the << stream operator
// the stream style, setting the log level
ofLog(OF_LOG_NOTICE) << "the number is " << 10;
// this is the same as the last line, but only sends at log level notice
ofLog() << "the number is " << 10;
// there are also log level specific stream objects,
// one for each level except OF_LOG_SILENT
ofLogVerbose() << "a verbose print"
ofLogNotice() << "a regular notice print";
ofLogWarning() << "uh oh, a warning";
ofLogError() << "oh no, an error occurred!";
ofLogFatalError() << "accckkk, a fatal error!!";
Note: The log level specific stream objects also take a string argument for the "module". A module is a string that is added to the beginning of the log line and can be used to separate logging messages by setting an independent log level for that module only. This module-specific log level has no effect on other modules. See ofSetLogLevel(module, logLevel) for more detail.
// log to a module called "Hello"
ofLogWarning("Hello") << "a warning print";
Warning: It is important to understand that the log level specific stream objects take the module name as an argument and the log messages via the << operator. Putting your message as a string argument inside the parentheses uses that message as a module and so nothing will be printed:
// this prints a warning message
ofLogWarning() << "a warning print";
// !!! this does not print a message as the string "a warning print" is the module argument !!!
ofLogWarning("a warning print");
// this prints a warning message to the "Hello" module
ofLogWarning("Hello") << "a warning print";
Log Message Redirection
Last, it's useful to be able to record log messages to a file or send them to a custom destination. For log redirection see ofLogToFile(), ofLogToConsole(), & ofSetLoggerChannel() in the ofLog functions.
ofLog()
ofLog::ofLog()
ofLog provides a streaming log interface by accepting variables via the ostream operator << similar to cout and cerr.
It builds a string and logs it when the stream is finished. A newline is printed automatically and all the stream controls (endl, flush, hex, etc) work normally.
// converts incoming primitive types (int, float, etc) to strings automatically
ofLog() << "a string" << 100 << 20.234f;
The log level is explicitly OF_LOG_NOTICE.
See ofSetLogLevel(logLevel) for more info on log levels.
ofLog(...)
ofLog::ofLog(ofLogLevel level)
The same as the ofLog() stream interface, except it accepts a log level.
// set the log level
ofLog(OF_LOG_WARNING) << "a string" << 100 << 20.234f;
You can use the derived convenience classes as an alternative for specific log levels:
ofLogVerbose()
ofLogNotice()
ofLogWarning()
ofLogError()
ofLogFatalError()
// set the log level
ofLog(OF_LOG_WARNING) << "a string" << 100 << 20.234f;
// this is the same as above
ofLogWarning() << "a string" << 100 << 20.234f;
See ofSetLogLevel() for more info on log levels.
ofLog(...)
ofLog::ofLog(ofLogLevel level, const string &message)
Logs a string at a specific log level.
The string message can be concatenated using the ofToString() conversion function in ofUtils:
// build a single string message
ofLog(OF_LOG_NOTICE, "the number is "
+ ofToString(10) + " and I have a float too " + ofToString(123.45f));
See ofSetLogLevel(logLevel) for more info on log levels.
Documentation from code comments
Log a string at a specific log level.
Supply the logging message as a parameter to the function instead of as a stream.
The string message can be concatenated using the ofToString(const T& value) conversion function:
// Build a single string message.
ofLog(OF_LOG_NOTICE, "the number is "
+ ofToString(10) + " and I have a float too " + ofToString(123.45f));
Parameters:
level The ofLogLevel for this log message.
message The log message.
getChannel()
shared_ptr< ofBaseLoggerChannel > ofLog::getChannel()
Documentation from code comments
Get the current logging channel.
operator<
ofLog & ofLog::operator<
Documentation from code comments
Define flexible stream operator.
This allows the class to use the << std::ostream to catch function
pointers such as std::endl and std::hex.
Parameters:
func A function pointer that takes a std::ostream as an argument.
Returns: A reference to itself.
Documentation from code comments
Define flexible stream operator.
This allows the class to use the << std::ostream to catch function pointers such as std::endl and std::hex.
Parameters:
func A function pointer that takes a std::ostream as an argument.
Returns: A reference to itself.
setAutoSpace(...)
void ofLog::setAutoSpace(bool autoSpace)
Documentation from code comments
Let the logger automaticly add spaces between messages.
Default is false
.
Parameters:
autoSpace Set to true to add spaces between messages
setChannel(...)
void ofLog::setChannel(shared_ptr< ofBaseLoggerChannel > channel)
Sets the logging channel that receives log messages. This is analogous to ofSetLoggerChannel().
See ofSetLoggerChannel() for more detail.
Documentation from code comments
Set the logging channel destinations for messages.
This can be used to output to files instead of stdout.
See also: ofFileLoggerChannel ofConsoleLoggerChannel
Parameters:
channel The channel to log to.
ofGetLogLevel()
ofLogLevel ofGetLogLevel()
Get the current log level. This is useful when combined with ofGetLogLevelName() if you want to print the current log level:
ofLogLevel currentLevel = ofGetLogLevel();
ofLog() << "The current log level is " << ofGetLogLevelName(currentLevel);
Documentation from code comments
Get the currently set global logging level.
Returns: The currently set global logging level.
ofGetLogLevel(...)
ofLogLevel ofGetLogLevel(string module)
Documentation from code comments
Get the logging level for a specific module.
Parameters:
module specific module name.
Returns: The currently set specific module logging level.
ofGetLogLevelName(...)
string ofGetLogLevelName(ofLogLevel level, bool pad=false)
Documentation from code comments
Get log level name as a string.
Parameters:
level The ofLogLevel you want as a string.
pad True if you want all log level names to be the same length.
Returns: The log level name as a string.
ofGetLoggerChannel()
shared_ptr< ofBaseLoggerChannel > ofGetLoggerChannel()
Documentation from code comments
Get the current logger channel.
ofLogToConsole()
void ofLogToConsole()
Documentation from code comments
Set the logging to ouptut to the console.
This is the default state and can be called to reset console logging after ofLogToFile or ofSetLoggerChannel has been called.
ofLogToFile(...)
void ofLogToFile(const filesystem::path &path, bool append=false)
Enable logging to a file instead of the console. Set the path and name of the log file and it will be created if it doesn't exist. If it does exist, it will be overwritten unless you set append to true, whereas new lines will be added to the bottom of the file.
// logs to the console
ofLog() << "a test string";
// enable file logging, append text
// the log file will be created in the data directory
ofLogToFile("myLogFile.txt", true);
// now logs to the file
ofLog() << "a test string";
Note: When file logging is enabled, will not see log messages on the console!
Documentation from code comments
Set the logging to output to a file instead of the console.
Parameters:
path The path to the log file to use.
append True if you want to append to the existing file.
ofSetLogLevel(...)
void ofSetLogLevel(ofLogLevel level)
Sets the logging level so only messages above a certain priority are shown. This is useful if you want see lots of messages when debugging, but then set a higher level so only warnings and errors appear for users. logLevel values are (in order of priority): OF_LOG_VERBOSE OF_LOG_NOTICE OF_LOG_WARNING OF_LOG_ERROR OF_LOG_FATAL_ERROR OF_LOG_SILENT Following priority, setting a log level of OF_LOG_ERROR, means only error & fatal error messages will be printed. Conversely, setting OF_LOG_VERBOSE means all log level messages will be printed. Here's a code example:
// set to warning level
ofSetLogLevel(OF_LOG_WARNING);
ofLogWarning() << "a warning print"; // this prints
ofLogNotice() << "test print"; // this doesn't
ofLogVerbose() << "a verbose print"; // this doesn't either
// set to notice level
ofSetLogLevel(OF_LOG_NOTICE);
ofLogWarning() << "a warning print"; // this still prints
ofLogNotice() << "test print"; // this does too
ofLogVerbose() << "a verbose print"; // this doesn't
The default log level is OF_LOG_NOTICE. OF_LOG_SILENT is a special value which disables all messages.
Documentation from code comments
Sets the logging level to selectively show log messages.
This is useful if you want see lots of messages when debugging, but then set a higher level so only warnings and errors appear for users.
ofLogLevel values in order from lowest to highest level are:
- OF_LOG_VERBOSE
(lowest level)
- OF_LOG_NOTICE
- OF_LOG_WARNING
- OF_LOG_ERROR
- OF_LOG_FATAL_ERROR
- OF_LOG_SILENT
(highest level)
Thus, setting a log level of OF_LOG_ERROR
, means only logging messages
marked OF_LOG_ERROR and OF_LOG_FATAL_ERROR will be printed. Conversely,
setting OF_LOG_VERBOSE means all log level messages, including
OF_LOG_VERBOSE, will be printed. Finally, setting a log level of
OF_LOG_SILENT will prevent any messages from being printed.
The default ofLogLevel is OF_LOG_NOTICE
.
Parameters:
level the ofLogLevel (and below) you want to show
ofSetLogLevel(...)
void ofSetLogLevel(string module, ofLogLevel level)
Documentation from code comments
Set the logging level for a specific module.
When a module name is supplied to ofSetLogLevel, the provided ofLogLevel is selectively applied only to ofLog messages marked with the specified module.
This is particularly useful when the user desires to, for example, log at an OF_LOG_VERBOSE level for one module and then log at OF_LOG_ERROR for another module.
Example of logging to a specific module:
// Set the default log level for all logging.
ofSetLogLevel(OF_LOG_ERROR);
// Selectively enable verbose logging for the MyClass module.
ofSetLogLevel("MyClass", OF_LOG_VERBOSE);
// If we then log the following ...
// Log a vermose message to a module called "MyClass".
ofLogVerbose("MyClass") << "A verbose message from MyClass.";
// Log a verbose message to a module called "MyOtherClass".
ofLogVerbose("MyOtherClass") << "A verbose message from MyOtherClass.";
// In this case, we will see the verbose message from "MyClass", but not
// the message from "MyOtherClass".
ofSetLoggerChannel(...)
void ofSetLoggerChannel(shared_ptr< ofBaseLoggerChannel > loggerChannel)
Documentation from code comments
Set the logger to use a custom logger channel.
Custom logger channels must extend ofBaseLoggerChannel. Custom log channels can be useful for combining logging methods, logging to a server, logging to email or even Twitter.
Parameters:
loggerChannel A shared pointer to the logger channel.
Last updated Saturday, 17 August 2024 20:48:02 UTC - 99bfb4fd7929e233b87b05758efc36f91505592e
If you have any doubt about the usage of this module you can ask in the forum.
If you want to contribute better documentation or start documenting this section you can do so here
If you find anything wrong with this docs you can report any error by opening an issue