docs: Documenting new L2Tracer with a scenario and graph building example
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 47d4a65..98c8314 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -46,7 +46,6 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
-
.. _9-node-grid-example:
9-node grid example
@@ -289,3 +288,7 @@
:ref:`Custom applications`
+25-node tree topology with L2Tracer
+-----------------------------------
+
+:ref:`Example of packet drop tracer (L2Tracer)`
diff --git a/docs/source/metric.rst b/docs/source/metric.rst
index 4f1fa94..758bd3a 100644
--- a/docs/source/metric.rst
+++ b/docs/source/metric.rst
@@ -56,6 +56,28 @@
...
+- :ndnsim:`L2Tracer`
+
+ This tracer is similar in spirit to :ndnsim:`ndn::L3RateTracer`, but it currently traces only packet drop on layer 2 (e.g.,
+ due to transmission queue overflow).
+
+ The following example enables tracing on all simulation nodes:
+
+ .. code-block:: c++
+
+ // necessary includes
+ #include <ns3/ndnSIM/utils/tracers/l2-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<L2RateTracer> > >
+ l2tracers = L2RateTracer::InstallAll ("drop-trace.txt", Seconds (0.5));
+
+ Simulator::Run ();
+
+ ...
.. note::
@@ -136,6 +158,48 @@
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/>`_.
+.. _Example of packet drop tracer (L2Tracer):
+
+Example of packet drop tracer (L2Tracer)
+----------------------------------------
+
+This example (``ndn-tree-with-l2tracer.cc``) demonstrates basic usage of :ref:`trace classes`.
+
+In this scenario we will use a tree-like topology:
+
+.. image:: _static/topo-tree-25-node.png
+ :alt: 25-node tree topology
+
+The corresponding topology file (``topo-tree-25-node.txt``):
+
+.. literalinclude:: ../../examples/topologies/topo-tree-25-node.txt
+ :language: bash
+ :linenos:
+ :lines: 2-
+
+Example simulation (``ndn-tree-with-l2tracer.cc``) scenario that utilizes trace helpers:
+
+.. literalinclude:: ../../examples/ndn-tree-with-l2tracer.cc
+ :language: c++
+ :linenos:
+ :lines: 1-
+ :emphasize-lines: 7-8,19,135-139
+
+To run this scenario, use the following command::
+
+ ./waf --run=ndn-tree-with-l2tracer
+
+The successful run will create ``drop-trace.txt`` file 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:
+
+.. literalinclude:: ../../examples/graphs/drop-graph.R
+ :language: r
+ :linenos:
+
+.. image:: _static/l2-rate-tracer.png
+ :alt: Packet drop rates on routers
+
.. _cs trace helper:
Content store trace helper
diff --git a/examples/graphs/drop-graph.R b/examples/graphs/drop-graph.R
new file mode 100755
index 0000000..0f28f6e
--- /dev/null
+++ b/examples/graphs/drop-graph.R
@@ -0,0 +1,30 @@
+#!/usr/bin/env Rscript
+# Copyright (c) 2012-2013 Alexander Afanasyev <alexander.afanasyev@ucla.edu>
+
+
+# install.packages ('ggplot2')
+library (ggplot2)
+## # install.packages ('scales')
+## library (scales)
+
+#########################
+# Rate trace processing #
+#########################
+data = read.table ("drop-trace.txt", header=T)
+data$Node = factor (data$Node)
+data$Kilobits <- data$Kilobytes * 8
+data$Type = factor (data$Type)
+
+## data.rtr = data[grep("Rtr", data$Node),]
+
+# graph rates on all nodes in Kilobits
+g.all <- ggplot (data, aes (x=Time, y=Kilobits, color=Type)) +
+ geom_point (size=2) +
+ geom_line () +
+ ylab ("Packet drop rate [Kbits/s]") +
+ facet_wrap (~ Node) +
+ theme_bw ()
+
+png ("drop-trace-all-nodes.png", width=800, height=500)
+print (g.all)
+x = dev.off ()
diff --git a/examples/wscript b/examples/wscript
index b21629e..af34ee6 100644
--- a/examples/wscript
+++ b/examples/wscript
@@ -42,6 +42,9 @@
obj = bld.create_ns3_program('ndn-tree-app-delay-tracer', ['ndnSIM'])
obj.source = 'ndn-tree-app-delay-tracer.cc'
+ obj = bld.create_ns3_program('ndn-tree-with-l2tracer', ['ndnSIM'])
+ obj.source = 'ndn-tree-with-l2tracer.cc'
+
obj = bld.create_ns3_program('ndn-simple-pit-policies', ['ndnSIM'])
obj.source = 'ndn-simple-pit-policies.cc'