Defines | Functions

Logging
[Debugging]

Logging functions and macros. More...

Collaboration diagram for Logging:

Defines

#define NS_LOG_COMPONENT_DEFINE(name)   static ns3::LogComponent g_log = ns3::LogComponent (name)
#define NS_LOG(level, msg)
#define NS_LOG_ERROR(msg)   NS_LOG(ns3::LOG_ERROR, msg)
#define NS_LOG_WARN(msg)   NS_LOG(ns3::LOG_WARN, msg)
#define NS_LOG_DEBUG(msg)   NS_LOG(ns3::LOG_DEBUG, msg)
#define NS_LOG_INFO(msg)   NS_LOG(ns3::LOG_INFO, msg)
#define NS_LOG_FUNCTION_NOARGS()
#define NS_LOG_FUNCTION(parameters)
#define NS_LOG_LOGIC(msg)   NS_LOG(ns3::LOG_LOGIC, msg)
#define NS_LOG_UNCOND(msg)

Functions

void ns3::LogComponentEnable (char const *name, enum LogLevel level)
void ns3::LogComponentEnableAll (enum LogLevel level)
void ns3::LogComponentDisable (char const *name, enum LogLevel level)
void ns3::LogComponentDisableAll (enum LogLevel level)
void ns3::LogComponentPrintList (void)

Detailed Description

Logging functions and macros.

LOG functionality: macros which allow developers to send information out on screen. 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" would enable one component at all log levels. NS_LOG="OlsrAgent:Ipv4L3Protocol" 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.


Define Documentation

#define NS_LOG (   level,
  msg 
)
Value:
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;                            \
          std::clog << msg << std::endl;                        \
        }                                                       \
    }                                                           \
  while (false)
Parameters:
level the log level
msg the message to log

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);
#define NS_LOG_COMPONENT_DEFINE (   name  )     static ns3::LogComponent g_log = ns3::LogComponent (name)
Parameters:
name a string

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.

#define NS_LOG_DEBUG (   msg  )     NS_LOG(ns3::LOG_DEBUG, msg)
Parameters:
msg the message to log

Use NS_LOG to output a message of level LOG_DEBUG.

#define NS_LOG_ERROR (   msg  )     NS_LOG(ns3::LOG_ERROR, msg)
Parameters:
msg the message to log

Use NS_LOG to output a message of level LOG_ERROR.

#define NS_LOG_FUNCTION (   parameters  ) 
Value:
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)
Parameters:
parameters the parameters to output.

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)
#define NS_LOG_FUNCTION_NOARGS (  ) 
Value:
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.

#define NS_LOG_INFO (   msg  )     NS_LOG(ns3::LOG_INFO, msg)
Parameters:
msg the message to log

Use NS_LOG to output a message of level LOG_INFO.

#define NS_LOG_LOGIC (   msg  )     NS_LOG(ns3::LOG_LOGIC, msg)
Parameters:
msg the message to log

Use NS_LOG to output a message of level LOG_LOGIC

#define NS_LOG_UNCOND (   msg  ) 
Value:
do                                    \
    {                                   \
      std::clog << msg << std::endl;    \
    }                                   \
  while (false)
Parameters:
msg the message to log

Output the requested message unconditionaly.

#define NS_LOG_WARN (   msg  )     NS_LOG(ns3::LOG_WARN, msg)
Parameters:
msg the message to log

Use NS_LOG to output a message of level LOG_WARN.


Function Documentation

void ns3::LogComponentDisable ( char const *  name,
enum LogLevel  level 
)
Parameters:
name a log component name
level a logging level

Disable the logging output associated with that log component. The logging output can be later re-enabled with a call to ns3::LogComponentEnable.

void ns3::LogComponentDisableAll ( enum LogLevel  level  ) 
Parameters:
level a logging level

Disable all logging for all components.

void ns3::LogComponentEnable ( char const *  name,
enum LogLevel  level 
)
Parameters:
name a log component name
level a logging level

Enable the logging output associated with that log component. The logging output can be later disabled with a call to ns3::LogComponentDisable.

Same as running your program with the NS_LOG environment variable set as NS_LOG='name=level'

void ns3::LogComponentEnableAll ( enum LogLevel  level  ) 
Parameters:
level a logging level

Enable the logging output for all registered log components.

Same as running your program with the NS_LOG environment variable set as NS_LOG='*=level'

void ns3::LogComponentPrintList ( void   ) 

Print the list of logging messages available. Same as running your program with the NS_LOG environment variable set as NS_LOG=print-list