tracers+docs: Correcting compilation and installation of trace helpers
Also in this commit an example on how to use trace helpers, including
how to build graphs using R.
diff --git a/docs/source/_static/root-5sec-counts.png b/docs/source/_static/root-5sec-counts.png
new file mode 100644
index 0000000..5257f1d
--- /dev/null
+++ b/docs/source/_static/root-5sec-counts.png
Binary files differ
diff --git a/docs/source/_static/root-rates.png b/docs/source/_static/root-rates.png
new file mode 100644
index 0000000..bc0df92
--- /dev/null
+++ b/docs/source/_static/root-rates.png
Binary files differ
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index ddb4b26..ff36020 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -255,3 +255,77 @@
You can also run using visualizer module to verify that both bottleneck links are utilized::
./waf --run=ndn-congestion-alt-topo-plugin --visualize
+
+.. _trace example:
+
+Example of using trace helpers
+------------------------------
+
+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/>`_.
diff --git a/docs/source/metric.rst b/docs/source/metric.rst
index cce98d9..aeff236 100644
--- a/docs/source/metric.rst
+++ b/docs/source/metric.rst
@@ -4,6 +4,7 @@
To obtain simulation results, you would need to connect to one or more `trace sources <doxygen/group___trace_source_list.html>`_ provided by ndnSIM classes.
+.. _trace classes:
Tracer classes
--------------
@@ -20,12 +21,19 @@
.. code-block:: c++
+ // necessary includes
+ #include <ns3/ndnSIM/utils/tracers/ndn-l3-aggregate-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<L3AggregateTracer> > >
- tracers = L3RateTracer::InstallAll ("aggregate-trace.txt", Seconds (1.0));
+ boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::L3AggregateTracer> > >
+ aggTracers = ndn::L3AggregateTracer::InstallAll ("aggregate-trace.txt", Seconds (1.0));
Simulator::Run ();
+
+ ...
- :ndnsim:`ndn::L3RateTracer`
@@ -36,12 +44,19 @@
.. code-block:: c++
+ // necessary includes
+ #include <ns3/ndnSIM/utils/tracers/ndn-l3-rate-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<L3RateTracer> > >
- tracers = L3RateTracer::InstallAll ("rate-trace.txt", Seconds (1.0));
+ boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::L3RateTracer> > >
+ rateTracers = ndn::L3RateTracer::InstallAll ("rate-trace.txt", Seconds (1.0));
Simulator::Run ();
+
+ ...
.. note::
@@ -50,3 +65,7 @@
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.
+Example
++++++++
+
+Please refer to the :ref:`this example <trace example>`.
