reference

This documentation is automatically generated from the openFrameworks source code using doxygen and refers to the most recent release, version 0.12.0.

ofLog.h File Reference
#include "ofFileUtils.h"
#include "ofConstants.h"
#include "ofUtils.h"
#include <sstream>

Go to the source code of this file.

Classes

class  ofLog
 A C++ stream-style logging interface. More...
 
class  ofLogVerbose
 Derived log class for easy verbose logging. More...
 
class  ofLogNotice
 Derived log class for easy notice logging. More...
 
class  ofLogWarning
 Derived log class for easy warning logging. More...
 
class  ofLogError
 Derived log class for easy error logging. More...
 
class  ofLogFatalError
 Derived log class for easy fatal error logging. More...
 

Functions

Global logger channel
void ofLogToFile (const of::filesystem::path &path, bool append=false)
 Set the logging to output to a file instead of the console.
 
void ofLogToConsole ()
 Set the logging to ouptut to the console.
 
void ofSetLoggerChannel (std::shared_ptr< ofBaseLoggerChannel > loggerChannel)
 Set the logger to use a custom logger channel.
 
std::shared_ptr< ofBaseLoggerChannel > ofGetLoggerChannel ()
 Get the current logger channel.
 

Global logging level

#define OF_CONSOLE_COLOR_RESTORE   (0)
 
#define OF_CONSOLE_COLOR_BLACK   (30)
 
#define OF_CONSOLE_COLOR_RED   (31)
 
#define OF_CONSOLE_COLOR_GREEN   (32)
 
#define OF_CONSOLE_COLOR_YELLOW   (33)
 
#define OF_CONSOLE_COLOR_BLUE   (34)
 
#define OF_CONSOLE_COLOR_PURPLE   (35)
 
#define OF_CONSOLE_COLOR_CYAN   (36)
 
#define OF_CONSOLE_COLOR_WHITE   (37)
 
enum  ofLogLevel : short {
  OF_LOG_VERBOSE , OF_LOG_NOTICE , OF_LOG_WARNING , OF_LOG_ERROR ,
  OF_LOG_FATAL_ERROR , OF_LOG_SILENT
}
 The supported logging levels. Default is OF_LOG_NOTICE. More...
 
void ofSetLogLevel (ofLogLevel level)
 Sets the logging level to selectively show log messages.
 
void ofSetLogLevel (std::string module, ofLogLevel level)
 Set the logging level for a specific module.
 
ofLogLevel ofGetLogLevel ()
 Get the currently set global logging level.
 
ofLogLevel ofGetLogLevel (std::string module)
 Get the logging level for a specific module.
 
std::string ofGetLogLevelName (ofLogLevel level, bool pad=false)
 Get log level name as a string.
 

Detailed Description

ofLog provides an interface for writing text output from your app. It's basically a more useful version of std::cout or printf where the output can be filtered and written to the console a file, or even a custom logging module.

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 set the logging level so only messages above a certain level 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(ofLogLevel level) for more details.

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);
A C++ stream-style logging interface.
Definition ofLog.h:299
std::string ofToString(const T &)
Convert a value to a string.
Definition ofUtils.h:657
@ OF_LOG_NOTICE
Definition ofLog.h:118

Stream: as a stream using the << stream operator

// The stream style, setting the log level to OF_LOG_WARNING.
ofLog(OF_LOG_WARNING) << "the number is " << 10;
// This is the same as the last line, except it uses the default OF_LOG_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 message."
ofLogNotice() << "A regular notice message.";
ofLogWarning() << "Uh oh, a warning!";
ofLogError() << "Oh no, an error occurred!";
ofLogFatalError() << "Accckkk, a fatal error!!";
Derived log class for easy error logging.
Definition ofLog.h:606
Derived log class for easy fatal error logging.
Definition ofLog.h:628
Derived log class for easy notice logging.
Definition ofLog.h:563
Derived log class for easy verbose logging.
Definition ofLog.h:541
Derived log class for easy warning logging.
Definition ofLog.h:585
@ OF_LOG_WARNING
Definition ofLog.h:119

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(string module, ofLogLevel level) for more details.

