Logging functions and macros. More...

Collaboration diagram for Logging:

Files
file	log-example.cc
	Example program illustrating the various logging functions.

file	log-macros-disabled.h
	Definition of empty logging macros and the NS_LOG_NOOP_INTERNAL macro.

file	log-macros-enabled.h
	NS_LOG and related logging macro definitions.

file	log.cc
	ns3::LogComponent and related implementations.

file	log.h
	Debug message logging.

file	node-printer.h
	Declaration of ns3::NodePrinter function pointer type and ns3::DefaultNodePrinter function.

file	sample-log-time-format.cc
	Example program that demonstrates how to replace the time printer.

file	sample-show-progress.cc
	Example program that demonstrates ShowProgress.

Classes
class	ns3::PrintList
	Handler for the undocumented `print-list` token in NS_LOG which triggers printing of the list of log components, then exits. More...

Macros
#define	NS_LOG(level, msg)
	This macro allows you to log an arbitrary message at a specific log level. More...

#define	NS_LOG_APPEND_CONTEXT
	Append the node id (or other file-local programmatic context, such as MPI rank) to a log message. More...

#define	NS_LOG_APPEND_FUNC_PREFIX
	Append the function name to a log message. More...

#define	NS_LOG_APPEND_LEVEL_PREFIX(level)
	Append the log severity level to a log message. More...

#define	NS_LOG_APPEND_NODE_PREFIX
	Append the simulation node id to a log message. More...

#define	NS_LOG_APPEND_NODE_PREFIX_IMPL
	Implementation details for NS_LOG_APPEND_NODE_PREFIX. More...

#define	NS_LOG_APPEND_TIME_PREFIX
	Append the simulation time to a log message. More...

#define	NS_LOG_APPEND_TIME_PREFIX_IMPL
	Implementation details for NS_LOG_APPEND_TIME_PREFIX. More...

#define	NS_LOG_COMPONENT_DEFINE(name) static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__)
	Define a Log component with a specific name. More...

#define	NS_LOG_COMPONENT_DEFINE_MASK(name, mask) static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__, mask)
	Define a logging component with a mask. More...

#define	NS_LOG_CONDITION
	Limit logging output based on some file-local condition, such as MPI rank. More...

#define	NS_LOG_DEBUG(msg) NS_LOG(ns3::LOG_DEBUG, msg)
	Use NS_LOG to output a message of level LOG_DEBUG. More...

#define	NS_LOG_ERROR(msg) NS_LOG(ns3::LOG_ERROR, msg)
	Use NS_LOG to output a message of level LOG_ERROR. More...

#define	NS_LOG_FUNCTION(parameters)
	If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ", ". More...

#define	NS_LOG_FUNCTION_NOARGS()
	Output the name of the function. More...

#define	NS_LOG_INFO(msg) NS_LOG(ns3::LOG_INFO, msg)
	Use NS_LOG to output a message of level LOG_INFO. More...

#define	NS_LOG_LOGIC(msg) NS_LOG(ns3::LOG_LOGIC, msg)
	Use NS_LOG to output a message of level LOG_LOGIC. More...

#define	NS_LOG_STATIC_TEMPLATE_DEFINE(name) static LogComponent& g_log [[maybe_unused]] = GetLogComponent(name)
	Declare and initialize a reference to a Log component. More...

#define	NS_LOG_TEMPLATE_DECLARE LogComponent& g_log
	Declare a reference to a Log component. More...

#define	NS_LOG_TEMPLATE_DEFINE(name) g_log(GetLogComponent(name))
	Initialize a reference to a Log component. More...

#define	NS_LOG_UNCOND(msg)
	Output the requested message unconditionally. More...

#define	NS_LOG_WARN(msg) NS_LOG(ns3::LOG_WARN, msg)
	Use NS_LOG to output a message of level LOG_WARN. More...

Functions
static void	ns3::CheckEnvironmentVariables ()
	Parse the `NS_LOG` environment variable. More...

static bool	ns3::ComponentExists (std::string componentName)
	Check if a log component exists. More...

void	ns3::DefaultNodePrinter (std::ostream &os)
	Default node id printer implementation. More...

Variables
static NodePrinter	ns3::g_logNodePrinter = nullptr
	The Log NodePrinter. More...

static TimePrinter	ns3::g_logTimePrinter = nullptr
	The Log TimePrinter. More...

