app+utils+doc: Adding application-level trace helper to record Interest-Data delays
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index d99c245..f0485c3 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -256,106 +256,17 @@
./waf --run=ndn-congestion-alt-topo-plugin --visualize
-.. _trace example:
-
3-level binary tree with packet-level trace helpers
---------------------------------------------------
-This example (``ndn-tree-tracers.cc``) demonstrates basic usage of :ref:`trace classes`.
+:ref:`packet trace helper example`
-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:
-
-.. aafig::
- :aspect: 60
- :scale: 120
-
- /--------\ /--------\ /--------\ /--------\
- |"leaf-1"| |"leaf-2"| |"leaf-3"| |"leaf-4"|
- \--------/ \--------/ \--------/ \--------/
- ^ ^ ^ ^
- | | | |
- \ / \ /
- \ / \ / 10Mbps / 1ms
- \ / \ /
- | | | |
- v v v v
- /-------\ /-------\
- |"rtr-1"| |"rtr-2"|
- \-------/ \-------/
- ^ ^
- | |
- \ / 10 Mpbs / 1ms
- +--------\ /--------+
- | |
- v v
- /--------\
- | "root" |
- \--------/
-
-The corresponding topology file (``topo-tree.txt``):
-
-.. literalinclude:: ../../examples/topologies/topo-tree.txt
- :language: bash
- :linenos:
- :lines: 1-2,27-
-
-Example simulation (``ndn-tree-tracers.cc``) scenario that utilizes trace helpers:
-
-.. literalinclude:: ../../examples/ndn-tree-tracers.cc
- :language: c++
- :linenos:
- :lines: 21-34,67-
- :emphasize-lines: 7-11,63-67
-
-
-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.
-
-For example, the following `R script <http://www.r-project.org/>`_ will build a number of nice graphs:
-
-.. image:: _static/root-rates.png
- :alt: Interest/Data packet rates at the root node
- :align: right
-
-.. image:: _static/root-5sec-counts.png
- :alt: Interest/Data packet counts at the root node in 5-second intervals
- :align: right
-
-.. 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/>`_.
-
-
-
-.. _cs trace helper example:
3-level binary tree with content store trace helper
---------------------------------------------------
-This example (``ndn-tree-cs-tracers.cc``) demonstrates basic usage of :ref:`content store tracer helper class<cs trace helper>`.
+:ref:`cs trace helper example`
-In this scenario we will use the same tree-like topology as in :ref:`previous example <trace 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:
-
-.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cc
- :language: c++
- :linenos:
- :lines: 21-31,64-
- :emphasize-lines: 7-11,25,46,48,65-66
-
-
-To run this scenario, use the following command::
-
- ./waf --run=ndn-tree-cs-tracers
-
-The successful run will create ``cs-trace.txt``, which similarly to trace file from the :ref:`previous example <trace example>` can be analyzed manually or used as input to some graph/stats packages.
3-node topology with Content Store respecting freshness field of ContentObjects
-------------------------------------------------------------------------------
diff --git a/docs/source/metric.rst b/docs/source/metric.rst
index d1d81ce..c1cec1c 100644
--- a/docs/source/metric.rst
+++ b/docs/source/metric.rst
@@ -62,11 +62,79 @@
A number of other tracers are available in ``plugins/tracers-broken`` folder, but they do not yet work with the current code.
Eventually, we will port most of them to the current code, but it is not our main priority at the moment and would really appreciate help with writing new tracers and porting the old ones.
+.. _packet trace helper example:
-Example
-+++++++
+Example of packet-level trace helpers
++++++++++++++++++++++++++++++++++++++
-Please refer to the :ref:`this example <trace example>`.
+This example (``ndn-tree-tracers.cc``) 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:
+
+.. aafig::
+ :aspect: 60
+ :scale: 120
+
+ /--------\ /--------\ /--------\ /--------\
+ |"leaf-1"| |"leaf-2"| |"leaf-3"| |"leaf-4"|
+ \--------/ \--------/ \--------/ \--------/
+ ^ ^ ^ ^
+ | | | |
+ \ / \ /
+ \ / \ / 10Mbps / 1ms
+ \ / \ /
+ | | | |
+ v v v v
+ /-------\ /-------\
+ |"rtr-1"| |"rtr-2"|
+ \-------/ \-------/
+ ^ ^
+ | |
+ \ / 10 Mpbs / 1ms
+ +--------\ /--------+
+ | |
+ v v
+ /--------\
+ | "root" |
+ \--------/
+
+The corresponding topology file (``topo-tree.txt``):
+
+.. literalinclude:: ../../examples/topologies/topo-tree.txt
+ :language: bash
+ :linenos:
+ :lines: 1-2,27-
+
+Example simulation (``ndn-tree-tracers.cc``) scenario that utilizes trace helpers:
+
+.. literalinclude:: ../../examples/ndn-tree-tracers.cc
+ :language: c++
+ :linenos:
+ :lines: 21-34,67-
+ :emphasize-lines: 7-11,63-67
+
+
+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.
+
+For example, the following `R script <http://www.r-project.org/>`_ will build a number of nice graphs:
+
+.. image:: _static/root-rates.png
+ :alt: Interest/Data packet rates at the root node
+ :align: right
+
+.. image:: _static/root-5sec-counts.png
+ :alt: Interest/Data packet counts at the root node in 5-second intervals
+ :align: right
+
+.. 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/>`_.
.. _cs trace helper:
@@ -103,10 +171,79 @@
.. Evaluate lifetime of the content store entries can be accomplished using modified version of the content stores.
.. In particular,
+.. _cs trace helper example:
+
+Example of content store trace helper
++++++++++++++++++++++++++++++++++++++
+
+This example (``ndn-tree-cs-tracers.cc``) 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:
+
+.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cc
+ :language: c++
+ :linenos:
+ :lines: 21-31,64-
+ :emphasize-lines: 7-11,25,43,45,62-63
-Example
-+++++++
+To run this scenario, use the following command::
-:ref:`This example <cs trace helper example>` demonstrates one usage of content store tracer.
+ ./waf --run=ndn-tree-cs-tracers
+
+The successful run will create ``cs-trace.txt``, which similarly to trace file from the :ref:`tracing example <packet trace helper example>` can be analyzed manually or used as input to some graph/stats packages.
+
+
+Application-level trace helper
+------------------------------
+
+- :ndnsim:`ndn::AppDelayTracer`
+
+ With the use of :ndnsim:`ndn::AppDelayTracer` it is possible to obtain data about for delays between issuing Interest and receiving corresponding Data packet.
+
+ The following code enables application-level Interest-Data delay tracing:
+
+ .. code-block:: c++
+
+ // necessary includes
+ #include <ns3/ndnSIM/utils/tracers/ndn-app-delay-tracer.h>
+
+ ...
+
+ // the following should be put just before calling Simulator::Run in the scenario
+
+ boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::AppDelayTracer> > >
+ tracers = ndn::AppDelayTracer::InstallAll ("app-delays-trace.txt");
+
+ Simulator::Run ();
+
+ ...
+
+.. _app delay trace helper example:
+
+Example of application-level trace helper
++++++++++++++++++++++++++++++++++++++++++
+
+This example (``ndn-tree-app-delay-tracer.cc``) 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:
+
+.. literalinclude:: ../../examples/ndn-tree-app-delay-tracer.cc
+ :language: c++
+ :linenos:
+ :lines: 21-31,64-
+ :emphasize-lines: 7-8,61-62
+
+
+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.
+