Example of logging to a specific module:

// log to a module called "Hello"
ofLogWarning("Hello") << "A warning message.";

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 message.";
// !!! This does not print a message because 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 message.";

Log Message Redirection

It's useful to be able to record log messages to a file or send them to a custom destination.

For log redirection see

Macro Definition Documentation

◆ OF_CONSOLE_COLOR_BLACK

#define OF_CONSOLE_COLOR_BLACK   (30)

◆ OF_CONSOLE_COLOR_BLUE

#define OF_CONSOLE_COLOR_BLUE   (34)

◆ OF_CONSOLE_COLOR_CYAN

#define OF_CONSOLE_COLOR_CYAN   (36)

◆ OF_CONSOLE_COLOR_GREEN

#define OF_CONSOLE_COLOR_GREEN   (32)

◆ OF_CONSOLE_COLOR_PURPLE

#define OF_CONSOLE_COLOR_PURPLE   (35)

◆ OF_CONSOLE_COLOR_RED

#define OF_CONSOLE_COLOR_RED   (31)

◆ OF_CONSOLE_COLOR_RESTORE

#define OF_CONSOLE_COLOR_RESTORE   (0)

◆ OF_CONSOLE_COLOR_WHITE

#define OF_CONSOLE_COLOR_WHITE   (37)

◆ OF_CONSOLE_COLOR_YELLOW

#define OF_CONSOLE_COLOR_YELLOW   (33)

Enumeration Type Documentation

◆ ofLogLevel

enum ofLogLevel : short

The supported logging levels. Default is OF_LOG_NOTICE.

Enumerator
OF_LOG_VERBOSE 
OF_LOG_NOTICE 
OF_LOG_WARNING 
OF_LOG_ERROR 
OF_LOG_FATAL_ERROR 
OF_LOG_SILENT 

ofSetLogLevel(OF_LOG_SILENT).

Function Documentation

◆ ofGetLoggerChannel()

std::shared_ptr< ofBaseLoggerChannel > ofGetLoggerChannel ( )

Get the current logger channel.

◆ ofGetLogLevel() [1/2]

ofLogLevel ofGetLogLevel ( )

Get the currently set global logging level.

Returns
The currently set global logging level.

◆ ofGetLogLevel() [2/2]

ofLogLevel ofGetLogLevel ( std::string  module)

Get the logging level for a specific module.

Parameters
modulespecific module name.
Returns
The currently set specific module logging level.

◆ ofGetLogLevelName()

std::string ofGetLogLevelName ( ofLogLevel  level,
bool  pad = false 
)

Get log level name as a string.

Parameters
levelThe ofLogLevel you want as a string.
padTrue if you want all log level names to be the same length.
Returns
The log level name as a string.

◆ ofLogToConsole()

void ofLogToConsole ( )

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 of::filesystem::path &  path,
bool  append = false 
)

Set the logging to output to a file instead of the console.

Parameters
pathThe path to the log file to use.
appendTrue if you want to append to the existing file.

◆ ofSetLoggerChannel()

void ofSetLoggerChannel ( std::shared_ptr< ofBaseLoggerChannel >  loggerChannel)

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
loggerChannelA shared pointer to the logger channel.

◆ ofSetLogLevel() [1/2]

void ofSetLogLevel ( ofLogLevel  level)

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
levelthe ofLogLevel (and below) you want to show

◆ ofSetLogLevel() [2/2]

void ofSetLogLevel ( std::string  module,
ofLogLevel  level 
)

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.
// Selectively enable verbose logging for the MyClass module.
// 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".
void ofSetLogLevel(ofLogLevel level)
Sets the logging level to selectively show log messages.
Definition ofLog.cpp:40
@ OF_LOG_VERBOSE
Definition ofLog.h:117
@ OF_LOG_ERROR
Definition ofLog.h:120