A Discrete-Event Network Simulator
API

Logging functions and macros. More...

+ Collaboration diagram for Logging:

Files

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.
 

Namespaces

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

Classes

class  ns3::PrintList
 Handler for print-list token in NS_LOG to print the list of log components. 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 & NS_UNUSED_GLOBAL (g_log) = 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 (void)
 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 = 0
 The Log NodePrinter. More...
 
static TimePrinter ns3::g_logTimePrinter = 0
 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 ...

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);

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 107 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); \
std::clog << msg << std::endl; \
} \
} 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);
Parameters
[in]levelThe log level
[in]msgThe message to log
Internal:
Logging implementation macro; should not be called directly.

Definition at line 187 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 146 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 108 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 121 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 96 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_NODE_PREFIX_IMPL

#define NS_LOG_APPEND_NODE_PREFIX_IMPL
Value:
do { \
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 63 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 84 of file log-macros-enabled.h.

◆ NS_LOG_APPEND_TIME_PREFIX_IMPL

#define NS_LOG_APPEND_TIME_PREFIX_IMPL
Value:
do { \
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 45 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 {
// Definitions within the ns3 namespace
} // namespace ns3
using ns3::g_log;
// Further definitions outside of the ns3 namespace
Parameters
[in]nameThe log component name.

Definition at line 205 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]nameThe log component name.
[in]maskThe default mask.

Definition at line 216 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 165 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]msgThe message to log.

Definition at line 273 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]msgThe message to log.

Definition at line 257 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__ << "("; \
ns3::ParameterLogger (std::clog) << parameters; \
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]parametersThe parameters to output.

Definition at line 244 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 209 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]msgThe message to log.

Definition at line 281 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]msgThe message to log.

Definition at line 289 of file log.h.

◆ NS_LOG_STATIC_TEMPLATE_DEFINE

#define NS_LOG_STATIC_TEMPLATE_DEFINE (   name)     static LogComponent & NS_UNUSED_GLOBAL (g_log) = 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]nameThe log component name.

Definition at line 249 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 228 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]nameThe log component name.

Definition at line 239 of file log.h.

◆ NS_LOG_UNCOND

#define NS_LOG_UNCOND (   msg)
Value:
NS_LOG_CONDITION \
do { \
std::clog << msg << std::endl; \
} while (false)

Output the requested message unconditionally.

Parameters
[in]msgThe message to log

Definition at line 269 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]msgThe message to log.

Definition at line 265 of file log.h.

Function Documentation

◆ CheckEnvironmentVariables()

static void ns3::CheckEnvironmentVariables ( void  )
static

Parse the NS_LOG environment variable.

This is private to the logging implementation.

Definition at line 528 of file log.cc.

References ns3::ComponentExists(), ns3::LogComponentPrintList(), and NS_FATAL_ERROR.

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]componentNameThe putative log component name.
Returns
true if componentName exists.

Definition at line 504 of file log.cc.

References ns3::LogComponent::GetComponentList(), and NS_ASSERT.

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]osThe output stream to print the node id on.

Definition at line 38 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 = 0
static

The Log NodePrinter.

Definition at line 52 of file log.cc.

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

◆ g_logTimePrinter

TimePrinter ns3::g_logTimePrinter = 0
static

The Log TimePrinter.

This is private to the logging implementation.

Definition at line 47 of file log.cc.

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

NS_LOG_COMPONENT_DEFINE
#define NS_LOG_COMPONENT_DEFINE(name)
Define a Log component with a specific name.
Definition: log.h:205
ns3::LOG_FUNCTION
@ LOG_FUNCTION
Function tracing.
Definition: log.h:109
ns3
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::LOG_PREFIX_NODE
@ LOG_PREFIX_NODE
Prefix all trace prints with simulation node.
Definition: log.h:120
NS_LOG
#define NS_LOG(level, msg)
This macro allows you to log an arbitrary message at a specific log level.
Definition: log-macros-enabled.h:187
ns3::LogGetNodePrinter
NodePrinter LogGetNodePrinter(void)
Get the LogNodePrinter function currently in use.
Definition: log.cc:638
ns3::LOG_PREFIX_LEVEL
@ LOG_PREFIX_LEVEL
Prefix all trace prints with log level (severity).
Definition: log.h:121
ns3::LogGetTimePrinter
TimePrinter LogGetTimePrinter(void)
Get the LogTimePrinter function currently in use.
Definition: log.cc:629
ns3::LOG_PREFIX_TIME
@ LOG_PREFIX_TIME
Prefix all trace prints with simulation time.
Definition: log.h:119
ns3::LOG_PREFIX_FUNC
@ LOG_PREFIX_FUNC
Prefix all trace prints with function.
Definition: log.h:118
ns3::NodePrinter
void(* NodePrinter)(std::ostream &os)
Function signature for prepending the node id to a log message.
Definition: node-printer.h:40
ns3::TimePrinter
void(* TimePrinter)(std::ostream &os)
Function signature for features requiring a time formatter, such as logging or ShowProgress.
Definition: time-printer.h:43
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:244
ns3::LOG_DEBUG
@ LOG_DEBUG
Rare ad-hoc debug messages.
Definition: log.h:103