Macros defined by the build system.
These have to be visible for doxygen to document them, so we put them here in a file only seen by doxygen, not the compiler.
#define	NS3_LOG_ENABLE
	Enable logging at compile time. More...

Detailed Description

Logging functions and macros.

LOG functionality: macros which allow developers to send information to the std::clog output stream.

All logging messages are disabled by default. To enable selected logging messages, use the ns3::LogComponentEnable function or use the NS_LOG environment variable

Use the environment variable NS_LOG to define a ':'-separated list of logging components to enable. For example (using bash syntax),

$ NS_LOG="OlsrAgent" ./ns3 run ...

NS_LOG

const char * NS_LOG

Control which logging components are enabled.

Definition: environment-variables.h:159

ns3

Every class exported by the ns3 library is enclosed in the ns3 namespace.

would enable one component at all log levels.

$NS_LOG="OlsrAgent:Ipv4L3Protocol" ./ns3 run ...

would enable two components, at all log levels, etc. NS_LOG="*" will enable all available log components at all levels.

To control more selectively the log levels for each component, use this syntax:

$ NS_LOG='Component1=func|warn:Component2=error|debug'

This example would enable the func, and warn log levels for 'Component1' and the error and debug log levels for 'Component2'. The wildcard '*' can be used here as well. For example NS_LOG='*=level_all|prefix' would enable all log levels and prefix all prints with the component and function names.

A note on NS_LOG_FUNCTION() and NS_LOG_FUNCTION_NOARGS(): generally, use of (at least) NS_LOG_FUNCTION(this) is preferred, with the any function parameters added:

NS_LOG_FUNCTION (this << arg1 << args);

NS_LOG_FUNCTION

#define NS_LOG_FUNCTION(parameters)

If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ",...

Definition: log-macros-enabled.h:240

check-style-clang-format.args

args

Definition: check-style-clang-format.py:754

Use NS_LOG_FUNCTION_NOARGS() only in static functions with no arguments.

Macro Definition Documentation

◆ NS3_LOG_ENABLE

#define NS3_LOG_ENABLE

Enable logging at compile time.

This is normally set by ./ns3 configure --build-profile=debug.

Definition at line 109 of file main.h.

◆ NS_LOG

#define NS_LOG	(	level,
		msg
	)

Value:

    NS_LOG_CONDITION                                                                               \
    do                                                                                             \
    {                                                                                              \
        if (g_log.IsEnabled(level))                                                                \
        {                                                                                          \
            NS_LOG_APPEND_TIME_PREFIX;                                                             \
            NS_LOG_APPEND_NODE_PREFIX;                                                             \
            NS_LOG_APPEND_CONTEXT;                                                                 \
            NS_LOG_APPEND_FUNC_PREFIX;                                                             \
            NS_LOG_APPEND_LEVEL_PREFIX(level);                                                     \
            auto flags = std::clog.setf(std::ios_base::boolalpha);                                 \
            std::clog << msg << std::endl;                                                         \
            std::clog.flags(flags);                                                                \
        }                                                                                          \
    } while (false)

This macro allows you to log an arbitrary message at a specific log level.

The log message is expected to be a C++ ostream message such as "my string" << aNumber << "my oth stream".

Typical usage looks like:

NS_LOG (LOG_DEBUG, "a number="<<aNumber<<", anotherNumber="<<anotherNumber);

ns3::LOG_DEBUG

@ LOG_DEBUG

Full voluminous logging to support debugging.

Definition: log.h:112

Parameters

[in]	level	The log level
[in]	msg	The message to log

Internal:: Logging implementation macro; should not be called directly.

Definition at line 181 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_CONTEXT

#define NS_LOG_APPEND_CONTEXT

Append the node id (or other file-local programmatic context, such as MPI rank) to a log message.

This is implemented locally in .cc files because the relevant variable is only known there.

