| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ns-3 trace helpers provide a rich environment for configuring and
selecting different trace events and writing them to files. In previous
sections, primarily “Building Topologies,” we have seen several varieties
of the trace helper methods designed for use inside other (device) helpers.
Perhaps you will recall seeing some of these variations:
pointToPoint.EnablePcapAll ("second");
pointToPoint.EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
csma.EnablePcap ("third", csmaDevices.Get (0), true);
pointToPoint.EnableAsciiAll (ascii.CreateFileStream ("myfirst.tr"));
What may not be obvious, though, is that there is a consistent model for all of the trace-related methods found in the system. We will now take a little time and take a look at the “big picture”.
There are currently two primary use cases of the tracing helpers in ns-3:
Device helpers and protocol helpers. Device helpers look at the problem
of specifying which traces should be enabled through a node, device pair. For
example, you may want to specify that pcap tracing should be enabled on a
particular device on a specific node. This follows from the ns-3 device
conceptual model, and also the conceptual models of the various device helpers.
Following naturally from this, the files created follow a
<prefix>-<node>-<device> naming convention.
Protocol helpers look at the problem of specifying which traces should be
enabled through a protocol and interface pair. This follows from the ns-3
protocol stack conceptual model, and also the conceptual models of internet
stack helpers. Naturally, the trace files should follow a
<prefix>-<protocol>-<interface> naming convention.
The trace helpers therefore fall naturally into a two-dimensional taxonomy. There are subtleties that prevent all four classes from behaving identically, but we do strive to make them all work as similarly as possible; and whenever possible there are analogs for all methods in all classes.
| pcap | ascii | -----------------+------+-------| Device Helper | | | -----------------+------+-------| Protocol Helper | | | -----------------+------+-------|
We use an approach called a mixin to add tracing functionality to our
helper classes. A mixin is a class that provides functionality to that
is inherited by a subclass. Inheriting from a mixin is not considered a form
of specialization but is really a way to collect functionality.
Let’s take a quick look at all four of these cases and their respective
mixins.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The goal of these helpers is to make it easy to add a consistent pcap trace
facility to an ns-3 device. We want all of the various flavors of
pcap tracing to work the same across all devices, so the methods of these
helpers are inherited by device helpers. Take a look at
src/helper/trace-helper.h if you want to follow the discussion while
looking at real code.
The class PcapHelperForDevice is a mixin provides the high level
functionality for using pcap tracing in an ns-3 device. Every device
must implement a single virtual method inherited from this class.
virtual void EnablePcapInternal (std::string prefix, Ptr<NetDevice> nd, bool promiscuous) = 0;
The signature of this method reflects the device-centric view of the situation
at this level. All of the public methods inherited from class
2PcapUserHelperForDevice reduce to calling this single device-dependent
implementation method. For example, the lowest level pcap method,
void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
will call the device implementation of EnablePcapInternal directly. All
other public pcap tracing methods build on this implementation to provide
additional user-level functionality. What this means to the user is that all
device helpers in the system will have all of the pcap trace methods available;
and these methods will all work in the same way across devices if the device
implements EnablePcapInternal correctly.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false); void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false); void EnablePcap (std::string prefix, NetDeviceContainer d, bool promiscuous = false); void EnablePcap (std::string prefix, NodeContainer n, bool promiscuous = false); void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid, bool promiscuous = false); void EnablePcapAll (std::string prefix, bool promiscuous = false);
In each of the methods shown above, there is a default parameter called
promiscuous that defaults to false. This parameter indicates that the
trace should not be gathered in promiscuous mode. If you do want your traces
to include all traffic seen by the device (and if the device supports a
promiscuous mode) simply add a true parameter to any of the calls above. For example,
Ptr<NetDevice> nd;
...
helper.EnablePcap ("prefix", nd, true);
will enable promiscuous mode captures on the NetDevice specified by nd.
The first two methods also include a default parameter called explicitFilename
that will be discussed below.
You are encouraged to peruse the Doxygen for class PcapHelperForDevice
to find the details of these methods; but to summarize ...
You can enable pcap tracing on a particular node/net-device pair by providing a
Ptr<NetDevice> to an EnablePcap method. The Ptr<Node> is
implicit since the net device must belong to exactly one Node.
For example,
Ptr<NetDevice> nd;
...
helper.EnablePcap ("prefix", nd);
You can enable pcap tracing on a particular node/net-device pair by providing a
std::string representing an object name service string to an
EnablePcap method. The Ptr<NetDevice> is looked up from the name
string. Again, the @code<Node> is implicit since the named net device must
belong to exactly one Node. For example,
Names::Add ("server" ...);
Names::Add ("server/eth0" ...);
...
helper.EnablePcap ("prefix", "server/ath0");
You can enable pcap tracing on a collection of node/net-device pairs by
providing a NetDeviceContainer. For each NetDevice in the container
the type is checked. For each device of the proper type (the same type as is
managed by the device helper), tracing is enabled. Again, the @code<Node> is
implicit since the found net device must belong to exactly one Node.
For example,
NetDeviceContainer d = ...;
...
helper.EnablePcap ("prefix", d);
You can enable pcap tracing on a collection of node/net-device pairs by
providing a NodeContainer. For each Node in the NodeContainer
its attached NetDevices are iterated. For each NetDevice attached
to each node in the container, the type of that device is checked. For each
device of the proper type (the same type as is managed by the device helper),
tracing is enabled.
NodeContainer n;
...
helper.EnablePcap ("prefix", n);
You can enable pcap tracing on the basis of node ID and device ID as well as
with explicit Ptr. Each Node in the system has an integer node ID
and each device connected to a node has an integer device ID.
helper.EnablePcap ("prefix", 21, 1);
Finally, you can enable pcap tracing for all devices in the system, with the same type as that managed by the device helper.
helper.EnablePcapAll ("prefix");
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Implicit in the method descriptions above is the construction of a complete
filename by the implementation method. By convention, pcap traces in the
ns-3 system are of the form “<prefix>-<node id>-<device id>.pcap”
As previously mentioned, every node in the system will have a system-assigned node id; and every device will have an interface index (also called a device id) relative to its node. By default, then, a pcap trace file created as a result of enabling tracing on the first device of node 21 using the prefix “prefix” would be “prefix-21-1.pcap”.
You can always use the ns-3 object name service to make this more clear.
For example, if you use the object name service to assign the name “server”
to node 21, the resulting pcap trace file name will automatically become,
“prefix-server-1.pcap” and if you also assign the name “eth0” to the
device, your pcap file name will automatically pick this up and be called
“prefix-server-eth0.pcap”.
Finally, two of the methods shown above,
void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false); void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false);
have a default parameter called explicitFilename. When set to true,
this parameter disables the automatic filename completion mechanism and allows
you to create an explicit filename. This option is only available in the
methods which enable pcap tracing on a single device.
For example, in order to arrange for a device helper to create a single promiscuous pcap capture file of a specific name (“my-pcap-file.pcap”) on a given device, one could:
Ptr<NetDevice> nd;
...
helper.EnablePcap ("my-pcap-file.pcap", nd, true, true);
The first true parameter enables promiscuous mode traces and the second
tells the helper to interpret the prefix parameter as a complete filename.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The behavior of the ascii trace helper mixin is substantially similar to
the pcap version. Take a look at src/helper/trace-helper.h if you want to
follow the discussion while looking at real code.
The class AsciiTraceHelperForDevice adds the high level functionality for
using ascii tracing to a device helper class. As in the pcap case, every device
must implement a single virtual method inherited from the ascii trace mixin.
virtual void EnableAsciiInternal (Ptr<OutputStreamWrapper> stream, std::string prefix, Ptr<NetDevice> nd) = 0;
The signature of this method reflects the device-centric view of the situation
at this level; and also the fact that the helper may be writing to a shared
output stream. All of the public ascii-trace-related methods inherited from
class AsciiTraceHelperForDevice reduce to calling this single device-
dependent implementation method. For example, the lowest level ascii trace
methods,
void EnableAscii (std::string prefix, Ptr<NetDevice> nd);
void EnableAscii (Ptr<OutputStreamWrapper> stream, Ptr<NetDevice> nd);
@verbatim
will call the device implementation of @code{EnableAsciiInternal} directly,
providing either a valid prefix or stream. All other public ascii tracing
methods will build on these low-level functions to provide additional user-level
functionality. What this means to the user is that all device helpers in the
system will have all of the ascii trace methods available; and these methods
will all work in the same way across devices if the devices implement
@code{EnablAsciiInternal} correctly.
@subsubsection Ascii Tracing Device Helper Methods
@verbatim
void EnableAscii (std::string prefix, Ptr<NetDevice> nd);
void EnableAscii (Ptr<OutputStreamWrapper> stream, Ptr<NetDevice> nd);
void EnableAscii (std::string prefix, std::string ndName);
void EnableAscii (Ptr<OutputStreamWrapper> stream, std::string ndName);
void EnableAscii (std::string prefix, NetDeviceContainer d);
void EnableAscii (Ptr<OutputStreamWrapper> stream, NetDeviceContainer d);
void EnableAscii (std::string prefix, NodeContainer n);
void EnableAscii (Ptr<OutputStreamWrapper> stream, NodeContainer n);
void EnableAscii (std::string prefix, uint32_t nodeid, uint32_t deviceid);
void EnableAscii (Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t deviceid);
void EnableAsciiAll (std::string prefix);
void EnableAsciiAll (Ptr<OutputStreamWrapper> stream);
You are encouraged to peruse the Doxygen for class TraceHelperForDevice
to find the details of these methods; but to summarize ...
There are twice as many methods available for ascii tracing as there were for pcap tracing. This is because, in addition to the pcap-style model where traces from each unique node/device pair are written to a unique file, we support a model in which trace information for many node/device pairs is written to a common file. This means that the <prefix>-<node>-<device> file name generation mechanism is replaced by a mechanism to refer to a common file; and the number of API methods is doubled to allow all combinations.
Just as in pcap tracing, you can enable ascii tracing on a particular
node/net-device pair by providing a Ptr<NetDevice> to an EnableAscii
method. The Ptr<Node> is implicit since the net device must belong to
exactly one Node. For example,
Ptr<NetDevice> nd;
...
helper.EnableAscii ("prefix", nd);
In this case, no trace contexts are written to the ascii trace file since they would be redundant. The system will pick the file name to be created using the same rules as described in the pcap section, except that the file will have the suffix “.tr” instead of “.pcap”.
If you want to enable ascii tracing on more than one net device and have all traces sent to a single file, you can do that as well by using an object to refer to a single file:
Ptr<NetDevice> nd1;
Ptr<NetDevice> nd2;
...
Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
...
helper.EnableAscii (stream, nd1);
helper.EnableAscii (stream, nd2);
@verbatim
In this case, trace contexts are written to the ascii trace file since they
are required to disambiguate traces from the two devices. Note that since the
user is completely specifying the file name, the string should include the ``,tr''
for consistency.
You can enable ascii tracing on a particular node/net-device pair by providing a
@code{std::string} representing an object name service string to an
@code{EnablePcap} method. The @code{Ptr<NetDevice>} is looked up from the name
string. Again, the @code<Node> is implicit since the named net device must
belong to exactly one @code{Node}. For example,
@verbatim
Names::Add ("client" ...);
Names::Add ("client/eth0" ...);
Names::Add ("server" ...);
Names::Add ("server/eth0" ...);
...
helper.EnableAscii ("prefix", "client/eth0");
helper.EnableAscii ("prefix", "server/eth0");
This would result in two files named “prefix-client-eth0.tr” and “prefix-server-eth0.tr” with traces for each device in the respective trace file. Since all of the EnableAscii functions are overloaded to take a stream wrapper, you can use that form as well:
Names::Add ("client" ...);
Names::Add ("client/eth0" ...);
Names::Add ("server" ...);
Names::Add ("server/eth0" ...);
...
Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
...
helper.EnableAscii (stream, "client/eth0");
helper.EnableAscii (stream, "server/eth0");
This would result in a single trace file called “trace-file-name.tr” that contains all of the trace events for both devices. The events would be disambiguated by trace context strings.
You can enable ascii tracing on a collection of node/net-device pairs by
providing a NetDeviceContainer. For each NetDevice in the container
the type is checked. For each device of the proper type (the same type as is
managed by the device helper), tracing is enabled. Again, the @code<Node> is
implicit since the found net device must belong to exactly one Node.
For example,
NetDeviceContainer d = ...;
...
helper.EnableAscii ("prefix", d);
This would result in a number of ascii trace files being created, each of which follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the traces into a single file is accomplished similarly to the examples above:
NetDeviceContainer d = ...;
...
Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
...
helper.EnableAscii (stream, d);
You can enable ascii tracing on a collection of node/net-device pairs by
providing a NodeContainer. For each Node in the NodeContainer
its attached NetDevices are iterated. For each NetDevice attached
to each node in the container, the type of that device is checked. For each
device of the proper type (the same type as is managed by the device helper),
tracing is enabled.
NodeContainer n;
...
helper.EnableAscii ("prefix", n);
This would result in a number of ascii trace files being created, each of which follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the traces into a single file is accomplished similarly to the examples above:
You can enable pcap tracing on the basis of node ID and device ID as well as
with explicit Ptr. Each Node in the system has an integer node ID
and each device connected to a node has an integer device ID.
helper.EnableAscii ("prefix", 21, 1);
Of course, the traces can be combined into a single file as shown above.
Finally, you can enable pcap tracing for all devices in the system, with the same type as that managed by the device helper.
helper.EnableAsciiAll ("prefix");
This would result in a number of ascii trace files being created, one for every device in the system of the type managed by the helper. All of these files will follow the <prefix>-<node id>-<device id>.tr convention. Combining all of the traces into a single file is accomplished similarly to the examples above.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Implicit in the prefix-style method descriptions above is the construction of the
complete filenames by the implementation method. By convention, ascii traces
in the ns-3 system are of the form “<prefix>-<node id>-<device id>.tr”
As previously mentioned, every node in the system will have a system-assigned node id; and every device will have an interface index (also called a device id) relative to its node. By default, then, an ascii trace file created as a result of enabling tracing on the first device of node 21, using the prefix “prefix”, would be “prefix-21-1.tr”.
You can always use the ns-3 object name service to make this more clear.
For example, if you use the object name service to assign the name “server”
to node 21, the resulting ascii trace file name will automatically become,
“prefix-server-1.tr” and if you also assign the name “eth0” to the
device, your ascii trace file name will automatically pick this up and be called
“prefix-server-eth0.tr”.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The goal of these mixins is to make it easy to add a consistent pcap trace
facility to protocols. We want all of the various flavors of pcap tracing to
work the same across all protocols, so the methods of these helpers are
inherited by stack helpers. Take a look at src/helper/trace-helper.h
if you want to follow the discussion while looking at real code.
In this section we will be illustrating the methods as applied to the protocol
Ipv4. To specify traces in similar protocols, just substitute the
appropriate type. For example, use a Ptr<Ipv6> instead of a
Ptr<Ipv4> and call EnablePcapIpv6 instead of EnablePcapIpv4.
The class PcapHelperForIpv4 provides the high level functionality for
using pcap tracing in the Ipv4 protocol. Each protocol helper enabling these
methods must implement a single virtual method inherited from this class. There
will be a separate implementation for Ipv6, for example, but the only
difference will be in the method names and signatures. Different method names
are required to disambiguate class Ipv4 from Ipv6 which are both
derived from class Object, and methods that share the same signature.
virtual void EnablePcapIpv4Internal (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface) = 0;
The signature of this method reflects the protocol and interface-centric view
of the situation at this level. All of the public methods inherited from class
PcapHelperForIpv4 reduce to calling this single device-dependent
implementation method. For example, the lowest level pcap method,
void EnablePcapIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
@verbatim
will call the device implementation of @code{EnablePcapIpv4Internal} directly.
All other public pcap tracing methods build on this implementation to provide
additional user-level functionality. What this means to the user is that all
protocol helpers in the system will have all of the pcap trace methods
available; and these methods will all work in the same way across
protocols if the helper implements @code{EnablePcapIpv4Internal} correctly.
@subsubsection Pcap Tracing Protocol Helper Methods
These methods are designed to be in one-to-one correspondence with the @code{Node}-
and @code{NetDevice}- centric versions of the device versions. Instead of
@code{Node} and @code{NetDevice} pair constraints, we use protocol and interface
constraints.
Note that just like in the device version, there are six methods:
@verbatim
void EnablePcapIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
void EnablePcapIpv4 (std::string prefix, std::string ipv4Name, uint32_t interface);
void EnablePcapIpv4 (std::string prefix, Ipv4InterfaceContainer c);
void EnablePcapIpv4 (std::string prefix, NodeContainer n);
void EnablePcapIpv4 (std::string prefix, uint32_t nodeid, uint32_t interface);
void EnablePcapIpv4All (std::string prefix);
You are encouraged to peruse the Doxygen for class PcapHelperForIpv4
to find the details of these methods; but to summarize ...
You can enable pcap tracing on a particular protocol/interface pair by providing a
Ptr<Ipv4> and interface to an EnablePcap method. For example,
Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
...
helper.EnablePcapIpv4 ("prefix", ipv4, 0);
You can enable pcap tracing on a particular node/net-device pair by providing a
std::string representing an object name service string to an
EnablePcap method. The Ptr<Ipv4> is looked up from the name
string. For example,
Names::Add ("serverIPv4" ...);
...
helper.EnablePcapIpv4 ("prefix", "serverIpv4", 1);
You can enable pcap tracing on a collection of protocol/interface pairs by
providing an Ipv4InterfaceContainer. For each Ipv4 / interface
pair in the container the protocol type is checked. For each protocol of the
proper type (the same type as is managed by the device helper), tracing is
enabled for the corresponding interface. For example,
NodeContainer nodes;
...
NetDeviceContainer devices = deviceHelper.Install (nodes);
...
Ipv4AddressHelper ipv4;
ipv4.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
...
helper.EnablePcapIpv4 ("prefix", interfaces);
You can enable pcap tracing on a collection of protocol/interface pairs by
providing a NodeContainer. For each Node in the NodeContainer
the appropriate protocol is found. For each protocol, its interfaces are
enumerated and tracing is enabled on the resulting pairs. For example,
NodeContainer n;
...
helper.EnablePcapIpv4 ("prefix", n);
You can enable pcap tracing on the basis of node ID and interface as well. In
this case, the node-id is translated to a Ptr<Node> and the appropriate
protocol is looked up in the node. The resulting protocol and interface are
used to specify the resulting trace source.
helper.EnablePcapIpv4 ("prefix", 21, 1);
Finally, you can enable pcap tracing for all interfaces in the system, with associated protocol being the same type as that managed by the device helper.
helper.EnablePcapIpv4All ("prefix");
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Implicit in all of the method descriptions above is the construction of the
complete filenames by the implementation method. By convention, pcap traces
taken for devices in the ns-3 system are of the form
“<prefix>-<node id>-<device id>.pcap”. In the case of protocol traces,
there is a one-to-one correspondence between protocols and Nodes.
This is because protocol Objects are aggregated to Node Objects.
Since there is no global protocol id in the system, we use the corresponding
node id in file naming. Therefore there is a possibility for file name
collisions in automatically chosen trace file names. For this reason, the
file name convention is changed for protocol traces.
As previously mentioned, every node in the system will have a system-assigned node id. Since there is a one-to-one correspondence between protocol instances and node instances we use the node id. Each interface has an interface id relative to its protocol. We use the convention "<prefix>-n<node id>-i<interface id>.pcap" for trace file naming in protocol helpers.
Therefore, by default, a pcap trace file created as a result of enabling tracing on interface 1 of the Ipv4 protocol of node 21 using the prefix “prefix” would be “prefix-n21-i1.pcap”.
You can always use the ns-3 object name service to make this more clear.
For example, if you use the object name service to assign the name “serverIpv4”
to the Ptr<Ipv4> on node 21, the resulting pcap trace file name will
automatically become, “prefix-nserverIpv4-i1.pcap”.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The behavior of the ascii trace helpers is substantially similar to the pcap
case. Take a look at src/helper/trace-helper.h if you want to
follow the discussion while looking at real code.
In this section we will be illustrating the methods as applied to the protocol
Ipv4. To specify traces in similar protocols, just substitute the
appropriate type. For example, use a Ptr<Ipv6> instead of a
Ptr<Ipv4> and call EnableAsciiIpv6 instead of EnableAsciiIpv4.
The class AsciiTraceHelperForIpv4 adds the high level functionality
for using ascii tracing to a protocol helper. Each protocol that enables these
methods must implement a single virtual method inherited from this class.
virtual void EnableAsciiIpv4Internal (Ptr<OutputStreamWrapper> stream, std::string prefix,
Ptr<Ipv4> ipv4, uint32_t interface) = 0;
The signature of this method reflects the protocol- and interface-centric view
of the situation at this level; and also the fact that the helper may be writing
to a shared output stream. All of the public methods inherited from class
PcapAndAsciiTraceHelperForIpv4 reduce to calling this single device-
dependent implementation method. For example, the lowest level ascii trace
methods,
void EnableAsciiIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ptr<Ipv4> ipv4, uint32_t interface);
@verbatim
will call the device implementation of @code{EnableAsciiIpv4Internal} directly,
providing either the prefix or the stream. All other public ascii tracing
methods will build on these low-level functions to provide additional user-level
functionality. What this means to the user is that all device helpers in the
system will have all of the ascii trace methods available; and these methods
will all work in the same way across protocols if the protocols implement
@code{EnablAsciiIpv4Internal} correctly.
@subsubsection Ascii Tracing Device Helper Methods
@verbatim
void EnableAsciiIpv4 (std::string prefix, Ptr<Ipv4> ipv4, uint32_t interface);
void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ptr<Ipv4> ipv4, uint32_t interface);
void EnableAsciiIpv4 (std::string prefix, std::string ipv4Name, uint32_t interface);
void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, std::string ipv4Name, uint32_t interface);
void EnableAsciiIpv4 (std::string prefix, Ipv4InterfaceContainer c);
void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, Ipv4InterfaceContainer c);
void EnableAsciiIpv4 (std::string prefix, NodeContainer n);
void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, NodeContainer n);
void EnableAsciiIpv4 (std::string prefix, uint32_t nodeid, uint32_t deviceid);
void EnableAsciiIpv4 (Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t interface);
void EnableAsciiIpv4All (std::string prefix);
void EnableAsciiIpv4All (Ptr<OutputStreamWrapper> stream);
You are encouraged to peruse the Doxygen for class PcapAndAsciiHelperForIpv4
to find the details of these methods; but to summarize ...
There are twice as many methods available for ascii tracing as there were for pcap tracing. This is because, in addition to the pcap-style model where traces from each unique protocol/interface pair are written to a unique file, we support a model in which trace information for many protocol/interface pairs is written to a common file. This means that the <prefix>-n<node id>-<interface> file name generation mechanism is replaced by a mechanism to refer to a common file; and the number of API methods is doubled to allow all combinations.
Just as in pcap tracing, you can enable ascii tracing on a particular
protocol/interface pair by providing a Ptr<Ipv4> and an interface
to an EnableAscii method.
For example,
Ptr<Ipv4> ipv4;
...
helper.EnableAsciiIpv4 ("prefix", ipv4, 1);
In this case, no trace contexts are written to the ascii trace file since they would be redundant. The system will pick the file name to be created using the same rules as described in the pcap section, except that the file will have the suffix “.tr” instead of “.pcap”.
If you want to enable ascii tracing on more than one interface and have all traces sent to a single file, you can do that as well by using an object to refer to a single file. We have already something similar to this in the “cwnd” example above:
Ptr<Ipv4> protocol1 = node1->GetObject<Ipv4> ();
Ptr<Ipv4> protocol2 = node2->GetObject<Ipv4> ();
...
Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
...
helper.EnableAsciiIpv4 (stream, protocol1, 1);
helper.EnableAsciiIpv4 (stream, protocol2, 1);
@verbatim
In this case, trace contexts are written to the ascii trace file since they
are required to disambiguate traces from the two interfaces. Note that since
the user is completely specifying the file name, the string should include the
``,tr'' for consistency.
You can enable ascii tracing on a particular protocol by providing a
@code{std::string} representing an object name service string to an
@code{EnablePcap} method. The @code{Ptr<Ipv4>} is looked up from the name
string. The @code<Node> in the resulting filenames is implicit since there
is a one-to-one correspondence between protocol instances and nodes,
For example,
@verbatim
Names::Add ("node1Ipv4" ...);
Names::Add ("node2Ipv4" ...);
...
helper.EnableAsciiIpv4 ("prefix", "node1Ipv4", 1);
helper.EnableAsciiIpv4 ("prefix", "node2Ipv4", 1);
This would result in two files named “prefix-nnode1Ipv4-i1.tr” and “prefix-nnode2Ipv4-i1.tr” with traces for each interface in the respective trace file. Since all of the EnableAscii functions are overloaded to take a stream wrapper, you can use that form as well:
Names::Add ("node1Ipv4" ...);
Names::Add ("node2Ipv4" ...);
...
Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
...
helper.EnableAsciiIpv4 (stream, "node1Ipv4", 1);
helper.EnableAsciiIpv4 (stream, "node2Ipv4", 1);
This would result in a single trace file called “trace-file-name.tr” that contains all of the trace events for both interfaces. The events would be disambiguated by trace context strings.
You can enable ascii tracing on a collection of protocol/interface pairs by
providing an Ipv4InterfaceContainer. For each protocol of the proper
type (the same type as is managed by the device helper), tracing is enabled
for the corresponding interface. Again, the @code<Node> is implicit since
there is a one-to-one correspondence between each protocol and its node.
For example,
NodeContainer nodes;
...
NetDeviceContainer devices = deviceHelper.Install (nodes);
...
Ipv4AddressHelper ipv4;
ipv4.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
...
...
helper.EnableAsciiIpv4 ("prefix", interfaces);
This would result in a number of ascii trace files being created, each of which follows the <prefix>-n<node id>-i<interface>.tr convention. Combining all of the traces into a single file is accomplished similarly to the examples above:
NodeContainer nodes;
...
NetDeviceContainer devices = deviceHelper.Install (nodes);
...
Ipv4AddressHelper ipv4;
ipv4.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer interfaces = ipv4.Assign (devices);
...
Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("trace-file-name.tr");
...
helper.EnableAsciiIpv4 (stream, interfaces);
You can enable ascii tracing on a collection of protocol/interface pairs by
providing a NodeContainer. For each Node in the NodeContainer
the appropriate protocol is found. For each protocol, its interfaces are
enumerated and tracing is enabled on the resulting pairs. For example,
NodeContainer n;
...
helper.EnableAsciiIpv4 ("prefix", n);
This would result in a number of ascii trace files being created, each of which follows the <prefix>-<node id>-<device id>.tr convention. Combining all of the traces into a single file is accomplished similarly to the examples above:
You can enable pcap tracing on the basis of node ID and device ID as well. In
this case, the node-id is translated to a Ptr<Node> and the appropriate
protocol is looked up in the node. The resulting protocol and interface are
used to specify the resulting trace source.
helper.EnableAsciiIpv4 ("prefix", 21, 1);
Of course, the traces can be combined into a single file as shown above.
Finally, you can enable ascii tracing for all interfaces in the system, with associated protocol being the same type as that managed by the device helper.
helper.EnableAsciiIpv4All ("prefix");
This would result in a number of ascii trace files being created, one for every interface in the system related to a protocol of the type managed by the helper. All of these files will follow the <prefix>-n<node id>-i<interface.tr convention. Combining all of the traces into a single file is accomplished similarly to the examples above.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Implicit in the prefix-style method descriptions above is the construction of the
complete filenames by the implementation method. By convention, ascii traces
in the ns-3 system are of the form “<prefix>-<node id>-<device id>.tr”
As previously mentioned, every node in the system will have a system-assigned node id. Since there is a one-to-one correspondence between protocols and nodes we use to node-id to identify the protocol identity. Every interface on a given protocol will have an interface index (also called simply an interface) relative to its protocol. By default, then, an ascii trace file created as a result of enabling tracing on the first device of node 21, using the prefix “prefix”, would be “prefix-n21-i1.tr”. Use the prefix to disambiguate multiple protocols per node.
You can always use the ns-3 object name service to make this more clear.
For example, if you use the object name service to assign the name “serverIpv4”
to the protocol on node 21, and also specify interface one, the resulting ascii
trace file name will automatically become, “prefix-nserverIpv4-1.tr”.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated on August 20, 2010 using texi2html 1.82.