docs: Documentation update
Change-Id: I6f916eb822a59e980e8fb1134886c3431755119c
diff --git a/docs/source/metric.rst b/docs/source/metric.rst
index a5b2667..2476d43 100644
--- a/docs/source/metric.rst
+++ b/docs/source/metric.rst
@@ -11,55 +11,6 @@
Packet-level trace helpers
--------------------------
-- :ndnsim:`ndn::L3AggregateTracer`
-
- Tracing the aggregate number of Interests/Data packets forwarded by an NDN node
-
- The following example enables tracing on all simulation nodes:
-
- .. code-block:: c++
-
- // the following should be put just before calling Simulator::Run in the scenario
-
- ndn::L3AggregateTracer::InstallAll ("aggregate-trace.txt", Seconds (1.0));
-
- Simulator::Run ();
-
- ...
-
-
- Output file format is tab-separated values, with first row specifying names of the columns. Refer to the following table for the description of the columns:
-
- +------------------+---------------------------------------------------------------------+
- | Column | Description |
- +==================+=====================================================================+
- | ``Time`` | simulation time |
- +------------------+---------------------------------------------------------------------+
- | ``Node`` | node id, globally unique |
- +------------------+---------------------------------------------------------------------+
- | ``FaceId`` | interface ID (-1 for combined metric) |
- +------------------+---------------------------------------------------------------------+
- | ``Type`` | Type of measurements: |
- | | |
- | | - ``InInterests`` measurements of incoming Interests |
- | | - ``OutInterests`` measurements of outgoing Interests |
- | | - ``DropInterests`` measurements of dropped Interests |
- | | - ``InData`` measurements of incoming Data |
- | | - ``OutData`` measurements of outgoing Data |
- | | - ``DropData`` measurements of dropped Data |
- | | - ``InNacks`` measurements of incoming NACKs |
- | | - ``OutNacks`` measurements of outgoing NACKs |
- | | - ``DropNacks`` measurements of dropped NACKs |
- | | - ``SatisfiedInterests`` measurements of satisfied Interests |
- | | - ``TimedOutInterests`` measurements of timed out Interests |
- +------------------+---------------------------------------------------------------------+
- | ``Packets`` | absolute number of packets within last averaging period |
- | | (number of packets). |
- +------------------+---------------------------------------------------------------------+
- | ``Kilobytes`` | absolute number of kilobytes transferred within the last averaging |
- | | period (number of packets). |
- +------------------+---------------------------------------------------------------------+
-
- :ndnsim:`ndn::L3RateTracer`
Tracing the rate in bytes and in number of packets of Interest/Data packets forwarded by an NDN node
@@ -70,9 +21,9 @@
// the following should be put just before calling Simulator::Run in the scenario
- ndn::L3RateTracer::InstallAll ("rate-trace.txt", Seconds (1.0));
+ L3RateTracer::InstallAll("rate-trace.txt", Seconds(1.0));
- Simulator::Run ();
+ Simulator::Run();
...
@@ -91,21 +42,20 @@
| | |
| | - ``InInterests`` measurements of incoming Interests |
| | - ``OutInterests`` measurements of outgoing Interests |
- | | - ``DropInterests`` measurements of dropped Interests |
| | - ``InData`` measurements of incoming Data |
| | - ``OutData`` measurements of outgoing Data |
- | | - ``DropData`` measurements of dropped Data |
- | | - ``InNacks`` measurements of incoming NACKs |
- | | - ``OutNacks`` measurements of outgoing NACKs |
- | | - ``DropNacks`` measurements of dropped NACKs |
+ | | - ``SatisfiedInterests`` measurements of satisfied Interests |
+ | | (totals for all faces) |
+ | | - ``TimedOutInterests`` measurements of timed out Interests |
+ | | (totals for all faces) |
| | - ``InSatisfiedInterests`` measurements of incoming satisfied |
- | | Interests |
+ | | Interests (per incoming face) |
| | - ``InTimedOutInterests`` measurements of incoming timed out |
- | | Interests |
+ | | Interests (per incoming face) |
| | - ``OutSatisfiedInterests`` measurements of outgoing satisfied |
- | | Interests |
+ | | Interests (per outgoing face) |
| | - ``OutTimedOutInterests`` measurements of outgoing satisfied |
- | | Interests |
+ | | Interests (per outgoing face) |
+------------------+---------------------------------------------------------------------+
| ``Packets`` | estimated rate (EWMA average) of packets within the last averaging |
| | period (number of packets/s). |
@@ -131,9 +81,9 @@
// the following should be put just before calling Simulator::Run in the scenario
- L2RateTracer::InstallAll ("drop-trace.txt", Seconds (0.5));
+ L2RateTracer::InstallAll("drop-trace.txt", Seconds(0.5));
- Simulator::Run ();
+ Simulator::Run();
...
@@ -175,7 +125,7 @@
Example of packet-level trace helpers
+++++++++++++++++++++++++++++++++++++
-This example (``ndn-tree-tracers.cc``) demonstrates basic usage of :ref:`trace classes`.
+This example (``ndn-tree-tracers.cpp``) demonstrates basic usage of :ref:`trace classes`.
In this scenario we will use a tree-like topology, where consumers are installed on leaf nodes and producer is in the root of the tree:
@@ -215,33 +165,34 @@
:linenos:
:lines: 1-2,27-
-Example simulation (``ndn-tree-tracers.cc``) scenario that utilizes trace helpers:
+Example simulation (``ndn-tree-tracers.cpp``) scenario that utilizes trace helpers:
-.. literalinclude:: ../../examples/ndn-tree-tracers.cc
+.. literalinclude:: ../../examples/ndn-tree-tracers.cpp
:language: c++
:linenos:
- :lines: 21-28,61-
- :emphasize-lines: 57-58
+ :lines: 20-27,60-
+ :emphasize-lines: 58
To run this scenario, use the following command::
./waf --run=ndn-tree-tracers
-The successful run will create ``rate-trace.txt`` and ``aggregate-trace.txt`` files in the current directly, which can be analyzed manually or used as input to some graph/stats packages.
+The successful run will create ``rate-trace.txt`` files in the current directly, which can be analyzed manually or used as input to some graph/stats packages.
.. sidebar:: Graph build using the `R script <http://www.r-project.org/>`_
.. image:: _static/root-rates.png
:alt: Interest/Data packet rates at the root node
- .. image:: _static/root-5sec-counts.png
- :alt: Interest/Data packet counts at the root node in 5-second intervals
-
.. literalinclude:: ../../examples/graphs/rate-graph.R
:language: r
:linenos:
-For more information about R and ggplot2, please refer to `R language manual <http://cran.r-project.org/manuals.html>`_, `ggplot2 module manual <http://docs.ggplot2.org/current/>`_.
+For more information about R and ggplot2, please refer to `R language manual <http://cran.r-project.org/manuals.html>`_ and `ggplot2 module manual <http://docs.ggplot2.org/current/>`_.
+
+ ::
+
+ Rscript src/ndnSIM/examples/graphs/rate-graph.R
.. _Example of packet drop tracer (L2Tracer):
@@ -254,7 +205,7 @@
:alt: 25-node tree topology
:width: 550px
-This example (``ndn-tree-with-l2tracer.cc``) demonstrates basic usage of :ref:`trace classes`.
+This example (``ndn-tree-with-l2tracer.cpp``) demonstrates basic usage of :ref:`trace classes`.
The corresponding topology file (``topo-tree-25-node.txt``):
@@ -263,13 +214,13 @@
:linenos:
:lines: 2-
-Example simulation (``ndn-tree-with-l2tracer.cc``) scenario that utilizes trace helpers:
+Example simulation (``ndn-tree-with-l2tracer.cpp``) scenario that utilizes trace helpers:
-.. literalinclude:: ../../examples/ndn-tree-with-l2tracer.cc
+.. literalinclude:: ../../examples/ndn-tree-with-l2tracer.cpp
:language: c++
:linenos:
- :lines: 1-
- :emphasize-lines: 16,135
+ :lines: 20-
+ :emphasize-lines: 16,134
To run this scenario, use the following command::
@@ -283,6 +234,10 @@
:language: r
:linenos:
+Run R script::
+
+ Rscript src/ndnSIM/examples/graphs/drop-graph.R
+
.. image:: _static/l2-rate-tracer.png
:alt: Packet drop rates on routers
@@ -291,6 +246,8 @@
Content store trace helper
--------------------------
+NOTE: This tracer works ONLY when the content store structure of ndnSIM is used!
+
- :ndnsim:`ndn::CsTracer`
With the use of :ndnsim:`ndn::CsTracer` it is possible to obtain statistics of cache hits/cache misses on simulation nodes.
@@ -301,9 +258,9 @@
// the following should be put just before calling Simulator::Run in the scenario
- ndn::CsTracer::InstallAll ("cs-trace.txt", Seconds (1));
+ CsTracer::InstallAll("cs-trace.txt", Seconds(1));
- Simulator::Run ();
+ Simulator::Run();
...
@@ -317,18 +274,18 @@
Example of content store trace helper
+++++++++++++++++++++++++++++++++++++
-This example (``ndn-tree-cs-tracers.cc``) demonstrates basic usage of content store tracer.
+This example (``ndn-tree-cs-tracers.cpp``) demonstrates basic usage of content store tracer.
In this scenario we will use the same tree-like topology as in :ref:`previous example <packet trace helper example>`, where consumers are installed on leaf nodes and producer is in the root of the tree.
The main difference is that each client request data from the same namespace: /root/1, /root/2, ... Another small difference is that in this scenario we start our application not at the same time, but 10 ms apart.
-Example simulation (``ndn-tree-cs-tracers.cc``) scenario that utilizes trace helpers:
+Example simulation (``ndn-tree-cs-tracers.cpp``) scenario that utilizes trace helpers:
-.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cc
+.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cpp
:language: c++
:linenos:
- :lines: 21-28,61-
- :emphasize-lines: 59
+ :lines: 20-27,60-
+ :emphasize-lines: 61
To run this scenario, use the following command::
@@ -351,9 +308,9 @@
// the following should be put just before calling Simulator::Run in the scenario
- ndn::AppDelayTracer::InstallAll ("app-delays-trace.txt");
+ AppDelayTracer::InstallAll("app-delays-trace.txt");
- Simulator::Run ();
+ Simulator::Run();
...
@@ -384,14 +341,8 @@
+-----------------+---------------------------------------------------------------------+
| ``RetxCount`` | number of Interest retransmissions (for LastDelay always equal to 1)|
+-----------------+---------------------------------------------------------------------+
- | ``HopCount`` | combined number of number of hops for Interest and Data packet. |
- | | Note that HopCount is increased anytime somebody calls Send method |
- | | on a face, including delivery of Interest/Data to application via |
- | | an AppFace (but not from application to ndn::L3Protocol!). |
- | | |
- | | One consequence is that Interests satisfied by an app will have |
- | | even hop count (min hop count = 2), and Interests satisfied from |
- | | caches will have odd hop count (min hop count = 1) |
+ | ``HopCount`` | the number of hops that the retrieved Data packet traveled on the |
+ | | way back from producer application or cache. |
+-----------------+---------------------------------------------------------------------+
.. _app delay trace helper example:
@@ -399,42 +350,22 @@
Example of application-level trace helper
+++++++++++++++++++++++++++++++++++++++++
-This example (``ndn-tree-app-delay-tracer.cc``) demonstrates basic usage of application-level Interest-Data delay tracer.
+This example (``ndn-tree-app-delay-tracer.cpp``) demonstrates basic usage of application-level Interest-Data delay tracer.
In this scenario we will use the same tree-like topology as in :ref:`packet trace helper example <packet trace helper example>`, where consumers are installed on leaf nodes and producer is in the root of the tree and clients request data from the same namespace: /root/1, /root/2, ...
-Example simulation (``ndn-tree-app-delay-tracer.cc``) scenario that utilizes trace helpers:
+Example simulation (``ndn-tree-app-delay-tracer.cpp``) scenario that utilizes trace helpers:
-.. literalinclude:: ../../examples/ndn-tree-app-delay-tracer.cc
+.. literalinclude:: ../../examples/ndn-tree-app-delay-tracer.cpp
:language: c++
:linenos:
- :lines: 21-28,61-
- :emphasize-lines: 59
-
+ :lines: 20-27,60-
+ :emphasize-lines: 60
To run this scenario, use the following command::
./waf --run=ndn-tree-app-delay-tracer
-The successful run will create ``app-delays-trace.txt``, which similarly to trace file from the :ref:`packet trace helper example <packet trace helper example>` can be analyzed manually or used as input to some graph/stats packages.
-
-
-Other types of stats
---------------------
-
-.. _periodic tracing of Pending Interest Table (PIT) size:
-
-Periodic tracing of Pending Interest Table (PIT) size
-+++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-This example (``ndn-simple-with-pit-count-stats.cc``) shows how you can periodically print out current size of PIT on the selected nodes.
-
-.. literalinclude:: ../../examples/ndn-simple-with-pit-count-stats.cc
- :language: c++
- :linenos:
- :lines: 20-26,47-
- :emphasize-lines: 9-20,43-46,59-61
-
-To run this scenario, use the following command::
-
- ./waf --run=ndn-simple-with-pit-count-stats
+The successful run will create ``app-delays-trace.txt``, which similarly to trace file from the
+:ref:`packet trace helper example <packet trace helper example>` can be analyzed manually or used as
+input to some graph/stats packages.