Preferred format is something like (assuming the node id is accessible from var:

if (var)
  {
    std::clog << "[node " << var->GetObject<Node> ()->GetId () << "] ";
  }

Definition at line 141 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_FUNC_PREFIX

#define NS_LOG_APPEND_FUNC_PREFIX

Value:

    if (g_log.IsEnabled(ns3::LOG_PREFIX_FUNC))                                                     \
    {                                                                                              \
        std::clog << g_log.Name() << ":" << __FUNCTION__ << "(): ";                                \
    }

Append the function name to a log message.

Internal:: Logging implementation macro; should not be called directly.

Definition at line 105 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_LEVEL_PREFIX

#define NS_LOG_APPEND_LEVEL_PREFIX ( level )

Value:

    if (g_log.IsEnabled(ns3::LOG_PREFIX_LEVEL))                                                    \
    {                                                                                              \
        std::clog << "[" << g_log.GetLevelLabel(level) << "] ";                                    \
    }

Append the log severity level to a log message.

Internal:: Logging implementation macro; should not be called directly.

Definition at line 117 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_NODE_PREFIX

#define NS_LOG_APPEND_NODE_PREFIX

Value:

    if (g_log.IsEnabled(ns3::LOG_PREFIX_NODE))                                                     \
    {                                                                                              \
        NS_LOG_APPEND_NODE_PREFIX_IMPL;                                                            \
    }

Append the simulation node id to a log message.

Internal:: Logging implementation macro; should not be called directly.

Definition at line 93 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_NODE_PREFIX_IMPL

#define NS_LOG_APPEND_NODE_PREFIX_IMPL

Value:

    do                                                                                             \
    {                                                                                              \
        ns3::NodePrinter printer = ns3::LogGetNodePrinter();                                       \
        if (printer != 0)                                                                          \
        {                                                                                          \
            (*printer)(std::clog);                                                                 \
            std::clog << " ";                                                                      \
        }                                                                                          \
    } while (false)

Implementation details for NS_LOG_APPEND_NODE_PREFIX.

Internal:: Logging implementation macro; should not be called directly. We define this separately so we can reuse the definition in NS_FATAL.

Definition at line 62 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_TIME_PREFIX

#define NS_LOG_APPEND_TIME_PREFIX

Value:

    if (g_log.IsEnabled(ns3::LOG_PREFIX_TIME))                                                     \
    {                                                                                              \
        NS_LOG_APPEND_TIME_PREFIX_IMPL;                                                            \
    }

Append the simulation time to a log message.

Internal:: Logging implementation macro; should not be called directly.

Definition at line 81 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_TIME_PREFIX_IMPL

#define NS_LOG_APPEND_TIME_PREFIX_IMPL

Value:

    do                                                                                             \
    {                                                                                              \
        ns3::TimePrinter printer = ns3::LogGetTimePrinter();                                       \
        if (printer != 0)                                                                          \
        {                                                                                          \
            (*printer)(std::clog);                                                                 \
            std::clog << " ";                                                                      \
        }                                                                                          \
    } while (false)

Implementation details for NS_LOG_APPEND_TIME_PREFIX.

Internal:: Logging implementation macro; should not be called directly. We define this separately so we can reuse the definition in NS_FATAL.

Definition at line 43 of file log-macros-enabled.h.

◆ NS_LOG_COMPONENT_DEFINE

#define NS_LOG_COMPONENT_DEFINE ( name ) static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__)

Define a Log component with a specific name.

This macro should be used at the top of every file in which you want to use the NS_LOG macro. This macro defines a new "log component" which can be later selectively enabled or disabled with the ns3::LogComponentEnable and ns3::LogComponentDisable functions or with the NS_LOG environment variable.

LogComponent names should be simple string tokens, i.e., "ArfWifiManager", not "ns3::ArfWifiManager".

This macro should be placed within namespace ns3. If functions outside of namespace ns3 require access to logging, the preferred solution is to add the following 'using' directive at file scope, outside of namespace ns3, and after the inclusion of NS_LOG_COMPONENT_DEFINE, such as follows:

namespace ns3 {
  NS_LOG_COMPONENT_DEFINE ("...");
 
  // Definitions within the ns3 namespace
 
} // namespace ns3
 
using ns3::g_log;
 
// Further definitions outside of the ns3 namespace

Parameters

[in] name The log component name.

Definition at line 202 of file log.h.

◆ NS_LOG_COMPONENT_DEFINE_MASK

#define NS_LOG_COMPONENT_DEFINE_MASK	(	name,
		mask
	)	static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__, mask)

Define a logging component with a mask.

See LogComponent().

Parameters

[in]	name	The log component name.
[in]	mask	The default mask.

Definition at line 213 of file log.h.

◆ NS_LOG_CONDITION

#define NS_LOG_CONDITION

Limit logging output based on some file-local condition, such as MPI rank.

This is implemented locally in .cc files because the relevant condition variable is only known there.

Since this appears immediately before the do { ... } while false construct of NS_LOG(level, msg), it must have the form

#define NS_LOG_CONDITION if (condition)

Definition at line 159 of file log-macros-enabled.h.

