A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
log.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2006,2007 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8
9#ifndef NS3_LOG_H
10#define NS3_LOG_H
11
12#include "log-macros-disabled.h"
13#include "log-macros-enabled.h"
14#include "node-printer.h"
15#include "time-printer.h"
16
17#include <iostream>
18#include <stdint.h>
19#include <string>
20#include <type_traits>
21#include <unordered_map>
22#include <vector>
23
24/**
25 * @file
26 * @ingroup logging
27 * Debug message logging
28 */
29
30/**
31 * @ingroup debugging
32 * @defgroup logging Logging
33 *
34 * @brief Logging functions and macros
35 *
36 * LOG functionality: macros which allow developers to
37 * send information to the \c std::clog output stream.
38 *
39 * All logging messages are disabled by default. To enable selected logging
40 * messages, use the ns3::LogComponentEnable
41 * function or use the NS_LOG environment variable
42 *
43 * Use the environment variable NS_LOG to define a ':'-separated list of
44 * logging components to enable. For example (using bash syntax),
45 * @code
46 * $ NS_LOG="OlsrAgent" ./ns3 run ...
47 * @endcode
48 * would enable one component at all log levels.
49 * @code
50 * $NS_LOG="OlsrAgent:Ipv4L3Protocol" ./ns3 run ...
51 * @endcode
52 * would enable two components, at all log levels, etc.
53 * \c NS_LOG="*" will enable all available log components at all levels.
54 *
55 * To control more selectively the log levels for each component, use
56 * this syntax:
57 * @code
58 * $ NS_LOG='Component1=func|warn:Component2=error|debug'
59 * @endcode
60 * This example would enable the \c func, and \c warn log
61 * levels for 'Component1' and the \c error and \c debug log levels
62 * for 'Component2'. The wildcard '*' can be used here as well. For example
63 * \c NS_LOG='*=level_all|prefix' would enable all log levels and prefix all
64 * prints with the component and function names.
65 *
66 * A note on NS_LOG_FUNCTION() and NS_LOG_FUNCTION_NOARGS():
67 * generally, use of (at least) NS_LOG_FUNCTION(this) is preferred,
68 * with the any function parameters added:
69 * @code
70 * NS_LOG_FUNCTION (this << arg1 << args);
71 * @endcode
72 * Use NS_LOG_FUNCTION_NOARGS() only in static functions with no arguments.
73 */
74/** @{ */
75
76namespace ns3
77{
78
79/**
80 * Logging severity classes and levels.
81 */
83{
84 LOG_NONE = 0x00000000, //!< No logging.
85
86 LOG_ERROR = 0x00000001, //!< Serious error messages only.
87 LOG_LEVEL_ERROR = 0x00000001, //!< LOG_ERROR and above.
88
89 LOG_WARN = 0x00000002, //!< Warning messages.
90 LOG_LEVEL_WARN = 0x00000003, //!< LOG_WARN and above.
91
92 LOG_INFO = 0x00000004, //!< Something happened to change state.
93 LOG_LEVEL_INFO = 0x00000007, //!< LOG_INFO and above.
94
95 LOG_FUNCTION = 0x00000008, //!< Function tracing for non-trivial function calls.
96 LOG_LEVEL_FUNCTION = 0x0000000f, //!< LOG_FUNCTION and above.
97
98 LOG_LOGIC = 0x00000010, //!< Debugging logs for key branches and decisions in a function.
99 LOG_LEVEL_LOGIC = 0x0000001f, //!< LOG_LOGIC and above.
100
101 LOG_DEBUG = 0x00000020, //!< Full voluminous logging to support debugging.
102 LOG_LEVEL_DEBUG = 0x0000003f, //!< LOG_DEBUG and above.
103
104 LOG_ALL = 0x0fffffff, //!< Print everything.
105 LOG_LEVEL_ALL = LOG_ALL, //!< Print everything.
106
107 LOG_PREFIX_FUNC = 0x80000000, //!< Prefix all trace prints with function.
108 LOG_PREFIX_TIME = 0x40000000, //!< Prefix all trace prints with simulation time.
109 LOG_PREFIX_NODE = 0x20000000, //!< Prefix all trace prints with simulation node.
110 LOG_PREFIX_LEVEL = 0x10000000, //!< Prefix all trace prints with log level (severity).
111 LOG_PREFIX_ALL = 0xf0000000 //!< All prefixes.
113
114/**
115 * Enable the logging output associated with that log component.
116 *
117 * The logging output can be later disabled with a call
118 * to ns3::LogComponentDisable.
119 *
120 * Same as running your program with the NS_LOG environment
121 * variable set as NS_LOG='name=level'.
122 *
123 * @param [in] name The log component name.
124 * @param [in] level The logging level.
125 */
126void LogComponentEnable(const std::string& name, LogLevel level);
127
128/**
129 * Enable the logging output for all registered log components.
130 *
131 * Same as running your program with the NS_LOG environment
132 * variable set as NS_LOG='*=level'
133 *
134 * @param [in] level The logging level.
135 */
137
138/**
139 * Disable the logging output associated with that log component.
140 *
141 * The logging output can be later re-enabled with a call
142 * to LogComponentEnable.
143 *
144 * @param [in] name The log component name.
145 * @param [in] level The logging level.
146 */
147void LogComponentDisable(const std::string& name, LogLevel level);
148
149/**
150 * Disable all logging for all components.
151 *
152 * @param [in] level The logging level.
153 */
155
156} // namespace ns3
157
158/**
159 * Define a Log component with a specific name.
160 *
161 * This macro should be used at the top of every file in which you want
162 * to use the NS_LOG macro. This macro defines a new
163 * "log component" which can be later selectively enabled
164 * or disabled with the ns3::LogComponentEnable and
165 * ns3::LogComponentDisable functions or with the NS_LOG
166 * environment variable.
167 *
168 * LogComponent names should be simple string tokens, _i.e._,
169 * "ArfWifiManager", not "ns3::ArfWifiManager".
170 *
171 * This macro should be placed within namespace ns3. If functions
172 * outside of namespace ns3 require access to logging, the preferred
173 * solution is to add the following 'using' directive at file scope,
174 * outside of namespace ns3, and after the inclusion of
175 * NS_LOG_COMPONENT_DEFINE, such as follows:
176 * @code
177 * namespace ns3 {
178 * NS_LOG_COMPONENT_DEFINE ("...");
179 *
180 * // Definitions within the ns3 namespace
181 *
182 * } // namespace ns3
183 *
184 * using ns3::g_log;
185 *
186 * // Further definitions outside of the ns3 namespace
187 * @endcode
188 *
189 * @param [in] name The log component name.
190 */
191#define NS_LOG_COMPONENT_DEFINE(name) \
192 static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__)
193
194/**
195 * Define a logging component with a mask.
196 *
197 * See LogComponent().
198 *
199 * @param [in] name The log component name.
200 * @param [in] mask The default mask.
201 */
202#define NS_LOG_COMPONENT_DEFINE_MASK(name, mask) \
203 static ns3::LogComponent g_log = ns3::LogComponent(name, __FILE__, mask)
204
205/**
206 * Declare a reference to a Log component.
207 *
208 * This macro should be used in the declaration of template classes
209 * to allow their methods (defined in an header file) to make use of
210 * the NS_LOG_* macros. This macro should be used in the private
211 * section to prevent subclasses from using the same log component
212 * as the base class.
213 */
214#define NS_LOG_TEMPLATE_DECLARE LogComponent& g_log
215
216/**
217 * Initialize a reference to a Log component.
218 *
219 * This macro should be used in the constructor of template classes
220 * to allow their methods (defined in an header file) to make use of
221 * the NS_LOG_* macros.
222 *
223 * @param [in] name The log component name.
224 */
225#define NS_LOG_TEMPLATE_DEFINE(name) g_log(GetLogComponent(name))
226
227/**
228 * Declare and initialize a reference to a Log component.
229 *
230 * This macro should be used in static template methods to allow their
231 * methods (defined in an header file) to make use of the NS_LOG_* macros.
232 *
233 * @param [in] name The log component name.
234 */
235#define NS_LOG_STATIC_TEMPLATE_DEFINE(name) \
236 static LogComponent& g_log [[maybe_unused]] = GetLogComponent(name)
237
238/**
239 * Use \ref NS_LOG to output a message of level LOG_ERROR.
240 *
241 * @param [in] msg The message to log.
242 */
243#define NS_LOG_ERROR(msg) NS_LOG(ns3::LOG_ERROR, msg)
244
245/**
246 * Use \ref NS_LOG to output a message of level LOG_WARN.
247 *
248 * @param [in] msg The message to log.
249 */
250#define NS_LOG_WARN(msg) NS_LOG(ns3::LOG_WARN, msg)
251
252/**
253 * Use \ref NS_LOG to output a message of level LOG_DEBUG.
254 *
255 * @param [in] msg The message to log.
256 */
257#define NS_LOG_DEBUG(msg) NS_LOG(ns3::LOG_DEBUG, msg)
258
259/**
260 * Use \ref NS_LOG to output a message of level LOG_INFO.
261 *
262 * @param [in] msg The message to log.
263 */
264#define NS_LOG_INFO(msg) NS_LOG(ns3::LOG_INFO, msg)
265
266/**
267 * Use \ref NS_LOG to output a message of level LOG_LOGIC
268 *
269 * @param [in] msg The message to log.
270 */
271#define NS_LOG_LOGIC(msg) NS_LOG(ns3::LOG_LOGIC, msg)
272
273namespace ns3
274{
275
276/**
277 * Print the list of logging messages available.
278 * Same as running your program with the NS_LOG environment
279 * variable set as NS_LOG=print-list
280 */
282
283/**
284 * Set the TimePrinter function to be used
285 * to prepend log messages with the simulation time.
286 *
287 * The default is DefaultTimePrinter().
288 *
289 * @param [in] lp The TimePrinter function.
290 */
292/**
293 * Get the LogTimePrinter function currently in use.
294 * @returns The current LogTimePrinter function.
295 */
297
298/**
299 * Set the LogNodePrinter function to be used
300 * to prepend log messages with the node id.
301 *
302 * The default is DefaultNodePrinter().
303 *
304 * @param [in] np The LogNodePrinter function.
305 */
307/**
308 * Get the LogNodePrinter function currently in use.
309 * @returns The current LogNodePrinter function.
310 */
312
313/**
314 * A single log component configuration.
315 */
317{
318 public:
319 /**
320 * Constructor.
321 *
322 * @param [in] name The user-visible name for this component.
323 * @param [in] file The source code file which defined this LogComponent.
324 * @param [in] mask LogLevels blocked for this LogComponent. Blocking
325 * a log level helps prevent recursion by logging in
326 * functions which help implement the logging facility.
327 */
328 LogComponent(const std::string& name, const std::string& file, const LogLevel mask = LOG_NONE);
329 /**
330 * Check if this LogComponent is enabled for \c level
331 *
332 * @param [in] level The level to check for.
333 * @return \c true if we are enabled at \c level.
334 */
335 bool IsEnabled(const LogLevel level) const;
336 /**
337 * Check if all levels are disabled.
338 *
339 * @return \c true if all levels are disabled.
340 */
341 bool IsNoneEnabled() const;
342 /**
343 * Enable this LogComponent at \c level
344 *
345 * @param [in] level The LogLevel to enable.
346 */
347 void Enable(const LogLevel level);
348 /**
349 * Disable logging at \c level for this LogComponent.
350 *
351 * @param [in] level The LogLevel to disable.
352 */
353 void Disable(const LogLevel level);
354 /**
355 * Get the name of this LogComponent.
356 *
357 * @return The name of this LogComponent.
358 */
359 std::string Name() const;
360 /**
361 * Get the compilation unit defining this LogComponent.
362 * @returns The file name.
363 */
364 std::string File() const;
365 /**
366 * Get the string label for the given LogLevel.
367 *
368 * @param [in] level The LogLevel to get the label for.
369 * @return The string label for \c level.
370 */
371 static std::string GetLevelLabel(const LogLevel level);
372 /**
373 * Prevent the enabling of a specific LogLevel.
374 *
375 * @param [in] level The LogLevel to block.
376 */
377 void SetMask(const LogLevel level);
378
379 /**
380 * LogComponent name map.
381 *
382 * @internal
383 * This should really be considered an internal API.
384 * It is exposed here to allow print-introspected-doxygen.cc
385 * to generate a list of all LogComponents.
386 */
387 using ComponentList = std::unordered_map<std::string, LogComponent*>;
388
389 /**
390 * Get the list of LogComponents.
391 *
392 * @internal
393 * This should really be considered an internal API.
394 * It is exposed here to allow print-introspected-doxygen.cc
395 * to generate a list of all LogComponents.
396 *
397 * @returns The list of LogComponents.
398 */
400
401 private:
402 /**
403 * Parse the `NS_LOG` environment variable for options relating to this
404 * LogComponent.
405 */
406 void EnvVarCheck();
407
408 int32_t m_levels; //!< Enabled LogLevels.
409 int32_t m_mask; //!< Blocked LogLevels.
410 std::string m_name; //!< LogComponent name.
411 std::string m_file; //!< File defining this LogComponent.
412
413}; // class LogComponent
414
415/**
416 * Get the LogComponent registered with the given name.
417 *
418 * @param [in] name The name of the LogComponent.
419 * @return a reference to the requested LogComponent
420 */
421LogComponent& GetLogComponent(const std::string name);
422
423/**
424 * Insert `, ` when streaming function arguments.
425 */
427{
428 public:
429 /**
430 * Constructor.
431 *
432 * @param [in] os Underlying output stream.
433 */
434 ParameterLogger(std::ostream& os);
435
436 /**
437 * Write a function parameter on the output stream,
438 * separating parameters after the first by `,` strings.
439 *
440 * @param [in] param The function parameter.
441 * @return This ParameterLogger, so it's chainable.
442 */
443 template <typename T>
444 ParameterLogger& operator<<(const T& param);
445
446 /**
447 * Overload for vectors, to print each element.
448 *
449 * @param [in] vector The vector of parameters
450 * @return This ParameterLogger, so it's chainable.
451 */
452 template <typename T>
453 ParameterLogger& operator<<(const std::vector<T>& vector);
454
455 private:
456 /** Add `, ` before every parameter after the first. */
457 void CommaRest();
458
459 bool m_first{true}; //!< First argument flag, doesn't get `, `.
460 std::ostream& m_os; //!< Underlying output stream.
461};
462
463template <typename T>
465ParameterLogger::operator<<(const T& param)
466{
467 CommaRest();
468
469 if constexpr (std::is_convertible_v<T, std::string>)
470 {
471 m_os << "\"" << param << "\"";
472 }
473 else if constexpr (std::is_arithmetic_v<T>)
474 {
475 // Use + unary operator to cast uint8_t / int8_t to uint32_t / int32_t, respectively
476 m_os << +param;
477 }
478 else
479 {
480 m_os << param;
481 }
482
483 return *this;
484}
485
486template <typename T>
488ParameterLogger::operator<<(const std::vector<T>& vector)
489{
490 for (const auto& i : vector)
491 {
492 *this << i;
493 }
494 return *this;
495}
496
497} // namespace ns3
498
499/**@}*/ // \ingroup logging
500
501#endif /* NS3_LOG_H */
A single log component configuration.
Definition log.h:317
static ComponentList * GetComponentList()
Get the list of LogComponents.
Definition log.cc:132
void Enable(const LogLevel level)
Enable this LogComponent at level.
Definition log.cc:255
bool IsEnabled(const LogLevel level) const
Check if this LogComponent is enabled for level.
Definition log.cc:236
std::string File() const
Get the compilation unit defining this LogComponent.
Definition log.cc:273
int32_t m_levels
Enabled LogLevels.
Definition log.h:408
void Disable(const LogLevel level)
Disable logging at level for this LogComponent.
Definition log.cc:261
static std::string GetLevelLabel(const LogLevel level)
Get the string label for the given LogLevel.
Definition log.cc:280
void EnvVarCheck()
Parse the NS_LOG environment variable for options relating to this LogComponent.
Definition log.cc:187
std::string m_file
File defining this LogComponent.
Definition log.h:411
bool IsNoneEnabled() const
Check if all levels are disabled.
Definition log.cc:243
std::string Name() const
Get the name of this LogComponent.
Definition log.cc:267
std::unordered_map< std::string, LogComponent * > ComponentList
LogComponent name map.
Definition log.h:387
int32_t m_mask
Blocked LogLevels.
Definition log.h:409
LogComponent(const std::string &name, const std::string &file, const LogLevel mask=LOG_NONE)
Constructor.
Definition log.cc:148
void SetMask(const LogLevel level)
Prevent the enabling of a specific LogLevel.
Definition log.cc:249
std::string m_name
LogComponent name.
Definition log.h:410
Insert , when streaming function arguments.
Definition log.h:427
void CommaRest()
Add , before every parameter after the first.
Definition log.cc:518
bool m_first
First argument flag, doesn't get ,.
Definition log.h:459
ParameterLogger & operator<<(const T &param)
Write a function parameter on the output stream, separating parameters after the first by ,...
Definition log.h:465
ParameterLogger(std::ostream &os)
Constructor.
Definition log.cc:512
std::ostream & m_os
Underlying output stream.
Definition log.h:460
Definition of empty logging macros and the NS_LOG_NOOP_INTERNAL macro.
NS_LOG and related logging macro definitions.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
void LogComponentEnable(const std::string &name, LogLevel level)
Enable the logging output associated with that log component.
Definition log.cc:291
void LogSetTimePrinter(TimePrinter printer)
Set the TimePrinter function to be used to prepend log messages with the simulation time.
Definition log.cc:483
void(* TimePrinter)(std::ostream &os)
Function signature for features requiring a time formatter, such as logging or ShowProgress.
void(* NodePrinter)(std::ostream &os)
Function signature for prepending the node id to a log message.
NodePrinter LogGetNodePrinter()
Get the LogNodePrinter function currently in use.
Definition log.cc:507
void LogComponentDisable(const std::string &name, LogLevel level)
Disable the logging output associated with that log component.
Definition log.cc:319
LogLevel
Logging severity classes and levels.
Definition log.h:83
@ LOG_LEVEL_ALL
Print everything.
Definition log.h:105
@ LOG_PREFIX_FUNC
Prefix all trace prints with function.
Definition log.h:107
@ LOG_LEVEL_LOGIC
LOG_LOGIC and above.
Definition log.h:99
@ LOG_NONE
No logging.
Definition log.h:84
@ LOG_PREFIX_TIME
Prefix all trace prints with simulation time.
Definition log.h:108
@ LOG_FUNCTION
Function tracing for non-trivial function calls.
Definition log.h:95
@ LOG_ERROR
Serious error messages only.
Definition log.h:86
@ LOG_WARN
Warning messages.
Definition log.h:89
@ LOG_INFO
Something happened to change state.
Definition log.h:92
@ LOG_PREFIX_ALL
All prefixes.
Definition log.h:111
@ LOG_LEVEL_FUNCTION
LOG_FUNCTION and above.
Definition log.h:96
@ LOG_LEVEL_ERROR
LOG_ERROR and above.
Definition log.h:87
@ LOG_ALL
Print everything.
Definition log.h:104
@ LOG_LEVEL_WARN
LOG_WARN and above.
Definition log.h:90
@ LOG_LEVEL_DEBUG
LOG_DEBUG and above.
Definition log.h:102
@ LOG_PREFIX_LEVEL
Prefix all trace prints with log level (severity).
Definition log.h:110
@ LOG_LOGIC
Debugging logs for key branches and decisions in a function.
Definition log.h:98
@ LOG_PREFIX_NODE
Prefix all trace prints with simulation node.
Definition log.h:109
@ LOG_LEVEL_INFO
LOG_INFO and above.
Definition log.h:93
@ LOG_DEBUG
Full voluminous logging to support debugging.
Definition log.h:101
TimePrinter LogGetTimePrinter()
Get the LogTimePrinter function currently in use.
Definition log.cc:495
void LogComponentDisableAll(LogLevel level)
Disable all logging for all components.
Definition log.cc:331
LogComponent & GetLogComponent(const std::string name)
Get the LogComponent registered with the given name.
Definition log.cc:170
void LogComponentEnableAll(LogLevel level)
Enable the logging output for all registered log components.
Definition log.cc:309
void LogSetNodePrinter(NodePrinter printer)
Set the LogNodePrinter function to be used to prepend log messages with the node id.
Definition log.cc:501
void LogComponentPrintList()
Print the list of logging messages available.
Definition log.cc:341
Declaration of ns3::NodePrinter function pointer type and ns3::DefaultNodePrinter function.
Declaration of ns3::TimePrinter function pointer type and ns3::DefaultTimePrinter function.