Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(1209)

Unified Diff: src/stats/doc/data-collection-helpers.rst

Issue 318800043: Stats module enhancements
Patch Set: Created 7 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
Index: src/stats/doc/data-collection-helpers.rst
===================================================================
--- a/src/stats/doc/data-collection-helpers.rst
+++ b/src/stats/doc/data-collection-helpers.rst
@@ -38,10 +38,18 @@
new Probe types, as well as details about hooking together Probes,
Collectors, and Aggregators in custom arrangements.
-To date, two Data Collection helpers have been implemented:
+To date, four Data Collection helpers have been implemented:
- GnuplotHelper
- FileHelper
+- StatsAppDelayHelper
+- StatsAppThroughputHelper
+
+StatsAppDelayHelper and StatsAppThroughputHelper are responsible of
+locating source objects, create probes, collectors, and aggregators,
+and connect them together in a proper way to produce the statistics.
+They are inherited from base class StatsHelper, which encapsulates
+common functionality of these helpers.
GnuplotHelper
=============
@@ -593,12 +601,179 @@
fileHelper.WriteProbe ("ns3::Uinteger32Probe",
"/Names/Emitter/Counter",
"Output");
+
+StatsHelper classes
+===================
+
+Overview
+########
+
+StatsHelper is a base class for DCF-based statistics helper classes.
+Helper classes based on it are responsible of locating source objects,
+create probes, collectors, and aggregators, and connect them together
+in a proper way to produce the required statistics.
+
+The main inputs for the helpers are a
+name, an identifier type, an output type and nodes which are monitored.
+After all the necessary inputs have been set, the statistics
+can be started into action by invoking Install(). For example:
+
+::
+
+ NodeContainer nodes;
+ nodes.Create (2);
+
+ // ... (snip) ...
+
+ Ptr<StatsAppThroughputHelper> stat = CreateObject<StatsAppThroughputHelper> ();
+ stat->SetName ("name");
+ stat->SetIdentifierType (StatsHelper::IDENTIFIER_GLOBAL);
+ stat->SetOutputType (StatsHelper::OUTPUT_SCALAR_FILE);
+ stat->InstallNodes (nodes);
+ stat->Install ();
+
+ // ... (run simulation) ...
+
+ stat->Dispose (); // Disposing of helper creates output files
+
+
+This parent abstract class hosts several protected methods which are intended
+to simplify the development of child classes. These methods handle
+tasks related to DCF components.
+
+Output path and file naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To select the output directory for the statistics files, StatsHelper has an
+OutputPath attribute. By default, its value is ns-3-root-directory/output/.
+File names are based on helper name: if we create a helper
+
+::
+
+ Ptr<StatsAppThroughputHelper> stat = CreateObject<StatsAppThroughputHelper> ();
+ stat->SetName ("throughput_by_node_scatter");
+ stat->SetIdentifierType (StatsHelper::IDENTIFIER_NODE);
+ stat->SetOutputType (StatsHelper::OUTPUT_SCATTER_FILE);
+
+then the output files of this helper are named throughput_by_node_scatter.txt.
+Note that there may be other file extensions, or node ID suffixes in the file name
+based on output type.
+
+Identifier types
+~~~~~~~~~~~~~~~~
+
+By default, there are two identifier types available: IDENTIFIER_GLOBAL and
+IDENTIFIER_NODE. IDENTIFIER_GLOBAL causes statistics from all installed nodes
+to be combined under single global identifier ("0" as id). IDENTIFIER_NODE will
+separate statistics of all installed nodes under different IDs (node IDs).
+More identifiers may naturally be created, but this will require some other
+type of identifier ID creation in DoInstallProbes method of inherited helper
+classes.
+
+Output types
+~~~~~~~~~~~~
+
+There are several output types available:
+
+* OUTPUT_SCALAR_FILE
+* OUTPUT_SCATTER_FILE
+* OUTPUT_HISTOGRAM_FILE
+* OUTPUT_PDF_FILE
+* OUTPUT_CDF_FILE
+* OUTPUT_SCALAR_PLOT
+* OUTPUT_SCATTER_PLOT
+* OUTPUT_HISTOGRAM_PLOT
+* OUTPUT_PDF_PLOT
+* OUTPUT_CDF_PLOT
+
+Output types with FILE suffix produce a generic text file or PDf file
+based on collected statistics. Types with PLOT suffix generate Gnuplot
+data files and scripts for automatically generating PNG figures with Gnuplot.
+
+Scatter output types produce files, which have a list of time values and corresponding
+statistics values. Scalar output types calculate single average value for each identifier,
+e.g. in StatsAppThroughputHelper
+a scalar file would contain sum of transmitted application layer bytes divided by time
+per identifier.
+
+Note that depending on the inherited helper class, not all output types may
+be supported. In some cases, it is not even meaningful to enable all formats.
+
+
+StatsAppDelayHelper
+##################
+
+StatsAppDelayHelper produces application layer delay statistics from nodes
+installed to it. It is mainly an example of using the StatsHelper as a template
+for statistics collection.
+
+StatsAppDelayHelper collects delay information from installed nodes by adding
+TrafficTimeTags as byte tags to sent packets. It does this by hooking into
+Rx and Tx trace sources of applications installed into nodes.
+Once a packet with a tag is received
+by other application, the timestamp from the tag is removed and difference between
+send and receive times is registered as delay.
+
+Installing StatsAppDelayHelper is straightforward:
+
+::
+
+ Ptr<StatsAppDelayHelper> delayCdfByNode = CreateObject<StatsAppDelayHelper> ();
+ delayCdfByNode->SetName ("stat-app-delay-scatter-node");
+ delayCdfByNode->SetIdentifierType (StatsHelper::IDENTIFIER_NODE);
+ delayCdfByNode->SetOutputType (StatsHelper::OUTPUT_CDF_FILE);
+ delayCdfByNode->InstallNodes (nodes);
+ delayCdfByNode->Install ();
+
+ // Run the simulation
+
+ delayCdfByNode->Dispose ();
+
+This type of configuration causes helper to produce cumulative distribution function of the delay
+values placed in text files with node id suffixes.
+
+StatsAppThroughputHelper
+########################
+
+StatsAppThroughputHelper produces application layer throughput statistics from nodes
+installed to it. As StatsAppDelayHelper, it is mainly an example of using the StatsHelper
+as a template for statistics collection.
+
+StatsAppThroughputHelper collects throughput statistics by creating ApplicationPacketProbes and
+hooking them into Rx trace sources of any applications in target nodes.
+Once a packet is received by application, the size of the packet is saved for later use.
+The packet sizes and timing are use to calculate the data rate of received packets.
+
+Installing StatsAppThroughputHelper is straightforward:
+
+::
+
+ Ptr<StatsAppThroughputHelper> throughputScatterByNode = CreateObject<StatsAppThroughputHelper> ();
+ throughputScatterByNode->SetName ("stat-app-delay-scatter-node");
+ throughputScatterByNode->SetIdentifierType (StatsHelper::IDENTIFIER_NODE);
+ throughputScatterByNode->SetOutputType (StatsHelper::OUTPUT_SCATTER_FILE);
+ throughputScatterByNode->InstallNodes (nodes);
+ throughputScatterByNode->Install ();
+
+ // Run the simulation
+
+ throughputScatterByNode->Dispose ();
+
+This type of configuration causes helper to produce scatter values, i.e. tuples of time and throughput on
+preceding interval, listed in a separate text file for each node.
+
+Note that some of the StatsAppThroughputHelper configuration modes require averaging mode to be set on.
+This can be done by configuring
+
+::
+
+ throughputScatterByNode->SetAveragingMode (true);
Scope and Limitations
=====================
Currently, only these Probes have been implemented and connected
-to the GnuplotHelper and to the FileHelper:
+to the GnuplotHelper, FileHelper and StatsHelper classes:
- BooleanProbe
- DoubleProbe
@@ -607,6 +782,7 @@
- Uinteger32Probe
- TimeProbe
- PacketProbe
+- ApplicationDelayProbe
- ApplicationPacketProbe
- Ipv4PacketProbe

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b