Logging functions and macros. More...
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. | |
Namespaces | |
namespace | anonymous_namespace{log.cc} |
Unnamed namespace for log.cc. | |
namespace | ns3 |
Every class exported by the ns3 library is enclosed in the ns3 namespace. | |
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. | |
#define | NS_LOG_APPEND_CONTEXT |
Append the node id (or other file-local programmatic context, such as MPI rank) to a log message. | |
#define | NS_LOG_APPEND_FUNC_PREFIX |
Append the function name to a log message. | |
#define | NS_LOG_APPEND_LEVEL_PREFIX(level) |
Append the log severity level to a log message. | |
#define | NS_LOG_APPEND_NODE_PREFIX |
Append the simulation node id to a log message. | |
#define | NS_LOG_APPEND_NODE_PREFIX_IMPL |
Implementation details for NS_LOG_APPEND_NODE_PREFIX. | |
#define | NS_LOG_APPEND_TIME_PREFIX |
Append the simulation time to a log message. | |
#define | NS_LOG_APPEND_TIME_PREFIX_IMPL |
Implementation details for NS_LOG_APPEND_TIME_PREFIX. | |
#define | NS_LOG_COMPONENT_DEFINE(name) static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__) |
Define a Log component with a specific name. | |
#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. | |
#define | NS_LOG_CONDITION |
Limit logging output based on some file-local condition, such as MPI rank. | |
#define | NS_LOG_DEBUG(msg) NS_LOG(ns3::LOG_DEBUG, msg) |
Use NS_LOG to output a message of level LOG_DEBUG. | |
#define | NS_LOG_ERROR(msg) NS_LOG(ns3::LOG_ERROR, msg) |
Use NS_LOG to output a message of level LOG_ERROR. | |
#define | NS_LOG_FUNCTION(parameters) |
If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ", ". | |
#define | NS_LOG_FUNCTION_NOARGS() |
Output the name of the function. | |
#define | NS_LOG_INFO(msg) NS_LOG(ns3::LOG_INFO, msg) |
Use NS_LOG to output a message of level LOG_INFO. | |
#define | NS_LOG_LOGIC(msg) NS_LOG(ns3::LOG_LOGIC, msg) |
Use NS_LOG to output a message of level LOG_LOGIC. | |
#define | NS_LOG_STATIC_TEMPLATE_DEFINE(name) static LogComponent& g_log [[maybe_unused]] = GetLogComponent(name) |
Declare and initialize a reference to a Log component. | |
#define | NS_LOG_TEMPLATE_DECLARE LogComponent& g_log |
Declare a reference to a Log component. | |
#define | NS_LOG_TEMPLATE_DEFINE(name) g_log(GetLogComponent(name)) |
Initialize a reference to a Log component. | |
#define | NS_LOG_UNCOND(msg) |
Output the requested message unconditionally. | |
#define | NS_LOG_WARN(msg) NS_LOG(ns3::LOG_WARN, msg) |
Use NS_LOG to output a message of level LOG_WARN. | |
Functions | |
static void | ns3::CheckEnvironmentVariables () |
Parse the NS_LOG environment variable. | |
static bool | ns3::ComponentExists (std::string componentName) |
Check if a log component exists. | |
void | ns3::DefaultNodePrinter (std::ostream &os) |
Default node id printer implementation. | |
Variables | |
static NodePrinter | ns3::g_logNodePrinter = nullptr |
The Log NodePrinter. | |
static TimePrinter | ns3::g_logTimePrinter = nullptr |
The Log TimePrinter. | |
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. | |
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),
would enable one component at all log levels.
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:
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:
Use NS_LOG_FUNCTION_NOARGS() only in static functions with no arguments.
#define NS3_LOG_ENABLE |
#define NS_LOG | ( | level, | |
msg | |||
) |
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:
[in] | level | The log level |
[in] | msg | The message to log |
Definition at line 181 of file log-macros-enabled.h.
#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
:
Definition at line 141 of file log-macros-enabled.h.
#define NS_LOG_APPEND_FUNC_PREFIX |
Append the function name to a log message.
Definition at line 105 of file log-macros-enabled.h.
#define NS_LOG_APPEND_LEVEL_PREFIX | ( | level | ) |
Append the log severity level to a log message.
Definition at line 117 of file log-macros-enabled.h.
#define NS_LOG_APPEND_NODE_PREFIX |
Append the simulation node id to a log message.
Definition at line 93 of file log-macros-enabled.h.
#define NS_LOG_APPEND_NODE_PREFIX_IMPL |
Implementation details for NS_LOG_APPEND_NODE_PREFIX.
Definition at line 62 of file log-macros-enabled.h.
#define NS_LOG_APPEND_TIME_PREFIX |
Append the simulation time to a log message.
Definition at line 81 of file log-macros-enabled.h.
#define NS_LOG_APPEND_TIME_PREFIX_IMPL |
Implementation details for NS_LOG_APPEND_TIME_PREFIX.
Definition at line 43 of file log-macros-enabled.h.
#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:
[in] | name | The log component name. |
#define NS_LOG_COMPONENT_DEFINE_MASK | ( | name, | |
mask | |||
) | static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__, mask) |
#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
Definition at line 159 of file log-macros-enabled.h.
#define NS_LOG_DEBUG | ( | msg | ) | NS_LOG(ns3::LOG_DEBUG, msg) |
#define NS_LOG_ERROR | ( | msg | ) | NS_LOG(ns3::LOG_ERROR, msg) |
#define NS_LOG_FUNCTION | ( | parameters | ) |
If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ", ".
Typical usage looks like:
And the output will look like:
To facilitate function tracing, most functions should begin with (at least) NS_LOG_FUNCTION(this). Static functions should use NS_LOG_FUNCTION_NOARGS() instead.
[in] | parameters | The parameters to output. |
Definition at line 238 of file log-macros-enabled.h.
#define NS_LOG_FUNCTION_NOARGS | ( | ) |
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 204 of file log-macros-enabled.h.
#define NS_LOG_INFO | ( | msg | ) | NS_LOG(ns3::LOG_INFO, msg) |
#define NS_LOG_LOGIC | ( | msg | ) | NS_LOG(ns3::LOG_LOGIC, msg) |
#define NS_LOG_STATIC_TEMPLATE_DEFINE | ( | name | ) | static LogComponent& g_log [[maybe_unused]] = GetLogComponent(name) |
#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.
#define NS_LOG_TEMPLATE_DEFINE | ( | name | ) | g_log(GetLogComponent(name)) |
#define NS_LOG_UNCOND | ( | msg | ) |
Output the requested message unconditionally.
[in] | msg | The message to log |
Definition at line 260 of file log-macros-enabled.h.
#define NS_LOG_WARN | ( | msg | ) | NS_LOG(ns3::LOG_WARN, msg) |
|
static |
Parse the NS_LOG
environment variable.
This is private to the logging implementation.
Definition at line 455 of file log.cc.
References ns3::ComponentExists(), ns3::EnvironmentVariable::GetDictionary(), ns3::LogComponentPrintList(), NS_FATAL_ERROR, NS_LOG_UNCOND, and ns3::SplitString().
Referenced by ns3::LogSetTimePrinter().
|
static |
Check if a log component exists.
This is private to the logging implementation.
[in] | componentName | The putative log component name. |
true
if componentName
exists. Definition at line 442 of file log.cc.
References ns3::LogComponent::GetComponentList().
Referenced by ns3::CheckEnvironmentVariables().
void ns3::DefaultNodePrinter | ( | std::ostream & | os | ) |
Default node id printer implementation.
[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().
|
static |
The Log NodePrinter.
Definition at line 116 of file log.cc.
Referenced by ns3::LogGetNodePrinter(), and ns3::LogSetNodePrinter().
|
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().