ns-3.24: comparison src/stats/doc/data-collection-helpers.rst

equal deleted inserted replaced

-:19b4146b1d39
+:e943837b17ad
 const std::string &title,
 const std::string &xLegend,
 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:
 ::
 void PlotProbe (const std::string &typeId,
 const std::string &path,
 const std::string &title);
 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
+* path:  The path in the |ns3| configuration namespace to one or more trace sources
-* probeTraceSource:  Which output of the probe should be connected to
+* probeTraceSource:  Which output of the probe (itself a trace source) should be plotted
-* title:  The title to associate with the dataset (in the gnuplot legend)
+* 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.
 A fully worked example (from ``seventh.cc``) is shown below:
 // Create the gnuplot helper.
 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.
+// Specify the probe type, trace source path (in configuration namespace), and
-plotHelper.PlotProbe ("ns3::Ipv4PacketProbe",
+// probe output trace source ("OutputBytes") to plot.  The fourth argument
-"/NodeList/*/$ns3::Ipv4L3Protocol/Tx",
+// 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:
 ::
 +------------------+------------------------------+
 | 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.                      |
 +------------------+------------------------------+
 | title            | The title to be associated   |
 |                  | location is inside.          |
 +------------------+------------------------------+
 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.
 If the config path has more than one match in the system because
 there is a wildcard, then one dataset for each match will
 is the string "bytes", and there are two wildcards in the path,
 then dataset titles like "bytes-0 0" or "bytes-12 9" will be
 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:
 ::
 plotHelper.PlotProbe ("ns3::Ipv4PacketProbe",
 "/NodeList/*/$ns3::Ipv4L3Protocol/Tx",
 Gnuplot Helper Example
 ~~~~~~~~~~~~~~~~~~~~~~
 A slightly simpler example than the ``seventh.cc`` example can be
-found in ``src/stats/examples/gnuplot-helper-example.cc``.  It
+found in ``src/stats/examples/gnuplot-helper-example.cc``.  The
-is more of a toy example than ``seventh.cc`` because it has
+following 2-D gnuplot was created using the example.
-a made-up trace source created for demonstration purposes.
-The following 2-D gnuplot was created using the example.
 .. _gnuplot-helper-example:
 .. figure:: figures/gnuplot-helper-example.png
 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.
 ::
 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.
 ::
 // Create the gnuplot helper.
 "Emitter Count",
 "png");
 // Plot the values generated by the probe.  The path that we provide
 // helps to disambiguate the source of the trace.
-plotHelper.PlotProbe ("ns3::DoubleProbe",
+plotHelper.PlotProbe ("ns3::Uinteger32Probe",
-"/Names/Probe/Output",
+"/Names/Emitter/Counter",
 "Output",
 "Emitter Count",
 GnuplotAggregator::KEY_INSIDE);
 FileHelper
 +------------------+------------------------------+
 | 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.                      |
 +------------------+------------------------------+
 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.
 If the config path has more than one match in the system because
 File Helper Example
 ~~~~~~~~~~~~~~~~~~~
 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
+This example only uses the FileHelper.
-is also more of a toy example than ``seventh.cc`` because it has
-a made-up trace source created for demonstration purposes.
 The following text file with 2 columns of formatted values named
 ``file-helper-example.txt`` was created using the example.
 Only the first 10 lines of this file are shown here for brevity.
 .. sourcecode:: text
-Time (Seconds) = 4.995e-01	Count = 1
+Time (Seconds) = 0.203  Count = 1
-Time (Seconds) = 1.463e+00	Count = 2
+Time (Seconds) = 0.702  Count = 2
-Time (Seconds) = 1.678e+00	Count = 3
+Time (Seconds) = 1.404  Count = 3
-Time (Seconds) = 3.972e+00	Count = 4
+Time (Seconds) = 2.368  Count = 4
-Time (Seconds) = 4.150e+00	Count = 5
+Time (Seconds) = 3.364  Count = 5
-Time (Seconds) = 8.066e+00	Count = 6
+Time (Seconds) = 3.579  Count = 6
-Time (Seconds) = 8.731e+00	Count = 7
+Time (Seconds) = 5.873  Count = 7
-Time (Seconds) = 9.807e+00	Count = 8
+Time (Seconds) = 6.410  Count = 8
-Time (Seconds) = 1.078e+01	Count = 9
+Time (Seconds) = 6.472  Count = 9
-Time (Seconds) = 1.083e+01	Count = 10
 ...
 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.
 ::
 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
 "file-helper-example.txt", with no extra suffixes like
 // Set the labels for this formatted output file.
 fileHelper.Set2dFormat ("Time (Seconds) = %.3e\tCount = %.0f");
 // Write the values generated by the probe.  The path that we
 // provide helps to disambiguate the source of the trace.
-fileHelper.WriteProbe ("ns3::DoubleProbe",
+fileHelper.WriteProbe ("ns3::Uinteger32Probe",
-"/Names/Probe/Output",
+"/Names/Emitter/Counter",
 "Output");
 Scope and Limitations
 =====================
 - Uinteger32Probe
 - PacketProbe
 - 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
 types (Probe, Collector, and Aggregator) in more detail, and show
 how they can be connected together using lower-level API.

changeset 11027	e943837b17ad
parent 10408	5c604e8ec2e1
child 11028	abeb2185bce5