blob: 0e821f03a872fbc9407aa591019a77bae0d6bd15 [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 Afanasyev1a0fff62013-01-19 14:29:51 -0800250 | ``HopCount`` | combined number of number of hops for Interest and Data packet. |
251 | | Note that HopCount is increased anytime somebody calls Send method |
252 | | on a face, including delivery of Interest/Data to application via |
253 | | an AppFace (but not from application to ndn::L3Protocol!). |
254 | | |
255 | | One consequence is that Interests satisfied by an app will have |
256 | | even hop count (min hop count = 2), and Interests satisfied from |
257 | | caches will have off hop count (min hop count = 1) |
258 +-----------------+---------------------------------------------------------------------+
Alexander Afanasyev29dfb982013-01-18 20:04:15 -0800259
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800260.. _app delay trace helper example:
261
262Example of application-level trace helper
263+++++++++++++++++++++++++++++++++++++++++
264
265This example (``ndn-tree-app-delay-tracer.cc``) demonstrates basic usage of application-level Interest-Data delay tracer.
266
267In 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, ...
268
269Example simulation (``ndn-tree-app-delay-tracer.cc``) scenario that utilizes trace helpers:
270
271.. literalinclude:: ../../examples/ndn-tree-app-delay-tracer.cc
272 :language: c++
273 :linenos:
274 :lines: 21-31,64-
275 :emphasize-lines: 7-8,61-62
276
277
278To run this scenario, use the following command::
279
280 ./waf --run=ndn-tree-app-delay-tracer
281
282The 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.
283
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800284