Logging

Description

OMNeT++ provides a logging mechanism for models, with support for log levels, filtering, a configurable log prefix, and more.

See EV_LOG() for an overview.

If you are encountering compile errors, see also EV_STATICCONTEXT.

Classes
class	cLog
	This class groups logging related functionality. More...

Macros
#define	COMPILETIME_LOGLEVEL   omnetpp::LOGLEVEL_TRACE
	For compile-time filtering of logs. More...
#define	COMPILETIME_LOG_PREDICATE(object, logLevel, category)   (::omnetpp::defaultCompiletimeLogPredicate(logLevel, COMPILETIME_LOGLEVEL))
	This predicate determines if a log statement gets compiled into the executable. More...
#define	EV_STATICCONTEXT
	Use this macro when logging from static member functions. More...
#define	EV_LOG(logLevel, category)
	This is the macro underlying EV_INFO, EV_DETAIL, EV_INFO_C, and similar log macros. More...
#define	EV   EV_INFO
	Short for EV_INFO. More...
#define	EV_FATAL
	Pseudo-stream for logging local fatal errors. See EV_LOG for details. More...
#define	EV_ERROR
	Pseudo-stream for logging local recoverable errors. See EV_LOG for details. More...
#define	EV_WARN
	Pseudo-stream for logging warnings. See EV_LOG for details. More...
#define	EV_INFO
	Pseudo-stream for logging information with the default log level. See EV_LOG for details. More...
#define	EV_DETAIL
	Pseudo-stream for logging low-level protocol-specific details. See EV_LOG for details. More...
#define	EV_DEBUG
	Pseudo-stream for logging state variables and other low-level information. See EV_LOG for details. More...
#define	EV_TRACE
	Pseudo-stream for logging control flow information (entering/exiting functions, etc). See EV_LOG for details. More...
#define	EV_C(category)   EV_INFO_C(category)
	Short for EV_INFO_C. More...
#define	EV_FATAL_C(category)
	Pseudo-stream for logging local fatal errors of a specific category. See EV_LOG for details. More...
#define	EV_ERROR_C(category)
	Pseudo-stream for logging local recoverable errors of a specific category. See EV_LOG for details. More...
#define	EV_WARN_C(category)
	Pseudo-stream for logging warnings of a specific category. See EV_LOG for details. More...
#define	EV_INFO_C(category)
	Pseudo-stream for logging information with the default log level of a specific category. See EV_LOG for details. More...
#define	EV_DETAIL_C(category)
	Pseudo-stream for logging low-level protocol-specific details of a specific category. See EV_LOG for details. More...
#define	EV_DEBUG_C(category)
	Pseudo-stream for logging state variables and other low-level information of a specific category. See EV_LOG for details. More...
#define	EV_TRACE_C(category)
	Pseudo-stream for logging control flow information (entering/exiting functions, etc) of a specific category. See EV_LOG for details. More...

Enumerations
enum	LogLevel {   LOGLEVEL_TRACE, LOGLEVEL_DEBUG, LOGLEVEL_DETAIL, LOGLEVEL_INFO,   LOGLEVEL_WARN, LOGLEVEL_ERROR, LOGLEVEL_FATAL, LOGLEVEL_OFF,   LOGLEVEL_NOTSET = -1 }
	Classifies log messages based on detail and importance. More...

Macro Definition Documentation

COMPILETIME_LOGLEVEL

#define COMPILETIME_LOGLEVEL   omnetpp::LOGLEVEL_TRACE

For compile-time filtering of logs.

One is free to define this macro before including <omnetpp.h>, or redefine it any time. The change will affect subsequent log statements. Log statements that use lower log levels than the one specified by this macro will not be compiled into the executable.

COMPILETIME_LOG_PREDICATE

#define COMPILETIME_LOG_PREDICATE	(		object,
			logLevel,
			category
	)		(::omnetpp::defaultCompiletimeLogPredicate(logLevel, COMPILETIME_LOGLEVEL))

This predicate determines if a log statement gets compiled into the executable.

One is free to define this macro before including <omnetpp.h>, or redefine it any time. The change will affect subsequent log statements.

EV_STATICCONTEXT

#define EV_STATICCONTEXT

Use this macro when logging from static member functions.

Background: EV_LOG and derived macros (EV_INFO, EV_DETAIL, etc) will fail to compile when placed into static member functions of cObject-derived classes ("cannot call member function 'cObject::getThisPtr()' without object" in GNU C++, and "C2352: illegal call of non-static member function" in Visual C++). To fix it, add this macro at the top of the function; it contains local declarations to make the code compile.

EV_LOG

#define EV_LOG	(		logLevel,
			category
	)

This is the macro underlying EV_INFO, EV_DETAIL, EV_INFO_C, and similar log macros.

This macro should not be used directly, but via the logging macros EV, EV_FATAL, EV_ERROR, EV_WARN, EV_INFO, EV_DETAIL, EV_DEBUG, EV_TRACE, and their "category" versions EV_C, EV_FATAL_C, EV_ERROR_C, EV_WARN_C, EV_INFO_C, EV_DETAIL_C, EV_DEBUG_C, EV_TRACE_C.

Those macros act as C++ streams: one can write on them using the left-shift (<<) operator. Their names refer to the log level they represent (see LogLevel). The "category" (_C) versions accept a category string. Each category acts like a separate log channel; for example, one can use the "test" category to log text intended for consumption by an automated test suite.

