diff --git a/src/flow-monitor/doc/flow-monitor.rst b/src/flow-monitor/doc/flow-monitor.rst index 6646aad87..6d62290cc 100644 --- a/src/flow-monitor/doc/flow-monitor.rst +++ b/src/flow-monitor/doc/flow-monitor.rst @@ -18,13 +18,13 @@ The source code for the new module lives in the directory ``src/flow-monitor``. The Flow Monitor module goal is to provide a flexible system to measure the performance of network protocols. The module uses probes, installed in network nodes, to track the packets exchanged by the nodes, and it will measure -a number of parameters. Packets are divided according to the flow they belong +a number of parameters. Packets are divided according to the flow they belong to, where each flow is defined according to the probe's characteristics (e.g., -for IP, a flow is defined as the packets with the same {protocol, source (IP, port), +for IP, a flow is defined as the packets with the same {protocol, source (IP, port), destination (IP, port)} tuple. The statistics are collected for each flow can be exported in XML format. Moreover, -the user can access the probes directly to request specific stats about each flow. +the user can access the probes directly to request specific stats about each flow. Design ====== @@ -54,7 +54,7 @@ basic packet's data, useful for the packet's classification. It must be underlined that only L4 (TCP, UDP) packets are, so far, classified. Moreover, only unicast packets will be classified. -These limitations may be removed in the future. +These limitations may be removed in the future. The data collected for each flow are: @@ -71,12 +71,11 @@ The data collected for each flow are: * delayHistogram, jitterHistogram, packetSizeHistogram: histogram versions for the delay, jitter, and packet sizes, respectively; * packetsDropped, bytesDropped: the number of lost packets and bytes, divided according to the loss reason code (defined in the probe). -It is worth pointing out that the probes measure the packet bytes including IP headers. +It is worth pointing out that the probes measure the packet bytes including IP headers. The L2 headers are not included in the measure. These stats will be written in XML form upon request (see the Usage section). - References ========== @@ -101,19 +100,29 @@ The typical use is:: the ``SerializeToXmlFile ()`` function 2nd and 3rd parameters are used respectively to activate/deactivate the histograms and the per-probe detailed stats. - Other possible alternatives can be found in the Doxygen documentation. +It is important to keep in mind that Flow Monitor records the packets statistics by +intercepting them at IP level. As a consequence, when the simulation ends, any +packet queued for transmission below the IP level will be considered as lost. + +It is strongly suggested to consider this point when using Flow Monitor. The user can choose to: + +* Ignore the lost packets (if their number is a statistically irrelevant quantity), or +* Stop the Applications before the actual Simulation End time, leaving enough time between the two for the queued packets to be processed. + +The second method is the suggested one. Usually a few seconds are enough (the +exact value depends on the network type). Helpers ======= The helper API follows the pattern usage of normal helpers. -Through the helper you can install the monitor in the nodes, set the monitor attributes, and +Through the helper you can install the monitor in the nodes, set the monitor attributes, and print the statistics. One important thing is: the :cpp:class:`ns3::FlowMonitorHelper` must be instantiated only -once in the main. +once in the main. Attributes ========== @@ -163,10 +172,10 @@ The main model output is an XML formatted report about flow statistics. An examp The output was generated by a TCP flow from 10.1.3.1 to 10.1.2.2. -It is worth noticing that the index 2 probe is reporting more packets and more bytes than the other probes. +It is worth noticing that the index 2 probe is reporting more packets and more bytes than the other probes. That's a perfectly normal behaviour, as packets are fragmented at IP level in that node. -It should also be observed that the receiving node's probe (index 4) doesn't count the fragments, as the +It should also be observed that the receiving node's probe (index 4) doesn't count the fragments, as the reassembly is done before the probing point. Examples