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 |