Log statements are wrapped with compile-time and runtime guards at the call site to efficiently prevent unnecessary computation of parameters and log content. Compile-time guards are COMPILETIME_LOGLEVEL and COMPILETIME_LOG_PREDICATE. Runtime guards (runtime log level) can be set up via omnetpp.ini.

Under certain circumstances, compiling log statements may result in errors. When that happens, it is possible that the EV_STATICCONTEXT macro needs to be added to the code; please review its documentation for more info.

Examples:

EV << "Connection setup complete" << endl;  // equivalent to EV_INFO << ...
EV_DEBUG << "retryCount=" << retryCount << std::endl;
EV_WARNING << "Connection timed out\n";
EV_INFO_C("testing") << "ESTAB" << endl;

See also

LogLevel, EV_STATICCONTEXT, EV_INFO, EV_INFO_C, COMPILETIME_LOGLEVEL, COMPILETIME_LOG_PREDICATE

EV

#define EV   EV_INFO

Short for EV_INFO.

See also

EV_INFO

EV_FATAL

#define EV_FATAL

Pseudo-stream for logging local fatal errors. See EV_LOG for details.

See also

EV_LOG

EV_ERROR

#define EV_ERROR

Pseudo-stream for logging local recoverable errors. See EV_LOG for details.

See also

EV_LOG

EV_WARN

#define EV_WARN

Pseudo-stream for logging warnings. See EV_LOG for details.

See also

EV_LOG

EV_INFO

#define EV_INFO

Pseudo-stream for logging information with the default log level. See EV_LOG for details.

See also

EV_LOG

EV_DETAIL

#define EV_DETAIL

Pseudo-stream for logging low-level protocol-specific details. See EV_LOG for details.

See also

EV_LOG

EV_DEBUG

#define EV_DEBUG

Pseudo-stream for logging state variables and other low-level information. See EV_LOG for details.

See also

EV_LOG

EV_TRACE

#define EV_TRACE

Pseudo-stream for logging control flow information (entering/exiting functions, etc). See EV_LOG for details.

See also

EV_LOG

EV_C

#define EV_C

(

category

)

EV_INFO_C(category)

Short for EV_INFO_C.

See also

EV_INFO_C

EV_FATAL_C

#define EV_FATAL_C

(

category

)

Pseudo-stream for logging local fatal errors of a specific category. See EV_LOG for details.

See also

EV_LOG

EV_ERROR_C

#define EV_ERROR_C

(

category

)

Pseudo-stream for logging local recoverable errors of a specific category. See EV_LOG for details.

See also

EV_LOG

EV_WARN_C

#define EV_WARN_C

(

category

)

Pseudo-stream for logging warnings of a specific category. See EV_LOG for details.

See also

EV_LOG

EV_INFO_C

#define EV_INFO_C

(

category

)

Pseudo-stream for logging information with the default log level of a specific category. See EV_LOG for details.

See also

EV_LOG

EV_DETAIL_C

#define EV_DETAIL_C

(

category

)

Pseudo-stream for logging low-level protocol-specific details of a specific category. See EV_LOG for details.

See also

EV_LOG

EV_DEBUG_C

#define EV_DEBUG_C

(

category

)

Pseudo-stream for logging state variables and other low-level information of a specific category. See EV_LOG for details.

See also

EV_LOG

EV_TRACE_C

#define EV_TRACE_C

(

category

)

Pseudo-stream for logging control flow information (entering/exiting functions, etc) of a specific category. See EV_LOG for details.

See also

EV_LOG

Enumeration Type Documentation

LogLevel

enum LogLevel

Classifies log messages based on detail and importance.

Enumerator
LOGLEVEL_TRACE	The lowest log level; it should be used for low-level implementation-specific technical details that are mostly useful for the developers/maintainers of the component. For example, a MAC layer protocol component could log control flow in loops and if statements, entering/leaving methods and code blocks using this log level.
LOGLEVEL_DEBUG	This log level should be used for high-level implementation-specific technical details that are most likely important for the developers/maintainers of the component. These messages may help to debug various issues when one is looking at the code. For example, a MAC layer protocol component could log updates to internal state variables, updates to complex data structures using this log level.
LOGLEVEL_DETAIL	This log level should be used for low-level protocol-specific details that may be useful and understandable by the users of the component. These messages may help to track down various protocol-specific issues without actually looking too deep into the code. For example, a MAC layer protocol component could log state machine updates, acknowledge timeouts and selected back-off periods using this level.
LOGLEVEL_INFO	This log level should be used for high-level protocol specific details that are most likely important for the users of the component. For example, a MAC layer protocol component could log successful packet receptions and successful packet transmissions using this level.
LOGLEVEL_WARN	This log level should be used for exceptional (non-error) situations that may be important for users and rarely occur in the component. For example, a MAC layer protocol component could log detected bit errors using this level.
LOGLEVEL_ERROR	This log level should be used for recoverable (non-fatal) errors that allow the component to continue normal operation. For example, a MAC layer protocol component could log unsuccessful packet receptions and unsuccessful packet transmissions using this level.
LOGLEVEL_FATAL	The highest log level; it should be used for fatal (unrecoverable) errors that prevent the component from further operation. It doesn't mean that the simulation must stop immediately (because in such cases the code should throw a cRuntimeError), but rather that the a component is unable to continue normal operation. For example, a special purpose recording component may be unable to continue recording due to the disk being full.
LOGLEVEL_OFF	Not a real log level, it completely disables logging when set.
LOGLEVEL_NOTSET	Not a real log level, used for indicating the absence of a log level setting.