blob: 03ee82f8b7044b77c6386be6e246835f8fc69947 [file] [log] [blame]
Alexander Afanasyevb1314b12012-11-21 18:23:42 -08001
2Obtaining metrics
3=================
4
5To obtain simulation results, you would need to connect to one or more `trace sources <doxygen/group___trace_source_list.html>`_ provided by ndnSIM classes.
6
Alexander Afanasyevf4a03592012-12-10 16:12:34 -08007It is also possible to use existing trace helpers, which collects and aggregates requested statistical information in text files.
8
Alexander Afanasyev59314802012-11-26 14:56:04 -08009.. _trace classes:
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080010
Alexander Afanasyevf4a03592012-12-10 16:12:34 -080011Packet-level trace helpers
12--------------------------
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080013
14- :ndnsim:`ndn::L3AggregateTracer`
15
16 Tracing the aggregate number of Interests/Data packets forwarded by an NDN node
17
18 The following example enables tracing on all simulation nodes:
19
20 .. code-block:: c++
21
Alexander Afanasyev59314802012-11-26 14:56:04 -080022 // necessary includes
23 #include <ns3/ndnSIM/utils/tracers/ndn-l3-aggregate-tracer.h>
24
25 ...
26
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080027 // the following should be put just before calling Simulator::Run in the scenario
28
Alexander Afanasyev59314802012-11-26 14:56:04 -080029 boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::L3AggregateTracer> > >
30 aggTracers = ndn::L3AggregateTracer::InstallAll ("aggregate-trace.txt", Seconds (1.0));
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080031
32 Simulator::Run ();
Alexander Afanasyev59314802012-11-26 14:56:04 -080033
34 ...
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080035
36
37- :ndnsim:`ndn::L3RateTracer`
38
39 Tracing the rate in bytes and in number of packets of Interest/Data packets forwarded by an NDN node
40
41 The following example enables tracing on all simulation nodes:
42
43 .. code-block:: c++
44
Alexander Afanasyev59314802012-11-26 14:56:04 -080045 // necessary includes
46 #include <ns3/ndnSIM/utils/tracers/ndn-l3-rate-tracer.h>
47
48 ...
49
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080050 // the following should be put just before calling Simulator::Run in the scenario
51
Alexander Afanasyev59314802012-11-26 14:56:04 -080052 boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::L3RateTracer> > >
53 rateTracers = ndn::L3RateTracer::InstallAll ("rate-trace.txt", Seconds (1.0));
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080054
55 Simulator::Run ();
Alexander Afanasyev59314802012-11-26 14:56:04 -080056
57 ...
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080058
59
60.. note::
61
62 A number of other tracers are available in ``plugins/tracers-broken`` folder, but they do not yet work with the current code.
63 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.
64
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -080065.. _packet trace helper example:
Alexander Afanasyevb1314b12012-11-21 18:23:42 -080066
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -080067Example of packet-level trace helpers
68+++++++++++++++++++++++++++++++++++++
Alexander Afanasyev59314802012-11-26 14:56:04 -080069
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -080070This example (``ndn-tree-tracers.cc``) demonstrates basic usage of :ref:`trace classes`.
71
72In 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:
73
74.. aafig::
75 :aspect: 60
76 :scale: 120
77
78 /--------\ /--------\ /--------\ /--------\
79 |"leaf-1"| |"leaf-2"| |"leaf-3"| |"leaf-4"|
80 \--------/ \--------/ \--------/ \--------/
81 ^ ^ ^ ^
82 | | | |
83 \ / \ /
84 \ / \ / 10Mbps / 1ms
85 \ / \ /
86 | | | |
87 v v v v
88 /-------\ /-------\
89 |"rtr-1"| |"rtr-2"|
90 \-------/ \-------/
91 ^ ^
92 | |
93 \ / 10 Mpbs / 1ms
94 +--------\ /--------+
95 | |
96 v v
97 /--------\
98 | "root" |
99 \--------/
100
101The corresponding topology file (``topo-tree.txt``):
102
103.. literalinclude:: ../../examples/topologies/topo-tree.txt
104 :language: bash
105 :linenos:
106 :lines: 1-2,27-
107
108Example simulation (``ndn-tree-tracers.cc``) scenario that utilizes trace helpers:
109
110.. literalinclude:: ../../examples/ndn-tree-tracers.cc
111 :language: c++
112 :linenos:
113 :lines: 21-34,67-
114 :emphasize-lines: 7-11,63-67
115
116
117To run this scenario, use the following command::
118
119 ./waf --run=ndn-tree-tracers
120
121The 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.
122
123For example, the following `R script <http://www.r-project.org/>`_ will build a number of nice graphs:
124
125.. image:: _static/root-rates.png
126 :alt: Interest/Data packet rates at the root node
127 :align: right
128
129.. image:: _static/root-5sec-counts.png
130 :alt: Interest/Data packet counts at the root node in 5-second intervals
131 :align: right
132
133.. literalinclude:: ../../examples/graphs/rate-graph.R
134 :language: r
135 :linenos:
136
137For 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/>`_.
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800138
139.. _cs trace helper:
140
141Content store trace helper
142--------------------------
143
Alexander Afanasyevb1d6b032013-01-18 14:11:11 -0800144- :ndnsim:`ndn::CsTracer`
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800145
Alexander Afanasyevb1d6b032013-01-18 14:11:11 -0800146 With the use of :ndnsim:`ndn::CsTracer` it is possible to obtain statistics of cache hits/cache misses on simulation nodes.
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800147
148 The following code enables content store tracing:
149
150 .. code-block:: c++
151
152 // necessary includes
Alexander Afanasyevb1d6b032013-01-18 14:11:11 -0800153 #include <ns3/ndnSIM/utils/tracers/ndn-cs-tracer.h>
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800154
155 ...
156
157 // Select implementation of content store. By default, the following is applied:
158 // ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Lru", "MaxSize", "100");
159
160 // the following should be put just before calling Simulator::Run in the scenario
161
Alexander Afanasyevb1d6b032013-01-18 14:11:11 -0800162 boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::CsTracer> > >
163 aggTracers = ndn::CsTracer::InstallAll ("cs-trace.txt", Seconds (1));
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800164
165 Simulator::Run ();
166
167 ...
168
169.. - Tracing lifetime of content store entries
170
171.. Evaluate lifetime of the content store entries can be accomplished using modified version of the content stores.
172.. In particular,
173
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800174.. _cs trace helper example:
175
176Example of content store trace helper
177+++++++++++++++++++++++++++++++++++++
178
179This example (``ndn-tree-cs-tracers.cc``) demonstrates basic usage of content store tracer.
180
181In 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.
182The 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.
183
184Example simulation (``ndn-tree-cs-tracers.cc``) scenario that utilizes trace helpers:
185
186.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cc
187 :language: c++
188 :linenos:
189 :lines: 21-31,64-
190 :emphasize-lines: 7-11,25,43,45,62-63
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800191
192
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800193To run this scenario, use the following command::
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800194
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800195 ./waf --run=ndn-tree-cs-tracers
196
197The 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.
198
199
200Application-level trace helper
201------------------------------
202
203- :ndnsim:`ndn::AppDelayTracer`
204
205 With the use of :ndnsim:`ndn::AppDelayTracer` it is possible to obtain data about for delays between issuing Interest and receiving corresponding Data packet.
206
207 The following code enables application-level Interest-Data delay tracing:
208
209 .. code-block:: c++
210
211 // necessary includes
212 #include <ns3/ndnSIM/utils/tracers/ndn-app-delay-tracer.h>
213
214 ...
215
216 // the following should be put just before calling Simulator::Run in the scenario
217
218 boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::AppDelayTracer> > >
219 tracers = ndn::AppDelayTracer::InstallAll ("app-delays-trace.txt");
220
221 Simulator::Run ();
222
223 ...
224
Alexander Afanasyev29dfb982013-01-18 20:04:15 -0800225 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:
226
227 +-----------------+---------------------------------------------------------------------+
228 | Column | Description |
229 +=================+=====================================================================+
230 | ``Node`` | node id, global unique |
231 +-----------------+---------------------------------------------------------------------+
232 | ``AppId`` | app id, local unique on the node, not global |
233 +-----------------+---------------------------------------------------------------------+
234 | ``SeqNo`` | seq number of the Interest-Data |
235 +-----------------+---------------------------------------------------------------------+
236 | ``Type`` | Type of delay: |
237 | | |
238 | | - ``LastDelay`` means that ``DelayS`` and ``DelayUS`` represent |
239 | | delay between last Interest sent and Data packet received |
240 | | - ``FullDelay`` means that ``DelayS`` and ``DelayUS`` represent |
241 | | delay between first Interest sent and Data packet received |
242 | | (i.e., includes time of Interest retransmissions) |
243 +-----------------+---------------------------------------------------------------------+
244 | ``DelayS`` | delay value, specified in seconds |
245 +-----------------+---------------------------------------------------------------------+
246 | ``DelayUS`` | delay value, specified in microseconds (10^-6) |
247 +-----------------+---------------------------------------------------------------------+
Alexander Afanasyev400aae12013-01-19 13:27:52 -0800248 | ``RetxCount`` | number of Interest retransmissions (for LastDelay always equal to 1)|
249 +-----------------+---------------------------------------------------------------------+
Alexander Afanasyev29dfb982013-01-18 20:04:15 -0800250
251
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800252.. _app delay trace helper example:
253
254Example of application-level trace helper
255+++++++++++++++++++++++++++++++++++++++++
256
257This example (``ndn-tree-app-delay-tracer.cc``) demonstrates basic usage of application-level Interest-Data delay tracer.
258
259In 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, ...
260
261Example simulation (``ndn-tree-app-delay-tracer.cc``) scenario that utilizes trace helpers:
262
263.. literalinclude:: ../../examples/ndn-tree-app-delay-tracer.cc
264 :language: c++
265 :linenos:
266 :lines: 21-31,64-
267 :emphasize-lines: 7-8,61-62
268
269
270To run this scenario, use the following command::
271
272 ./waf --run=ndn-tree-app-delay-tracer
273
274The 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.
275
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800276