◆ NS_LOG_DEBUG

#define NS_LOG_DEBUG ( msg ) NS_LOG(ns3::LOG_DEBUG, msg)

Use NS_LOG to output a message of level LOG_DEBUG.

Parameters

[in] msg The message to log.

Definition at line 268 of file log.h.

◆ NS_LOG_ERROR

#define NS_LOG_ERROR ( msg ) NS_LOG(ns3::LOG_ERROR, msg)

Use NS_LOG to output a message of level LOG_ERROR.

Parameters

[in] msg The message to log.

Definition at line 254 of file log.h.

◆ NS_LOG_FUNCTION

#define NS_LOG_FUNCTION ( parameters )

Value:

    NS_LOG_CONDITION                                                                               \
    do                                                                                             \
    {                                                                                              \
        if (g_log.IsEnabled(ns3::LOG_FUNCTION))                                                    \
        {                                                                                          \
            NS_LOG_APPEND_TIME_PREFIX;                                                             \
            NS_LOG_APPEND_NODE_PREFIX;                                                             \
            NS_LOG_APPEND_CONTEXT;                                                                 \
            std::clog << g_log.Name() << ":" << __FUNCTION__ << "(";                               \
            auto flags = std::clog.setf(std::ios_base::boolalpha);                                 \
            ns3::ParameterLogger(std::clog) << parameters;                                         \
            std::clog.flags(flags);                                                                \
            std::clog << ")" << std::endl;                                                         \
        }                                                                                          \
    } while (false)

If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ", ".

Typical usage looks like:

NS_LOG_FUNCTION (aNumber<<anotherNumber);

And the output will look like:

Component:Function (aNumber, anotherNumber)

To facilitate function tracing, most functions should begin with (at least) NS_LOG_FUNCTION(this). Static functions should use NS_LOG_FUNCTION_NOARGS() instead.

Parameters

[in] parameters The parameters to output.

Definition at line 240 of file log-macros-enabled.h.

◆ NS_LOG_FUNCTION_NOARGS

#define NS_LOG_FUNCTION_NOARGS ( )

Value:

    NS_LOG_CONDITION                                                                               \
    do                                                                                             \
    {                                                                                              \
        if (g_log.IsEnabled(ns3::LOG_FUNCTION))                                                    \
        {                                                                                          \
            NS_LOG_APPEND_TIME_PREFIX;                                                             \
            NS_LOG_APPEND_NODE_PREFIX;                                                             \
            NS_LOG_APPEND_CONTEXT;                                                                 \
            std::clog << g_log.Name() << ":" << __FUNCTION__ << "()" << std::endl;                 \
        }                                                                                          \
    } while (false)

Output the name of the function.

This should be used only in static functions; most member functions should instead use NS_LOG_FUNCTION().

Definition at line 206 of file log-macros-enabled.h.

◆ NS_LOG_INFO

#define NS_LOG_INFO ( msg ) NS_LOG(ns3::LOG_INFO, msg)

Use NS_LOG to output a message of level LOG_INFO.

Parameters

[in] msg The message to log.

Definition at line 275 of file log.h.

◆ NS_LOG_LOGIC

#define NS_LOG_LOGIC ( msg ) NS_LOG(ns3::LOG_LOGIC, msg)

Use NS_LOG to output a message of level LOG_LOGIC.

Parameters

[in] msg The message to log.

Definition at line 282 of file log.h.

◆ NS_LOG_STATIC_TEMPLATE_DEFINE

#define NS_LOG_STATIC_TEMPLATE_DEFINE ( name ) static LogComponent& g_log [[maybe_unused]] = GetLogComponent(name)

Declare and initialize a reference to a Log component.

This macro should be used in static template methods to allow their methods (defined in an header file) to make use of the NS_LOG_* macros.

Parameters

[in] name The log component name.

Definition at line 246 of file log.h.

◆ NS_LOG_TEMPLATE_DECLARE

#define NS_LOG_TEMPLATE_DECLARE LogComponent& g_log

Declare a reference to a Log component.

This macro should be used in the declaration of template classes to allow their methods (defined in an header file) to make use of the NS_LOG_* macros. This macro should be used in the private section to prevent subclasses from using the same log component as the base class.

Definition at line 225 of file log.h.

◆ NS_LOG_TEMPLATE_DEFINE

#define NS_LOG_TEMPLATE_DEFINE ( name ) g_log(GetLogComponent(name))

Initialize a reference to a Log component.

