LTE Manual ——Logging（翻译）
（本文为个人学习笔记，如有不当的地方，欢迎指正！）
9 Logging
ns-3 日志功能可以用于监测或调试仿真程序的进展。日志输出可以通过 main() 程序中的语句或通过使用 NS_LOG 环境变量来启用。
日志语句并没有编译成 ns-3 的优化版本（Logging statements are not compiled into optimized builds of ns-3）。为了使用日志，必须 build ns-3 的默认调试 build 。
这个项目并不能保证日志输出会随时间而保持不变。提醒用户不要在日志代码顶部建立仿真输出框架，因为输出和启用输出的方式可能会随时间改变。
9.1 概述
ns-3 日志语句通常用于记录各种程序执行事件，例如仿真事件的发生或特定函数的使用。
例如，这个代码片段来自 Ipv4L3Protocol::IsDestinationAddress()：
if (address == iaddr.GetBroadcast ()) { NS_LOG_LOGIC ("For me (interface broadcast address)"); return true; }
如果 Ipv4L3Protocol component 在 大于或等于 LOGIC severity 级别上开启日志功能，那么日志声明会被打印输出；否则会被抑制。
9.1.1 启用输出
用户通常使用两种方式控制日志输出。第一种是设置 NS_LOG 环境变量；例如：
$ NS_LOG="*" ./waf --run first
上述代码将运行 first tutorial 程序，得到所有的日志输出。 （下面将讨论特定的 NS_LOG 格式。）
通过选择单独的组件，日志输出可以变得更详细：
$ NS_LOG="Ipv4L3Protocol" ./waf --run first
输出可以进一步根据前缀选项来定制。
第二种启用输出的方式是在程序中使用明确的语句。例如在 first tutorial 程序中添加下列代码：
int main (int argc, char *argv[]){ LogComponentEnable ("UdpEchoClientApplication", LOG_LEVEL_INFO); LogComponentEnable ("UdpEchoServerApplication", LOG_LEVEL_INFO); ...
（下面讨论 LOG_LEVEL_INFO 的含义和其他可能的值。 ）
9.1.2 NS_LOG 语法
NS_LOG 环境变量包含一系列日志组件和选项。日志组件通过冒号':' 隔开：
$ NS_LOG="<log-component>:<log-component>..."
每个日志组件选项通过标识符（flags）给定，位于日志组件后面：
$ NS_LOG="<log-component>=<option>|<option>...:<log-component>..."
选项（options）控制该组件的 severity 和 level ，以及是否应包含可选信息，例如仿真时间、仿真节点、函数名和象征性的 severity。
9.1.3 日志组件
通常来说，一个日志组件指的是单个的 .cc 源码文件，并且包含整个文件。
一些 helpers 有特殊的方法用于启用 一个模块中所有组件的日志功能，跨越不同的编译单位，但是逻辑上能组合在一起，例如 ns-3 wifi 代码：
WifiHelper wifiHelper;wifiHelper.EnableLogComponents ();
NS_LOG 日志组件通配符 '*' 启用所有的组件。
为了查看日志组件的定义，使用下面任何一个都可以：
$ NS_LOG="print-list" ./waf --run ... $ NS_LOG="foo" # a token not matching any log-component
第一种形式会打印输出所有日志组件的名称和启用标识符（flags）；可以使用 scratch-simulator 去尝试。第二种形式会打印输出所有注册的日志组件，然后以一个错误退出。
9.1.4 Severity 和 Level 选项
单个的消息属于单个的 “severity class” ，由宏创建消息。在上述例子中， NS_LOG_LOGIC(..) 在 LOG_LOGIC severity 类中创建消息。
下列 severity 类定义为 enum 常量：
| Severity Class | Meaning |
| LOG_NONE | The default, no logging |
| LOG_ERROR | Serious error messages only |
| LOG_WARN | Warning messages |
| LOG_DEBUG | For use in debugging |
| LOG_INFO | Informational |
| LOG_FUNCTION | Function tracing |
| LOG_LOGIC | Control flow tracing within functions |
通常情况下， 人们想在给定的 severity 类和更高的类上看到消息。这可以通过定义包含的日志 “levels”来定义：
| Level | Meaning |
| LOG_LEVEL_ERROR | Only LOG_ERROR severity class messages. |
| LOG_LEVEL_WARN | LOG_WARN and above. |
| LOG_LEVEL_DEBUG | LOG_DEBUG and above. |
| LOG_LEVEL_INFO | LOG_INFO and above. |
| LOG_LEVEL_FUNCTION | LOG_FUNCTION and above. |
| LOG_LEVEL_LOGIC | LOG_LOGIC and above. |
| LOG_LEVEL_ALL | All severity classes. |
| LOG_ALL | Synonym for LOG_LEVEL_ALL |
severity 类和 level 选项可以通过这些令牌在 NS_LOG 环境变量中给定 ：
| Class | Level |
| error | level_error |
| warn | level_warn |
| debug | level_debug |
| info | level_info |
| function | level_function |
| logic | level_logic |
| level_allall* |
使用一个 severity 类令牌只能启用该 severity 的日志消息。 例如， NS_LOG="*=warn" 不会输出 severity 为 error 的消息。 NS_LOG="*=level_debug" 只会输出 severity 级别为 debug 及以上的日志消息。
severity 类和级别可以使用 `|’ 运算符进行结合： NS_LOG="*=level_warn|logic" 将输出 severity 级别为 error、 warn 和 logic 的消息。
NS_LOG severity 级别的通配符'*' 与 all 的同义词为 level_all。
对于只在 NS_LOG 中提到的日志组件：
$ NS_LOG="<log-component>:..."
默认的 severity 为 LOG_LEVEL_ALL。
9.1.5 前缀选项
很多前缀有助于确定消息起源于何时何地，是什么 severity。
可用的前缀选项 （如同 enum 常量）有
| Prefix Symbol | Meaning |
| LOG_PREFIX_FUNC | Prefix the name of the calling function. |
| LOG_PREFIX_TIME | Prefix the simulation time. |
| LOG_PREFIX_NODE | Prefix the node id. |
| LOG_PREFIX_LEVEL | Prefix the severity level. |
| LOG_PREFIX_ALL | Enable all prefixes. |
下面简要描述前缀选项。
选项可以通过这些令牌在 NS_LOG 环境变量中给出：
| Token | Alternate |
| prefix_func | func |
| prefix_time | time |
| prefix_node | node |
| prefix_level | level |
| prefix_all | all* |
对于只在 NS_LOG 中提到的日志组件：
$ NS_LOG="<log-component>:..."
默认的前缀选项为 LOG_PREFIX_ALL。
（1）Severity 前缀
一个消息的 severity 类包含在选项 prefix_level 或 level 中。 例如， NS_LOG 的值启用所有日志组件 ('*') 和所有 severity 类 (=all) 的日志功能，并且给 severity 类 (|prefix_level) 的消息添加前缀。
$ NS_LOG="*=all|prefix_level" ./waf --run scratch-simulator Scratch Simulator [ERROR] error message [WARN] warn message [DEBUG] debug message [INFO] info message [FUNCT] function message [LOGIC] logic message
（2）时间前缀
仿真时间包含在选项 prefix_time 后 time 中，以秒为单位输出仿真时间。
（3）节点前缀
仿真节点 id 包含在选项 prefix_node 或 node 中。
（4）函数前缀
调用的函数名包含在选项 prefix_func 或 func 中。
（5）NS_LOG 通配符
日志组件通配符 '*' 表示启用所有的组件。 在特定的 severity 级别启用所有组件，可以使用 *=<severity> 。
severity 级别选项通配符 '*' 是 all 的同义词。 它必须出现在任何 '|' 字符分隔选项之前。为了启用所有的 severity 类，可以使用 <log-component>=* 或 <log-component>=*|<options>。
选项通配符 '*' 或令牌 all 开启所有的前缀选项，但是必须出现 '|' 字符的后面。为了启用特定的 severity 类或级别，以及所有的前缀，可以使用 <log-component>=<severity>|*。
结合选项通配符 ** 表示启用所有的 severities 和所有的前缀；例如， <log-component>=**。
uber-wildcard *** 表示启用所有日志组件的所有 severities 和所有前缀。这些都是等价的：
$ NS_LOG="***" ... $ NS_LOG="*=all|*" ... $ NS_LOG="*=*|all" ... $ NS_LOG="*=**" ... $ NS_LOG="*=level_all|*" ... $ NS_LOG="*=*|prefix_all" ... $ NS_LOG="*=*|*" ...
建议： 使用 NS_LOG="***"，甚至连微不足道的 scratch-simulator 也会产生超过 46K 行的输出！
9.2 如何在代码中添加日志功能
在你的代码中添加日志功能非常重要：
（1）调用 namespace ns3 里的 NS_LOG_COMPONENT_DEFINE (...); 宏。
创建唯一的字符串标识符（通常基于文件名或文件内定义的类名），并使用宏调用注册它，例如：
namespace ns3 { NS_LOG_COMPONENT_DEFINE ("Ipv4L3Protocol");...
它会注册 Ipv4L3Protocol 为一个日志组件。
（宏是精心编写的，目的是允许其包含在命名空间 ns3 内部或外部，并且整个代码库的使用情况有所不同，但是最初的目的是在命名空间 ns3 的外部、在文件全局范围内注册宏。）
（2）在函数和函数体中添加日志声明（宏调用）。
9.2.1 Logging Macros（日志宏）
日志宏和相关的 severity 等级为
| Severity Class | Macro |
| LOG_NONE | (none needed) |
| LOG_ERROR | NS_LOG_ERROR (...); |
| LOG_WARN | NS_LOG_WARN (...); |
| LOG_DEBUG | NS_LOG_DEBUG (...); |
| LOG_INFO | NS_LOG_INFO (...); |
| LOG_FUNCTION | NS_LOG_FUNCTION (...); |
| LOG_LOGIC | NS_LOG_LOGIC (...); |
宏的功能为输出 streamers，因此发送 std::cout、使用 << 运算符连接的任何东西都是允许的：
void MyClass::Check (int value, char * item){ NS_LOG_FUNCTION (this << arg << item); if (arg > 10) { NS_LOG_ERROR ("encountered bad value " << value << " while checking " << name << "!"); } ...}
注意 NS_LOG_FUNCTION 自动会在每个参数间插入一个 ',' (comma-space) 分隔符。 这简化了函数参数的日志； 只是如同上述例子一样，将它们用 << 运算符进行连接。
9.2.2 Unconditional Logging（无条件的日志）
为方便起见， NS_LOG_UNCOND (...); 宏将总是记录它的参数，即使相关的日志组件没有在任何 severity 开启。 该宏不会使用任何前缀选项。注意日志只能在调试 builds 中启用；该宏不会在优化的 builds 中产生输出。
9.2.3 Guidelines（指南）
- 使用 NS_LOG_FUNCTION (this << args...); 开始每个类的方法。 这会启用简单的函数调用 tracing 。
-
- 除了： 不要记录运算符或明确的副本构造函数，因为这些会造成无穷递归和堆栈溢出。
- 对于没有参数的方法，使用相同形式：NS_LOG_FUNCTION (this);
- 对于静态函数：
-
- 有参数的话，像往常一样使用 NS_LOG_FUNCTION (...); 。
- 没有参数的话使用 NS_LOG_FUNCTION_NOARGS ();
- NS_LOG_ERROR 用于错误严重的条件（可能使仿真执行无效）。
- NS_LOG_WARN 用于不寻常的条件（可以纠正的）。 请给出问题本质以及如何纠正它的的有关提示。
- NS_LOG_DEBUG 通常以一种特别的方式使用，目的是理解模型的执行。
- NS_LOG_INFO 用于执行的附加信息，例如数据结构的大小（当添加/移除数据结构时）。
- NS_LOG_LOGIC 用于 trace 一个函数的重要逻辑分支
- 测试你的日志变化不会打破代码（break the code）。运行一些启用所有日志组件的示例程序（例如 NS_LOG="***"）。
- 使用显式类型转换，用于任何类型的变量 uint8_t 或 int8_t，例如， NS_LOG_LOGIC ("Variable i is " << static_cast<int> (i));。没有了 cast， 整数会被理解为一个字符，结果最可能不符合期望。这是一个有据可查的 C++ ‘feature’。
参考文献：https://www.nsnam.org/docs/manual/singlehtml/index.html#document-logging