From 9d85e7f730e1249b2363986c1601c8b155da59b1 Mon Sep 17 00:00:00 2001 From: Alberto Gallegos Ramonet Date: Fri, 4 Apr 2025 14:22:27 +0900 Subject: [PATCH] flow-monitor: Reformat documentation and update content --- CHANGES.md | 1 + RELEASE_NOTES.md | 2 + doc/models/Makefile | 2 + .../doc/figures/flowmonitorArq.dia | Bin 0 -> 5186 bytes src/flow-monitor/doc/flow-monitor.rst | 115 ++++++++++-------- 5 files changed, 66 insertions(+), 54 deletions(-) create mode 100644 src/flow-monitor/doc/figures/flowmonitorArq.dia diff --git a/CHANGES.md b/CHANGES.md index 1518d0c13..dcca10743 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -23,6 +23,7 @@ This file is a best-effort approach to solving this issue; we will do our best b * (core) ``Object::GetInstanceTypeId()`` can no longer be specialized by subclasses and any such subclass API should be deleted (the base class will handle it). * (internet-apps) Added a parameter to the RADVD helper to announce a prefix without the autoconfiguration flag. +* (flow-monitor) Reformatted documentation and added a new concept figure. ### Changes to build system diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 21b544574..c51732d69 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -32,6 +32,8 @@ The required Doxygen version for documentation generation is now version 1.13. ### New user-visible features +- (flow-monitor) !2387 - Reformatted documentation and added a new concept figure. + ### Bugs fixed - (wifi) #2368 - Fix various issues related to Content Channels and RU allocation. Fixes mostly covers cases where OFDMA is used with central 26 tones, where a single user is being assigned the whole PPDU bandwidth or where a RU is larger than 20 MHz. diff --git a/doc/models/Makefile b/doc/models/Makefile index ce509d97a..fc23b2109 100644 --- a/doc/models/Makefile +++ b/doc/models/Makefile @@ -367,6 +367,7 @@ SOURCEFIGS = \ $(SRC)/lr-wpan/doc/802-15-4-ber.eps \ $(SRC)/lr-wpan/doc/802-15-4-per-sens.eps \ $(SRC)/lr-wpan/doc/802-15-4-psr-distance.eps \ + $(SRC)/flow-monitor/doc/figures/flowmonitorArq.dia \ $(SRC)/energy/doc/figures/dischargeCurve.png \ $(SRC)/energy/doc/figures/energyFramework.dia \ $(SRC)/energy/doc/figures/leadacid.png \ @@ -474,6 +475,7 @@ IMAGES_EPS = \ $(FIGURES)/802-15-4-per-sens.eps \ $(FIGURES)/802-15-4-psr-distance.eps \ $(FIGURES)/energyFramework.eps \ + $(FIGURES)/flowmonitorArq.eps \ $(FIGURES)/clear-channel.eps \ $(FIGURES)/assoc-manager.eps \ $(FIGURES)/emlsr-dl-txop.eps \ diff --git a/src/flow-monitor/doc/figures/flowmonitorArq.dia b/src/flow-monitor/doc/figures/flowmonitorArq.dia new file mode 100644 index 0000000000000000000000000000000000000000..3133366e537af0d6b9c9b0efa5a67a8941dabf4b GIT binary patch literal 5186 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 ZvTVR`7zE{#Dd@NfQ@apq&kh3M{0B>R3EKbw literal 0 HcmV?d00001 diff --git a/src/flow-monitor/doc/flow-monitor.rst b/src/flow-monitor/doc/flow-monitor.rst index f76882edc..f00bb1b33 100644 --- a/src/flow-monitor/doc/flow-monitor.rst +++ b/src/flow-monitor/doc/flow-monitor.rst @@ -1,19 +1,14 @@ Flow Monitor ------------- +============ .. include:: replace.txt .. highlight:: cpp .. heading hierarchy: - ------------- Chapter - ************* Section (#.#) - ============= Subsection (#.#.#) - ############# Paragraph (no number) + ============= Chapter + ------------- Section (#.#) + ~~~~~~~~~~~~~ Subsection (#.#.#) -Model Description -***************** - -The source code for the 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 @@ -26,8 +21,12 @@ 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. -Design -====== + +.. _fig-flowmonitorArq: + +.. figure:: figures/flowmonitorArq.* + + High-level Flow Monitor Architecture Flow Monitor module is designed in a modular way. It can be extended by subclassing ``ns3::FlowProbe`` and ``ns3::FlowClassifier``. @@ -42,10 +41,10 @@ guaranteed to be in every type of ``ns3::NetDevice``. As an example, ``CsmaNetDevice`` and ``PointToPointNetDevice`` have a ``TxQueue/Drop`` trace, while ``WiFiNetDevice`` does not. -The full module design is described in [FlowMonitor]_ +The source code for the module lives in the directory ``src/flow-monitor``. Scope and Limitations -===================== +--------------------- At the moment, probes and classifiers are available only for IPv4 and IPv6. @@ -89,8 +88,7 @@ These stats will be written in XML form upon request (see the Usage section). Due to the above design, FlowMonitor can not generate statistics when used with DSR routing protocol (because DSR forwards packets using broadcast addresses) -The "lost" packets problem -########################## +**The "lost" packets problem** At the end of a simulation, Flow Monitor could report about "lost" packets, i.e., packets that Flow Monitor have lost track of. @@ -111,15 +109,25 @@ It is important to stress that "lost" packets could be anywhere in the network, toward the received packets or the dropped ones. Ideally, their number should be zero or a minimal fraction of the other ones, i.e., they should be "statistically irrelevant". -References -========== - -.. [FlowMonitor] G. Carneiro, P. Fortuna, and M. Ricardo. 2009. FlowMonitor: a network monitoring framework for the network simulator 3 (NS-3). In Proceedings of the Fourth International ICST Conference on Performance Evaluation Methodologies and Tools (VALUETOOLS '09). http://dx.doi.org/10.4108/ICST.VALUETOOLS2009.7493 (Full text: https://dl.acm.org/doi/abs/10.4108/ICST.VALUETOOLS2009.7493) Usage -***** +----- The module usage is extremely simple. The helper will take care of about everything. +There are however, a few things that must be considered when using Flow Monitor: + + + +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 +print the statistics. + + +.. Important:: + When using the :cpp:class:`ns3::FlowMonitorHelper` must be instantiated only once in the ``main`` function. The typical use is:: @@ -139,32 +147,7 @@ activate/deactivate the histograms and the per-probe detailed stats. Other possible alternatives can be found in the Doxygen documentation, while ``cleanup_time`` is the time needed by in-flight packets to reach their destinations. -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 -print the statistics. - -One important thing is: the :cpp:class:`ns3::FlowMonitorHelper` must be instantiated only -once in the main. - -Attributes -========== - -The module provides the following attributes in :cpp:class:`ns3::FlowMonitor`: - -* MaxPerHopDelay (Time, default 10s): The maximum per-hop delay that should be considered; -* StartTime (Time, default 0s): The time when the monitoring starts; -* DelayBinWidth (double, default 0.001): The width used in the delay histogram; -* JitterBinWidth (double, default 0.001): The width used in the jitter histogram; -* PacketSizeBinWidth (double, default 20.0): The width used in the packetSize histogram; -* FlowInterruptionsBinWidth (double, default 0.25): The width used in the flowInterruptions histogram; -* FlowInterruptionsMinTime (double, default 0.5): The minimum inter-arrival time that is considered a flow interruption. - - -Output -====== +**XML file output** The main model output is an XML formatted report about flow statistics. An example is:: @@ -203,8 +186,30 @@ That's a perfectly normal behaviour, as packets are fragmented at IP level in th 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 -======== + +Attributes +~~~~~~~~~~ + +The module provides the following attributes in :cpp:class:`ns3::FlowMonitor`: + +* ``MaxPerHopDelay`` (Time, default 10s): The maximum per-hop delay that should be considered; +* ``StartTime`` (Time, default 0s): The time when the monitoring starts; +* ``DelayBinWidth`` (double, default 0.001): The width used in the delay histogram; +* ``JitterBinWidth`` (double, default 0.001): The width used in the jitter histogram; +* ``PacketSizeBinWidth`` (double, default 20.0): The width used in the packetSize histogram; +* ``FlowInterruptionsBinWidth`` (double, default 0.25): The width used in the flowInterruptions histogram; +* ``FlowInterruptionsMinTime`` (double, default 0.5): The minimum inter-arrival time that is considered a flow interruption. + + +Traces +~~~~~~ + +No traces are provided by this module as it is the module itself which provides a simple monitoring functionality to +other networks. + + +Examples and Tests +------------------ The examples are located in `src/flow-monitor/examples`. @@ -217,16 +222,18 @@ Moreover, the following examples use the flow-monitor module: * examples/wireless/wifi-multirate.cc * examples/wireless/wifi-hidden-terminal.cc +Tests are provided to ensure the histogram correct functionality. -Troubleshooting -=============== - -Do not define more than one :cpp:class:`ns3::FlowMonitorHelper` in the simulation. Validation -********** +---------- The paper in the references contains a full description of the module validation against a test network. -Tests are provided to ensure the Histogram correct functionality. + +References +---------- + +[`1 `_] G. Carneiro, P. Fortuna, and M. Ricardo. 2009. FlowMonitor: a network monitoring framework for the network simulator 3 (NS-3). In Proceedings of the Fourth International ICST Conference on Performance Evaluation Methodologies and Tools (VALUETOOLS '09). http://dx.doi.org/10.4108/ICST.VALUETOOLS2009.7493. +