--- a/src/stats/doc/data-collection-helpers.rst Tue Oct 14 13:29:05 2014 -0700
+++ b/src/stats/doc/data-collection-helpers.rst Wed Oct 15 07:00:24 2014 -0700
@@ -75,7 +75,7 @@
const std::string &yLegend,
const std::string &terminalType = ".png");
-The second statement hooks the ``Probe`` of interest:
+The second statement hooks the trace source of interest:
::
@@ -87,9 +87,9 @@
The arguments are as follows:
* typeId: The |ns3| TypeId of the Probe
-* path: The path in the |ns3| configuration namespace to one or more probes
-* probeTraceSource: Which output of the probe should be connected to
-* title: The title to associate with the dataset (in the gnuplot legend)
+* path: The path in the |ns3| configuration namespace to one or more trace sources
+* probeTraceSource: Which output of the probe (itself a trace source) should be plotted
+* title: The title to associate with the dataset(s) (in the gnuplot legend)
A variant on the PlotProbe above is to specify a fifth optional argument
that controls where in the plot the key (legend) is placed.
@@ -102,20 +102,41 @@
GnuplotHelper plotHelper;
// Configure the plot.
+ // 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",
"png");
- // Plot the values generated by the probe.
- plotHelper.PlotProbe ("ns3::Ipv4PacketProbe",
- "/NodeList/*/$ns3::Ipv4L3Protocol/Tx",
+ // 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);
-Note that the path specified may contain wildcards. In this case, multiple
+In this example, the ``probeType`` and ``tracePath`` are as follows (for IPv4):
+
+::
+
+ probeType = "ns3::Ipv4PacketProbe";
+ tracePath = "/NodeList/*/$ns3::Ipv4L3Protocol/Tx";
+
+The probeType is a key parameter for this helper to work. This TypeId
+must be registered in the system, and the signature on the Probe's trace
+sink must match that of the trace source it is being hooked to. Probe
+types are pre-defined for a number of data types corresponding to |ns3|
+traced values, and for a few other trace source signatures such as the
+'Tx' trace source of ``ns3::Ipv4L3Protocol`` class.
+
+Note that the trace source path specified may contain wildcards.
+In this case, multiple
datasets are plotted on one plot; one for each matched path.
The main output produced will be three files:
@@ -224,10 +245,10 @@
| Argument | Description |
+==================+==============================+
| typeId | The type ID for the probe |
- | | used when it is created. |
+ | | created by this helper. |
+------------------+------------------------------+
| path | Config path to access the |
- | | probe. |
+ | | trace source. |
+------------------+------------------------------+
| probeTraceSource | The probe trace source to |
| | access. |
@@ -242,7 +263,8 @@
The GnuplotHelper's ``PlotProbe()`` function
plots a dataset generated by hooking the |ns3| trace source with a
-probe, and then plotting the values from the probeTraceSource.
+probe created by the helper, and then plotting the values from the
+probeTraceSource.
The dataset will have the provided title, and will consist of
the 'newValue' at each timestamp.
@@ -256,7 +278,8 @@
possible as labels for the datasets that are plotted.
An example of how to use this function can be seen in the
-``seventh.cc`` code described above where it was used as follows:
+``seventh.cc`` code described above where it was used (with
+variable substitution) as follows:
::
@@ -273,11 +296,8 @@
~~~~~~~~~~~~~~~~~~~~~~
A slightly simpler example than the ``seventh.cc`` example can be
-found in ``src/stats/examples/gnuplot-helper-example.cc``. It
-is more of a toy example than ``seventh.cc`` because it has
-a made-up trace source created for demonstration purposes.
-
-The following 2-D gnuplot was created using the example.
+found in ``src/stats/examples/gnuplot-helper-example.cc``. The
+following 2-D gnuplot was created using the example.
.. _gnuplot-helper-example:
@@ -286,7 +306,7 @@
2-D Gnuplot Created by gnuplot-helper-example.cc Example.
In this example, there is an Emitter object that increments
-its counter at various random times and then emits the counter's
+its counter according to a Poisson process and then emits the counter's
value as a trace source.
::
@@ -294,25 +314,10 @@
Ptr<Emitter> emitter = CreateObject<Emitter> ();
Names::Add ("/Names/Emitter", emitter);
-The following code is probing the Counter exported by the
-emitter object. This DoubleProbe is using a path in the
-configuration namespace to make the connection. Note that
-the emitter registered itself in the configuration namespace
-after it was created; otherwise, the ConnectByPath would not work.
-
-::
-
- Ptr<DoubleProbe> probe = CreateObject<DoubleProbe> ();
- probe->SetName ("PathProbe");
- Names::Add ("/Names/Probe", probe);
-
- // Note, no return value is checked here.
- probe->ConnectByPath ("/Names/Emitter/Counter");
-
Note that because there are no wildcards in the path
used below, only 1 datastream was drawn in the plot.
This single datastream in the plot is simply labeled
-"Emitter Count", with no extra suffixes like you would
+"Emitter Count", with no extra suffixes like one would
see if there were wildcards in the path.
::
@@ -329,8 +334,8 @@
// Plot the values generated by the probe. The path that we provide
// helps to disambiguate the source of the trace.
- plotHelper.PlotProbe ("ns3::DoubleProbe",
- "/Names/Probe/Output",
+ plotHelper.PlotProbe ("ns3::Uinteger32Probe",
+ "/Names/Emitter/Counter",
"Output",
"Emitter Count",
GnuplotAggregator::KEY_INSIDE);
@@ -492,10 +497,10 @@
| Argument | Description |
+==================+==============================+
| typeId | The type ID for the probe |
- | | used when it is created. |
+ | | to be created. |
+------------------+------------------------------+
| path | Config path to access the |
- | | probe. |
+ | | trace source. |
+------------------+------------------------------+
| probeTraceSource | The probe trace source to |
| | access. |
@@ -503,7 +508,7 @@
The FileHelper's ``WriteProbe()`` function
creates output text files generated by hooking the ns-3 trace source
-with a probe, and then writing the values from the
+with a probe created by the helper, and then writing the values from the
probeTraceSource. The output file names will have the text stored
in the member variable m_outputFileNameWithoutExtension plus ".txt",
and will consist of the 'newValue' at each timestamp.
@@ -537,9 +542,7 @@
A slightly simpler example than the ``seventh.cc`` example can be
found in ``src/stats/examples/file-helper-example.cc``.
-This example only uses the FileHelper, not the FileHelper. It
-is also more of a toy example than ``seventh.cc`` because it has
-a made-up trace source created for demonstration purposes.
+This example only uses the FileHelper.
The following text file with 2 columns of formatted values named
``file-helper-example.txt`` was created using the example.
@@ -547,21 +550,19 @@
.. sourcecode:: text
- Time (Seconds) = 4.995e-01 Count = 1
- Time (Seconds) = 1.463e+00 Count = 2
- Time (Seconds) = 1.678e+00 Count = 3
- Time (Seconds) = 3.972e+00 Count = 4
- Time (Seconds) = 4.150e+00 Count = 5
- Time (Seconds) = 8.066e+00 Count = 6
- Time (Seconds) = 8.731e+00 Count = 7
- Time (Seconds) = 9.807e+00 Count = 8
- Time (Seconds) = 1.078e+01 Count = 9
- Time (Seconds) = 1.083e+01 Count = 10
-
+ Time (Seconds) = 0.203 Count = 1
+ Time (Seconds) = 0.702 Count = 2
+ Time (Seconds) = 1.404 Count = 3
+ Time (Seconds) = 2.368 Count = 4
+ Time (Seconds) = 3.364 Count = 5
+ Time (Seconds) = 3.579 Count = 6
+ Time (Seconds) = 5.873 Count = 7
+ Time (Seconds) = 6.410 Count = 8
+ Time (Seconds) = 6.472 Count = 9
...
In this example, there is an Emitter object that increments
-its counter at various random times and then emits the counter's
+its counter according to a Poisson process and then emits the counter's
value as a trace source.
::
@@ -569,21 +570,6 @@
Ptr<Emitter> emitter = CreateObject<Emitter> ();
Names::Add ("/Names/Emitter", emitter);
-The following code is probing the Counter exported by the
-emitter object. This DoubleProbe is using a path in the
-configuration namespace to make the connection. Note that
-the emitter registered itself in the configuration namespace
-after it was created; otherwise, the ConnectByPath would not work.
-
-::
-
- Ptr<DoubleProbe> probe = CreateObject<DoubleProbe> ();
- probe->SetName ("PathProbe");
- Names::Add ("/Names/Probe", probe);
-
- // Note, no return value is checked here.
- probe->ConnectByPath ("/Names/Emitter/Counter");
-
Note that because there are no wildcards in the path
used below, only 1 text file was created.
This single text file is simply named
@@ -604,8 +590,8 @@
// Write the values generated by the probe. The path that we
// provide helps to disambiguate the source of the trace.
- fileHelper.WriteProbe ("ns3::DoubleProbe",
- "/Names/Probe/Output",
+ fileHelper.WriteProbe ("ns3::Uinteger32Probe",
+ "/Names/Emitter/Counter",
"Output");
Scope and Limitations
@@ -623,7 +609,7 @@
- ApplicationPacketProbe
- Ipv4PacketProbe
-These Probes, therefore, are the only ones available to be used
+These Probes, therefore, are the only TypeIds available to be used
in ``PlotProbe()`` and ``WriteProbe()``.
In the next few sections, we cover each of the fundamental object