From 5b64122a3e801a704db70c19b569f6f965f369bf Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Wed, 15 Oct 2014 07:00:24 -0700 Subject: [PATCH] bug 1997: fix PlotProbe() documentation and usage for GnuplotHelper and FileHelper --- doc/tutorial/source/data-collection.rst | 50 +++---- examples/tutorial/seventh.cc | 24 ++-- src/stats/doc/data-collection-helpers.rst | 130 +++++++++---------- src/stats/examples/file-helper-example.cc | 39 ++---- src/stats/examples/gnuplot-helper-example.cc | 48 ++----- src/stats/helper/file-helper.h | 29 +++-- src/stats/helper/gnuplot-helper.cc | 11 +- src/stats/helper/gnuplot-helper.h | 30 +++-- src/stats/model/double-probe.cc | 4 +- 9 files changed, 162 insertions(+), 203 deletions(-) diff --git a/doc/tutorial/source/data-collection.rst b/doc/tutorial/source/data-collection.rst index 817d4f935..79b8d5998 100644 --- a/doc/tutorial/source/data-collection.rst +++ b/doc/tutorial/source/data-collection.rst @@ -103,19 +103,19 @@ some of the new lines of this diff: :: - + std::string probeName; - + std::string probeTrace; + + std::string probeType; + + std::string tracePath; + if (useV6 == false) + { ... - + probeName = "ns3::Ipv4PacketProbe"; - + probeTrace = "/NodeList/*/$ns3::Ipv4L3Protocol/Tx"; + + probeType = "ns3::Ipv4PacketProbe"; + + tracePath = "/NodeList/*/$ns3::Ipv4L3Protocol/Tx"; + } + else + { ... - + probeName = "ns3::Ipv6PacketProbe"; - + probeTrace = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; + + probeType = "ns3::Ipv6PacketProbe"; + + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; + } ... + // Use GnuplotHelper to plot the packet byte count over time @@ -129,12 +129,12 @@ some of the new lines of this diff: + "Time (Seconds)", + "Packet Byte Count"); + - + // Specify the probe type, probe path (in configuration namespace), and + + // 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 (probeName, - + probeTrace, + + plotHelper.PlotProbe (probeType, + + tracePath, + "OutputBytes", + "Packet Byte Count", + GnuplotAggregator::KEY_BELOW); @@ -151,8 +151,8 @@ some of the new lines of this diff: + + // Specify the probe type, probe path (in configuration namespace), and + // probe output trace source ("OutputBytes") to write. - + fileHelper.WriteProbe (probeName, - + probeTrace, + + fileHelper.WriteProbe (probeType, + + tracePath, + "OutputBytes"); + Simulator::Stop (Seconds (20)); @@ -161,7 +161,7 @@ some of the new lines of this diff: The careful reader will have noticed, when testing the IPv6 command -line attribute, that ``seventh.cc`` had created a number of new output files: +line attribute above, that ``seventh.cc`` had created a number of new output files: :: @@ -257,26 +257,26 @@ variables for later use: :: - + std::string probeName; - + std::string probeTrace; - + probeName = "ns3::Ipv6PacketProbe"; - + probeTrace = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; + + std::string probeType; + + std::string tracePath; + + probeType = "ns3::Ipv6PacketProbe"; + + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; We use them here: :: - + // Specify the probe type, probe path (in configuration namespace), and + + // 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 (probeName, - + probeTrace, + + plotHelper.PlotProbe (probeType, + + tracePath, + "OutputBytes", + "Packet Byte Count", + GnuplotAggregator::KEY_BELOW); -The first two arguments are the name of the probe type and the probe trace. +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 this framework to plot other traces. The probe trace here is the ``Tx`` trace source of class ``Ipv6L3Protocol``. When we examine this class @@ -417,17 +417,17 @@ FORMATTED is specified) with a format string such as follows: + // Set the labels for this formatted output file. + fileHelper.Set2dFormat ("Time (Seconds) = %.3e\tPacket Byte Count = %.0f"); -Finally, the probe of interest must be hooked. Again, the probeName and -probeTrace variables in this example are used, and the probe's output +Finally, the trace source of interest must be hooked. Again, the probeType and +tracePath variables in this example are used, and the probe's output trace source "OutputBytes" is hooked: :: + - + // Specify the probe type, probe path (in configuration namespace), and + + // Specify the probe type, trace source path (in configuration namespace), and + // probe output trace source ("OutputBytes") to write. - + fileHelper.WriteProbe (probeName, - + probeTrace, + + fileHelper.WriteProbe (probeType, + + tracePath, + "OutputBytes"); + diff --git a/examples/tutorial/seventh.cc b/examples/tutorial/seventh.cc index d90b0ee72..7023b23c7 100644 --- a/examples/tutorial/seventh.cc +++ b/examples/tutorial/seventh.cc @@ -210,8 +210,8 @@ main (int argc, char *argv[]) uint16_t sinkPort = 8080; Address sinkAddress; Address anyAddress; - std::string probeName; - std::string probeTrace; + std::string probeType; + std::string tracePath; if (useV6 == false) { Ipv4AddressHelper address; @@ -219,8 +219,8 @@ main (int argc, char *argv[]) Ipv4InterfaceContainer interfaces = address.Assign (devices); sinkAddress = InetSocketAddress (interfaces.GetAddress (1), sinkPort); anyAddress = InetSocketAddress (Ipv4Address::GetAny (), sinkPort); - probeName = "ns3::Ipv4PacketProbe"; - probeTrace = "/NodeList/*/$ns3::Ipv4L3Protocol/Tx"; + probeType = "ns3::Ipv4PacketProbe"; + tracePath = "/NodeList/*/$ns3::Ipv4L3Protocol/Tx"; } else { @@ -229,8 +229,8 @@ main (int argc, char *argv[]) Ipv6InterfaceContainer interfaces = address.Assign (devices); sinkAddress = Inet6SocketAddress (interfaces.GetAddress (1,1), sinkPort); anyAddress = Inet6SocketAddress (Ipv6Address::GetAny (), sinkPort); - probeName = "ns3::Ipv6PacketProbe"; - probeTrace = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; + probeType = "ns3::Ipv6PacketProbe"; + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; } PacketSinkHelper packetSinkHelper ("ns3::TcpSocketFactory", anyAddress); @@ -265,12 +265,12 @@ main (int argc, char *argv[]) "Time (Seconds)", "Packet Byte Count"); - // Specify the probe type, probe path (in configuration namespace), and + // 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 (probeName, - probeTrace, + plotHelper.PlotProbe (probeType, + tracePath, "OutputBytes", "Packet Byte Count", GnuplotAggregator::KEY_BELOW); @@ -285,10 +285,10 @@ main (int argc, char *argv[]) // Set the labels for this formatted output file. fileHelper.Set2dFormat ("Time (Seconds) = %.3e\tPacket Byte Count = %.0f"); - // Specify the probe type, probe path (in configuration namespace), and + // Specify the probe type, trace source path (in configuration namespace), and // probe output trace source ("OutputBytes") to write. - fileHelper.WriteProbe (probeName, - probeTrace, + fileHelper.WriteProbe (probeType, + tracePath, "OutputBytes"); Simulator::Stop (Seconds (20)); diff --git a/src/stats/doc/data-collection-helpers.rst b/src/stats/doc/data-collection-helpers.rst index ab00dda6d..1514c5301 100644 --- a/src/stats/doc/data-collection-helpers.rst +++ b/src/stats/doc/data-collection-helpers.rst @@ -75,7 +75,7 @@ output type, where the output type defaults to PNG if unspecified): 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 second statement hooks the ``Probe`` of interest: 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 @@ A fully worked example (from ``seventh.cc``) is shown below: 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 @@ It has the following arguments: | 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 @@ It has the following arguments: 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 @@ 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: :: @@ -273,11 +296,8 @@ Gnuplot Helper Example ~~~~~~~~~~~~~~~~~~~~~~ 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 @@ The following 2-D gnuplot was created using the example. 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 @@ value as a trace source. Ptr emitter = CreateObject (); 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 probe = CreateObject (); - 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 @@ see if there were wildcards in the path. // 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 @@ It has the following arguments: | 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 @@ It has the following arguments: 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 @@ 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 -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 @@ Only the first 10 lines of this file are shown here for brevity. .. 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 @@ value as a trace source. Ptr emitter = CreateObject (); 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 probe = CreateObject (); - 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 @@ you would see if there were wildcards in the path. // 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 @@ to the GnuplotHelper and to the FileHelper: - 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 diff --git a/src/stats/examples/file-helper-example.cc b/src/stats/examples/file-helper-example.cc index 410fc9e79..4283111e1 100644 --- a/src/stats/examples/file-helper-example.cc +++ b/src/stats/examples/file-helper-example.cc @@ -34,10 +34,11 @@ using namespace ns3; NS_LOG_COMPONENT_DEFINE ("FileHelperExample"); -/* - * This is our test object, an object that increments counters at - * various times and emits one of them as a trace source. - */ +// +// This is our test object, an object that increments a counter according +// to a Poisson process, and exports the (integer-valued) count as a +// trace source. +// class Emitter : public Object { public: @@ -45,10 +46,9 @@ public: Emitter (); private: void DoInitialize (void); - void Emit (void); void Count (void); - TracedValue m_counter; // normally this would be integer type + TracedValue m_counter; Ptr m_var; }; @@ -80,18 +80,9 @@ void Emitter::DoInitialize (void) { NS_LOG_FUNCTION (this); - Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Emit, this); Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Count, this); } -void -Emitter::Emit (void) -{ - NS_LOG_FUNCTION (this); - NS_LOG_DEBUG ("Emitting at " << Simulator::Now ().GetSeconds ()); - Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Emit, this); -} - void Emitter::Count (void) { @@ -114,18 +105,6 @@ int main (int argc, char *argv[]) Ptr emitter = CreateObject (); Names::Add ("/Names/Emitter", emitter); - // - // This Probe will be hooked to the Emitter's trace source object by - // accessing it by path name in the Config database. - // - - Ptr probe = CreateObject (); - probe->SetName ("PathProbe"); - Names::Add ("/Names/Probe", probe); - - // Note, no return value is checked here. - probe->ConnectByPath ("/Names/Emitter/Counter"); - // // This file helper will be used to put data values into a file. // @@ -138,12 +117,12 @@ int main (int argc, char *argv[]) FileAggregator::FORMATTED); // Set the labels for this formatted output file. - fileHelper.Set2dFormat ("Time (Seconds) = %.3e\tCount = %.0f"); + fileHelper.Set2dFormat ("Time (Seconds) = %.3f\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", - "/Names/Probe/Output", + fileHelper.WriteProbe ("ns3::Uinteger32Probe", + "/Names/Emitter/Counter", "Output"); // The Emitter object is not associated with an ns-3 node, so diff --git a/src/stats/examples/gnuplot-helper-example.cc b/src/stats/examples/gnuplot-helper-example.cc index fe36bedb3..16294b580 100644 --- a/src/stats/examples/gnuplot-helper-example.cc +++ b/src/stats/examples/gnuplot-helper-example.cc @@ -34,10 +34,11 @@ using namespace ns3; NS_LOG_COMPONENT_DEFINE ("GnuplotHelperExample"); -/* - * This is our test object, an object that increments counters at - * various times and emits one of them as a trace source. - */ +// +// This is our test object, an object that increments a counter according +// to a Poisson process, and exports the (integer-valued) count as a +// trace source. +// class Emitter : public Object { public: @@ -45,12 +46,10 @@ public: Emitter (); private: void DoInitialize (void); - void Emit (void); void Count (void); - TracedValue m_counter; // normally this would be integer type + TracedValue m_counter; Ptr m_var; - }; NS_OBJECT_ENSURE_REGISTERED (Emitter); @@ -80,18 +79,9 @@ void Emitter::DoInitialize (void) { NS_LOG_FUNCTION (this); - Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Emit, this); Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Count, this); } -void -Emitter::Emit (void) -{ - NS_LOG_FUNCTION (this); - NS_LOG_DEBUG ("Emitting at " << Simulator::Now ().GetSeconds ()); - Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Emit, this); -} - void Emitter::Count (void) { @@ -114,18 +104,6 @@ int main (int argc, char *argv[]) Ptr emitter = CreateObject (); Names::Add ("/Names/Emitter", emitter); - // - // This Probe will be hooked to the Emitter's trace source object by - // accessing it by path name in the Config database. - // - - Ptr probe = CreateObject (); - probe->SetName ("PathProbe"); - Names::Add ("/Names/Probe", probe); - - // Note, no return value is checked here. - probe->ConnectByPath ("/Names/Emitter/Counter"); - // // This gnuplot helper will be used to produce output used to make // gnuplot plots. @@ -134,17 +112,19 @@ int main (int argc, char *argv[]) // Create the gnuplot helper. GnuplotHelper plotHelper; - // Configure the plot. + // Configure the plot. Arguments include file prefix, plot title, + // x-label, y-label, and output file type plotHelper.ConfigurePlot ("gnuplot-helper-example", - "Emitter Counts vs. Time", + "Emitter Count vs. Time", "Time (Seconds)", "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", - "/Names/Probe/Output", + // Create a probe. Because the trace source we are interested in is + // of type uint32_t, we specify the type of probe to use by the first + // argument specifying its ns3 TypeId. + plotHelper.PlotProbe ("ns3::Uinteger32Probe", + "/Names/Emitter/Counter", "Output", "Emitter Count", GnuplotAggregator::KEY_INSIDE); diff --git a/src/stats/helper/file-helper.h b/src/stats/helper/file-helper.h index 872c15bb4..936cbe1b5 100644 --- a/src/stats/helper/file-helper.h +++ b/src/stats/helper/file-helper.h @@ -75,7 +75,7 @@ public: /** * \param typeId the type ID for the probe used when it is created. - * \param path Config path to access the probe. + * \param path Config path for underlying trace source to be probed * \param probeTraceSource the probe trace source to access. * * Creates output files generated by hooking the ns-3 trace source @@ -84,6 +84,11 @@ public: * in m_outputFileNameWithoutExtension plus ".txt", and will consist * of the 'newValue' at each timestamp. * + * This method will create one or more probes according to the TypeId + * provided, connect the probe(s) to the trace source specified by + * the config path, and hook the probeTraceSource(s) to the downstream + * aggregator. + * * If the config path has more than one match in the system * (e.g. there is a wildcard), then one output file for each match * will be created. The output file names will contain the text in @@ -102,17 +107,6 @@ public: const std::string &path, const std::string &probeTraceSource); - /** - * \param typeId the type ID for the probe used when it is created. - * \param probeName the probe's name. - * \param path Config path to access the probe - * - * \brief Adds a probe to be used to write values to files. - */ - void AddProbe (const std::string &typeId, - const std::string &probeName, - const std::string &path); - /** * \param adaptorName the timeSeriesAdaptor's name. * @@ -252,6 +246,17 @@ public: void Set10dFormat (const std::string &format); private: + /** + * \param typeId the type ID for the probe used when it is created. + * \param probeName the probe's name. + * \param path Config path to access the probe + * + * \brief Adds a probe to be used to write values to files. + */ + void AddProbe (const std::string &typeId, + const std::string &probeName, + const std::string &path); + /** * \param typeId the type ID for the probe used when it is created. * \param matchIdentifier this string is used to make the probe's diff --git a/src/stats/helper/gnuplot-helper.cc b/src/stats/helper/gnuplot-helper.cc index 9ee82bcc5..b0ca4d295 100644 --- a/src/stats/helper/gnuplot-helper.cc +++ b/src/stats/helper/gnuplot-helper.cc @@ -113,8 +113,8 @@ GnuplotHelper::PlotProbe (const std::string &typeId, // Get a pointer to the aggregator. Ptr aggregator = GetAggregator (); - // Add a subtitle to the title to show the probe's path. - aggregator->SetTitle ( m_title + " \\n\\nProbe Path: " + path); + // Add a subtitle to the title to show the trace source's path. + aggregator->SetTitle ( m_title + " \\n\\nTrace Source Path: " + path); // Set the default dataset plotting style for the values. aggregator->Set2dDatasetDefaultStyle (Gnuplot2dDataset::LINES_POINTS); @@ -128,7 +128,8 @@ GnuplotHelper::PlotProbe (const std::string &typeId, // See if the path has any wildcards. bool pathHasNoWildcards = path.find ("*") == std::string::npos; - // Remove the last token from the path. + // Remove the last token from the path; this should correspond to the + // trace source attribute. size_t lastSlash = path.find_last_of ("/"); if (lastSlash == std::string::npos) { @@ -145,9 +146,11 @@ GnuplotHelper::PlotProbe (const std::string &typeId, } // See if there are any matches for the probe's path with the last - // token removed. + // token removed; this corresponds to the traced object itself. + NS_LOG_DEBUG ("Searching config database for trace source " << path); Config::MatchContainer matches = Config::LookupMatches (pathWithoutLastToken); uint32_t matchCount = matches.GetN (); + NS_LOG_DEBUG ("Found " << matchCount << " matches for trace source " << path); // This is used to make the probe's context be unique. std::string matchIdentifier; diff --git a/src/stats/helper/gnuplot-helper.h b/src/stats/helper/gnuplot-helper.h index b8fac01cf..e487238a5 100644 --- a/src/stats/helper/gnuplot-helper.h +++ b/src/stats/helper/gnuplot-helper.h @@ -95,7 +95,7 @@ public: /** * \param typeId the type ID for the probe used when it is created. - * \param path Config path to access the probe. + * \param path Config path for underlying trace source to be probed * \param probeTraceSource the probe trace source to access. * \param title the title to be associated to this dataset * \param keyLocation the location of the key in the plot. @@ -105,6 +105,11 @@ public: * will have the provided title, and will consist of the 'newValue' * at each timestamp. * + * This method will create one or more probes according to the TypeId + * provided, connect the probe(s) to the trace source specified by + * the config path, and hook the probeTraceSource(s) to the downstream + * aggregator. + * * If the config path has more than one match in the system * (e.g. there is a wildcard), then one dataset for each match will * be plotted. The dataset titles will be suffixed with the matched @@ -120,17 +125,6 @@ public: const std::string &title, enum GnuplotAggregator::KeyLocation keyLocation = GnuplotAggregator::KEY_INSIDE); - /** - * \param typeId the type ID for the probe used when it is created. - * \param probeName the probe's name. - * \param path Config path to access the probe. - * - * \brief Adds a probe to be used to make the plot. - */ - void AddProbe (const std::string &typeId, - const std::string &probeName, - const std::string &path); - /** * \param adaptorName the timeSeriesAdaptor's name. * @@ -155,6 +149,18 @@ public: Ptr GetAggregator (); private: + + /** + * \param typeId the type ID for the probe used when it is created. + * \param probeName the probe's name. + * \param path Config path to access the probe. + * + * \brief Adds a probe to be used to make the plot. + */ + void AddProbe (const std::string &typeId, + const std::string &probeName, + const std::string &path); + /** * \brief Constructs the aggregator. */ diff --git a/src/stats/model/double-probe.cc b/src/stats/model/double-probe.cc index 3102067ae..4d7ca59ec 100644 --- a/src/stats/model/double-probe.cc +++ b/src/stats/model/double-probe.cc @@ -85,7 +85,7 @@ bool DoubleProbe::ConnectByObject (std::string traceSource, Ptr obj) { NS_LOG_FUNCTION (this << traceSource << obj); - NS_LOG_DEBUG ("Name of probe (if any) in names database: " << Names::FindPath (obj)); + NS_LOG_DEBUG ("Name of trace source (if any) in names database: " << Names::FindPath (obj)); bool connected = obj->TraceConnectWithoutContext (traceSource, MakeCallback (&ns3::DoubleProbe::TraceSink, this)); return connected; } @@ -94,7 +94,7 @@ void DoubleProbe::ConnectByPath (std::string path) { NS_LOG_FUNCTION (this << path); - NS_LOG_DEBUG ("Name of probe to search for in config database: " << path); + NS_LOG_DEBUG ("Name of trace source to search for in config database: " << path); Config::ConnectWithoutContext (path, MakeCallback (&ns3::DoubleProbe::TraceSink, this)); }