This macro should be used in the constructor of template classes to allow their methods (defined in an header file) to make use of the NS_LOG_* macros.

Parameters

[in] name The log component name.

Definition at line 236 of file log.h.

◆ NS_LOG_UNCOND

#define NS_LOG_UNCOND ( msg )

Value:

    NS_LOG_CONDITION                                                                               \
    do                                                                                             \
    {                                                                                              \
        auto flags = std::clog.setf(std::ios_base::boolalpha);                                     \
        std::clog << msg << std::endl;                                                             \
        std::clog.flags(flags);                                                                    \
    } while (false)

Output the requested message unconditionally.

Parameters

[in] msg The message to log

Definition at line 264 of file log-macros-enabled.h.

◆ NS_LOG_WARN

#define NS_LOG_WARN ( msg ) NS_LOG(ns3::LOG_WARN, msg)

Use NS_LOG to output a message of level LOG_WARN.

Parameters

[in] msg The message to log.

Definition at line 261 of file log.h.

Function Documentation

◆ CheckEnvironmentVariables()

static void ns3::CheckEnvironmentVariables ( )

static

Parse the NS_LOG environment variable.

This is private to the logging implementation.

Definition at line 451 of file log.cc.

References ns3::ComponentExists(), ns3::EnvironmentVariable::GetDictionary(), anonymous_namespace{log.cc}::LOG_LABEL_LEVELS, ns3::LogComponentPrintList(), NS_FATAL_ERROR, NS_LOG_UNCOND, and ns3::SplitString().

Referenced by ns3::LogSetTimePrinter().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ComponentExists()

static bool ns3::ComponentExists ( std::string componentName )

static

Check if a log component exists.

This is private to the logging implementation.

Parameters

[in] componentName The putative log component name.

Returns: true if componentName exists.

Definition at line 438 of file log.cc.

References ns3::LogComponent::GetComponentList().

Referenced by ns3::CheckEnvironmentVariables().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DefaultNodePrinter()

void ns3::DefaultNodePrinter ( std::ostream & os )

Default node id printer implementation.

Parameters

[in,out] os The output stream to print the node id on.

Definition at line 39 of file node-printer.cc.

References ns3::Simulator::GetContext(), and ns3::Simulator::NO_CONTEXT.

Referenced by ns3::GetImpl(), and ns3::Simulator::SetImplementation().

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ g_logNodePrinter

NodePrinter ns3::g_logNodePrinter = nullptr

static

The Log NodePrinter.

Definition at line 116 of file log.cc.

Referenced by ns3::LogGetNodePrinter(), and ns3::LogSetNodePrinter().

◆ g_logTimePrinter

TimePrinter ns3::g_logTimePrinter = nullptr

static

The Log TimePrinter.

This is private to the logging implementation.

Definition at line 111 of file log.cc.

Referenced by ns3::LogGetTimePrinter(), and ns3::LogSetTimePrinter().

Files

Classes

Macros

Functions

Variables

Macros defined by the build system.

Detailed Description

Macro Definition Documentation

◆ NS3_LOG_ENABLE

◆ NS_LOG

◆ NS_LOG_APPEND_CONTEXT

◆ NS_LOG_APPEND_FUNC_PREFIX

◆ NS_LOG_APPEND_LEVEL_PREFIX

◆ NS_LOG_APPEND_NODE_PREFIX

◆ NS_LOG_APPEND_NODE_PREFIX_IMPL

◆ NS_LOG_APPEND_TIME_PREFIX

◆ NS_LOG_APPEND_TIME_PREFIX_IMPL

◆ NS_LOG_COMPONENT_DEFINE

◆ NS_LOG_COMPONENT_DEFINE_MASK

◆ NS_LOG_CONDITION

◆ NS_LOG_DEBUG

◆ NS_LOG_ERROR

◆ NS_LOG_FUNCTION

◆ NS_LOG_FUNCTION_NOARGS

◆ NS_LOG_INFO

◆ NS_LOG_LOGIC

◆ NS_LOG_STATIC_TEMPLATE_DEFINE

◆ NS_LOG_TEMPLATE_DECLARE

◆ NS_LOG_TEMPLATE_DEFINE

◆ NS_LOG_UNCOND

◆ NS_LOG_WARN

Function Documentation

◆ CheckEnvironmentVariables()

◆ ComponentExists()

◆ DefaultNodePrinter()

Variable Documentation

◆ g_logNodePrinter

◆ g_logTimePrinter