The design objective has been to offer the user a lot of flexibility in selecting which events to monitor, and to allow users freedom to use possibly complex logic to decide what things to log to trace files or to perform inline statistics calculations.
To provide this flexibility, every model must define a set of trace event sources. Each of these trace event source can generate one type of event and can specify any number of arguments to convey per-event information from the trace event source to the listening trace event sinks.
While this design allows users to hand-specify a different trace sink to each trace source, ns-3 also provides a set of simple trace helpers which perform bulk connection of the default trace sources to a set of trace sinks which generate trace files in various specific formats. For example, pcap output can be trivially generated for the default ipv4 stack by instantiating an object of type PcapTrace and calling its TraceAllIp method. The example file examples/simple-p2p.cc contains examples for producing both ascii and pcap traces using this high-level API.
To integrate in this framework, model developers need to:
Later, when the time comes to connect the user's trace sinks (that is, the user's callbacks. See section 4.2) to the model's trace sources, the user can use the TraceRoot::Connect method which takes as an argument a string pattern which identifies the set of trace sources stored in trace resolver instances to connect. For example, a string pattern could look like '/nodes/*/netdevices/*/*' which would identify all trace events in all netdevice objects contained in all nodes.