Index: doc/tutorial/source/data-collection.rst |
=================================================================== |
--- a/doc/tutorial/source/data-collection.rst |
+++ b/doc/tutorial/source/data-collection.rst |
@@ -7,8 +7,8 @@ |
--------------- |
Our final tutorial chapter introduces some components that were added |
-to |ns3| in version 3.18, and that are still under development. This |
-tutorial section is also a work-in-progress. |
+to |ns3| starting with version 3.18, and that are still under development. |
+This tutorial section is also a work-in-progress. |
Motivation |
********** |
@@ -122,22 +122,20 @@ |
+ GnuplotHelper plotHelper; |
+ |
+ // Configure the plot. The first argument is the file name prefix |
- + // for the output files generated. The second, third, and fourth |
- + // arguments are, respectively, the plot title, x-axis, and y-axis labels |
- + plotHelper.ConfigurePlot ("seventh-packet-byte-count", |
- + "Packet Byte Count vs. Time", |
- + "Time (Seconds)", |
- + "Packet Byte Count"); |
- + |
- + // Specify the probe type, trace source path (in configuration namespace), and |
- + // probe output trace source ("OutputBytes") to plot. The fourth argument |
- + // specifies the name of the data series label on the plot. The last |
- + // argument formats the plot by specifying where the key should be placed. |
- + plotHelper.PlotProbe (probeType, |
- + tracePath, |
- + "OutputBytes", |
- + "Packet Byte Count", |
- + GnuplotAggregator::KEY_BELOW); |
+ + // for the output files generated. The second, third, and fourth |
+ + // arguments are, respectively, the plot title, x-axis, and y-axis labels |
+ + plotHelper.ConfigurePlot ("seventh-packet-byte-count", |
+ + "Packet Byte Count vs. Time", |
+ + "Time (Seconds)", |
+ + "Packet Byte Count"); |
+ + |
+ + // Specify the probe type, trace source path (in configuration namespace), and |
+ + // probe output trace source ("OutputBytes") to plot. The fourth argument |
+ + // specifies the name of the data series label on the plot. |
+ + plotHelper.AddProbe (probeType, |
+ + tracePath, |
+ + "OutputBytes", |
+ + "Packet Byte Count"); |
+ |
+ // Use FileHelper to write out the packet byte count over time |
+ FileHelper fileHelper; |
@@ -270,13 +268,11 @@ |
+ // Specify the probe type, trace source path (in configuration namespace), and |
+ // probe output trace source ("OutputBytes") to plot. The fourth argument |
- + // specifies the name of the data series label on the plot. The last |
- + // argument formats the plot by specifying where the key should be placed. |
- + plotHelper.PlotProbe (probeType, |
- + tracePath, |
- + "OutputBytes", |
- + "Packet Byte Count", |
- + GnuplotAggregator::KEY_BELOW); |
+ + // specifies the name of the data series label on the plot. |
+ + plotHelper.AddProbe (probeType, |
+ + tracePath, |
+ + "OutputBytes", |
+ + "Packet Byte Count"); |
The first two arguments are the name of the probe type and the trace source path. |
These two are probably the hardest to determine when you try to use |
@@ -288,7 +284,8 @@ |
:: |
.AddTraceSource ("Tx", "Send IPv6 packet to outgoing interface.", |
- MakeTraceSourceAccessor (&Ipv6L3Protocol::m_txTrace)) |
+ MakeTraceSourceAccessor (&Ipv6L3Protocol::m_txTrace), |
+ "ns3::Ipv6L3Protocol::TxRxTracedCallback") |
This says that ``Tx`` is a name for variable ``m_txTrace``, which has |
a declaration of: |
@@ -300,11 +297,32 @@ |
*/ |
TracedCallback<Ptr<const Packet>, Ptr<Ipv6>, uint32_t> m_txTrace; |
+ |
+The last argument specifies that it is a TxRxTracedCallback; this |
+documentation string allows the signature to be easily found using |
+Doxygen. If we look at this signature in the same header file, we can |
+see also: |
+ |
+:: |
+ |
+ /** |
+ * TracedCallback signature for packet transmission or reception events. |
+ * |
+ * \param [in] packet The packet. |
+ * \param [in] ipv6 |
+ * \param [in] interface |
+ */ |
+ typedef void (* TxRxTracedCallback) |
+ (const Ptr<const Packet> packet, const Ptr<const Ipv6> ipv6, |
+ const uint32_t interface); |
+ |
+i.e. the same information about the arguments is present in this typedef. |
+ |
It turns out that this specific trace source signature is supported |
by a Probe class (what we need here) of class Ipv6PacketProbe. |
See the files ``src/internet/model/ipv6-packet-probe.{h,cc}``. |
-So, in the PlotProbe statement above, we see that the statement is |
+So, in the AddProbe statement above, we see that the statement is |
hooking the trace source (identified by path string) with a matching |
|ns3| Probe type of ``Ipv6PacketProbe``. If we did not support |
this probe type (matching trace source signature), we could have not |
@@ -324,17 +342,20 @@ |
.SetGroupName ("Stats") |
.AddConstructor<Ipv6PacketProbe> () |
.AddTraceSource ( "Output", |
- "The packet plus its IPv6 object and interface that serve as the output for this probe", |
- MakeTraceSourceAccessor (&Ipv6PacketProbe::m_output)) |
+ "The packet plus its IPv6 object and interface " |
+ "that serve as the output for this probe", |
+ MakeTraceSourceAccessor (&Ipv6PacketProbe::m_output), |
+ "ns3::Ipv6PacketProbe::TracedCallback") |
.AddTraceSource ( "OutputBytes", |
"The number of bytes in the packet", |
- MakeTraceSourceAccessor (&Ipv6PacketProbe::m_outputBytes)) |
+ MakeTraceSourceAccessor (&Ipv6PacketProbe::m_outputBytes), |
+ "ns3::Packet::PacketSizeTracedCallback") |
; |
return tid; |
} |
-The third argument of our PlotProbe statement specifies that we are |
+The third argument of our AddProbe statement specifies that we are |
interested in the number of bytes in this packet; specifically, the |
"OutputBytes" trace source of Ipv6PacketProbe. |
Finally, the last two arguments of the statement provide the plot |
@@ -343,6 +364,31 @@ |
the plot key to be inserted below the plot. Other options include |
NO_KEY, KEY_INSIDE, and KEY_ABOVE. |
+Multiple data series can be added to a single plot. |
+This can be done by repeatedly calling ``AddProbe()`` such as in the |
+previous example (avoiding the use of wildcards): |
+ |
+:: |
+ |
+ tracePath = "/NodeList/0/$ns3::Ipv4L3Protocol/Tx"; |
+ plotHelper.AddProbe (probeType, |
+ tracePath, |
+ "OutputBytes", |
+ "Packet Byte Count for node 0"); |
+ tracePath = "/NodeList/1/$ns3::Ipv4L3Protocol/Tx"; |
+ plotHelper.AddProbe (probeType, |
+ tracePath, |
+ "OutputBytes", |
+ "Packet Byte Count for node 1"); |
+ |
+Finally, by default, the helper uses a Collector type of |
+``ns3::EventDrivenCollector`` which does not do any processing |
+of the data generated asynchronously by the trace sources. Other |
+Collector types are possible, such as a TimeSeriesCollector to |
+generate periodic time-series, a TimeAverageCollector to generate |
+rates (such as data rate from an interface, sampled every second), |
+and the ability to scale the Y-axis data using a ScalingCollector. |
+More details can be found in the |ns3| manual. |
Supported Trace Types |
********************* |