NS-TRACING

TRACING

The *ns-3 *tracing system is built on the concepts of independent tracing sources and tracing sinks, along with a uniformmechanism for connecting sources to sinks.

Trace sources are entities that can signal events that happen in a simulation and provide access to interesting underlyingdata. For example, a trace source could indicate when a packet is received by a net device and provide access to thepacket contents for interested trace sinks. A trace source might also indicate when an interesting state change happensin a model. For example, the congestion window of a TCP model is a prime candidate for a trace source. Every timethe congestion window changes connected trace sinks are notified with the old and new value.

Trace sources are not useful by themselves; they must be connected to other pieces of code that actually do somethinguseful with the information provided by the source. The entities that consume trace information are called trace sinks.Trace sources are generators of data and trace sinks are consumers. This explicit division allows for large numbers oftrace sources to be scattered around the system in places which model authors believe might be useful. Inserting tracesources introduces a very small execution overhead.

There can be zero or more consumers of trace events generated by a trace source. One can think of a trace source as akind of point-to-multipoint information link. Your code looking for trace events from a particular piece of core codecould happily coexist with other code doing something entirely different from the same information.

Unless a user connects a trace sink to one of these sources, nothing is output. By using the tracing system, both youand other people hooked to the same trace source are getting exactly what they want and only what they want out ofthe system. Neither of you are impacting any other user by changing what information is output by the system. If youhappen to add a trace source, your work as a good open-source citizen may allow other users to provide new utilitiesthat are perhaps very useful overall, without making any changes to the *ns-3 *core.

Callbacks

允许某处代码访问C++中某个函数和方法无需具体模块之间的依赖。
根本上是你把访问函数的地址视为变量，函数指针。
每个trace source维护一个internal list of Callbacks。

class MyObject : public Object
{
public:
  /**
   * Register this type.
   * \return The TypeId.
   */
  static TypeId GetTypeId (void)
  {
    static TypeId tid = TypeId ("MyObject")
      .SetParent<Object> ()
      .SetGroupName ("Tutorial")
      .AddConstructor<MyObject> ()
      .AddTraceSource ("MyInteger",
                       "An integer value to trace.",
                       MakeTraceSourceAccessor (&MyObject::m_myInt),
                       "ns3::TracedValueCallback::Int32")
    ;
    return tid;
  }

  MyObject () {}
  TracedValue<int32_t> m_myInt;
};
void
IntTrace (int32_t oldValue, int32_t newValue)
{
  std::cout << "Traced " << oldValue << " to " << newValue << std::endl;
}
int
main (int argc, char *argv[])
{
  Ptr<MyObject> myObject = CreateObject<MyObject> ();
  myObject->TraceConnectWithoutContext ("MyInteger", MakeCallback (&IntTrace));

  myObject->m_myInt = 1234;
}

.AddTraceSource第一个属性是trace source的名字，在config system中可见；
第二个属性是帮助信息；
第三个属性,使用要追踪的TracedValue生成函数特征调用

The TracedValue<> declaration provides the infrastructure that drives the callback process. Any time the underlying value is changed the TracedValue mechanism will provide both the old and the new value of that variable, in thiscase an int32_t value. The trace sink function traceSink for this TracedValue will need the signature

Connect with Config

TraceConnectWithoutContext这种函数其实用的时候很少，大多数用Config来连接,底层调用合适的TraceConnect。
Config系统用Config path来选择trace source.

void ns3::Config::Connect
(
std::string path,
const CallbackBase & cb
)

Parameters
[in]path
A path to match trace sources.
[in]cb
The callback to connect to the matching trace sources.

This function will attempt to find all trace sources which match the input path and will then connect the input callback to them in such a way that the callback will receive an extra context string upon trace event notification.
通过TracedCallback类中重载的操作符()calls any registered trace sinks

拿CourseChange的例子更加深入底层的讲了ns3的底层代码如何构建TraceSource,以及Trace工作原理

Finding Sources

Okay, I know that there must be trace sources in the simulation core, but how do I find out what trace sources areavailable to me?

Finding Sources.png

Config Paths

Okay, I found a trace source, how do I figure out the Config path to use when I connect to it?

Detailed Description.png

/NodeList/[i]/$ns3::MobilityModel"
还可以使用命令搜索文件

find . -name '*.cc' | xargs grep CourseChange | grep Connect

找到实例自己模仿着写

Callback Signatures

Okay, I found a trace source and the Config path, how do I figure out what the return type and formal arguments ofmy callback function need to be?
一种方法去用上面的命令找到实例
一种方法是在API文档里找
实在找不到的就找TracedCallback定义的变量

总结自己写一个trace source需要注册.AddTraceSource,申明一个想要关注的TracedValue变量，然后写一个trace sink函数用来接收source发出的信息，在程序运行前把sink绑定到source上，这样TracedValue在变化时执行callback返回新旧两个TracedValue值。

To summarize, a trace source is, in essence, a variable that holds a list of callbacks. A trace sink is a function usedas the target of a callback. The Attribute and object type information systems are used to provide a way to connecttrace sources to trace sinks. The act of “hitting” a trace source is executing an operator on the trace source which firescallbacks. This results in the trace sink callbacks registering interest in the source being called with the parametersprovided by the source.

看了好几天ns3的回调实现，最后在ns3group里找到了答案，
https://groups.google.com/forum/#!topic/ns-3-users/xty2I8JV3_c
3.24 ps：想要看C++如何通过模板类实现回调还要买书学习一下