OLD | NEW |
1 .. include:: replace.txt | 1 .. include:: replace.txt |
2 .. highlight:: cpp | 2 .. highlight:: cpp |
3 .. role:: raw-role(raw) | 3 .. role:: raw-role(raw) |
4 :format: html latex | 4 :format: html latex |
5 | 5 |
6 Data Collection | 6 Data Collection |
7 --------------- | 7 --------------- |
8 | 8 |
9 Our final tutorial chapter introduces some components that were added | 9 Our final tutorial chapter introduces some components that were added |
10 to |ns3| in version 3.18, and that are still under development. This | 10 to |ns3| starting with version 3.18, and that are still under development. |
11 tutorial section is also a work-in-progress. | 11 This tutorial section is also a work-in-progress. |
12 | 12 |
13 Motivation | 13 Motivation |
14 ********** | 14 ********** |
15 | 15 |
16 One of the main points of running simulations is to generate output data,· | 16 One of the main points of running simulations is to generate output data,· |
17 either for research purposes or simply to learn about the system. | 17 either for research purposes or simply to learn about the system. |
18 In the previous chapter, we introduced the tracing subsystem and | 18 In the previous chapter, we introduced the tracing subsystem and |
19 the example ``sixth.cc``. from which PCAP or ASCII trace files are· | 19 the example ``sixth.cc``. from which PCAP or ASCII trace files are· |
20 generated. These traces are valuable for data analysis using a | 20 generated. These traces are valuable for data analysis using a |
21 variety of external tools, and for many users, such output data is | 21 variety of external tools, and for many users, such output data is |
(...skipping 93 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
115 + { | 115 + { |
116 ... | 116 ... |
117 + probeType = "ns3::Ipv6PacketProbe"; | 117 + probeType = "ns3::Ipv6PacketProbe"; |
118 + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; | 118 + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; |
119 + } | 119 + } |
120 ... | 120 ... |
121 + // Use GnuplotHelper to plot the packet byte count over time | 121 + // Use GnuplotHelper to plot the packet byte count over time |
122 + GnuplotHelper plotHelper; | 122 + GnuplotHelper plotHelper; |
123 +· | 123 +· |
124 + // Configure the plot. The first argument is the file name prefix | 124 + // Configure the plot. The first argument is the file name prefix |
125 + // for the output files generated. The second, third, and fourth | 125 + // for the output files generated. The second, third, and fourth |
126 + // arguments are, respectively, the plot title, x-axis, and y-axis labels | 126 + // arguments are, respectively, the plot title, x-axis, and y-axis labels |
127 + plotHelper.ConfigurePlot ("seventh-packet-byte-count", | 127 + plotHelper.ConfigurePlot ("seventh-packet-byte-count", |
128 + "Packet Byte Count vs. Time", | 128 + "Packet Byte Count vs. Time", |
129 + "Time (Seconds)", | 129 + "Time (Seconds)", |
130 + "Packet Byte Count"); | 130 + "Packet Byte Count"); |
131 +· | 131 + |
132 + // Specify the probe type, trace source path (in configuration namespace),
and | 132 + // Specify the probe type, trace source path (in configuration namespace),
and |
133 + // probe output trace source ("OutputBytes") to plot. The fourth argument | 133 + // probe output trace source ("OutputBytes") to plot. The fourth argument |
134 + // specifies the name of the data series label on the plot. The last | 134 + // specifies the name of the data series label on the plot. |
135 + // argument formats the plot by specifying where the key should be placed. | 135 + plotHelper.AddProbe (probeType, |
136 + plotHelper.PlotProbe (probeType, | 136 + tracePath, |
137 + tracePath, | 137 + "OutputBytes", |
138 + "OutputBytes", | 138 + "Packet Byte Count"); |
139 + "Packet Byte Count", | |
140 + GnuplotAggregator::KEY_BELOW); | |
141 +· | 139 +· |
142 + // Use FileHelper to write out the packet byte count over time | 140 + // Use FileHelper to write out the packet byte count over time |
143 + FileHelper fileHelper; | 141 + FileHelper fileHelper; |
144 +· | 142 +· |
145 + // Configure the file to be written, and the formatting of output data. | 143 + // Configure the file to be written, and the formatting of output data. |
146 + fileHelper.ConfigureFile ("seventh-packet-byte-count", | 144 + fileHelper.ConfigureFile ("seventh-packet-byte-count", |
147 + FileAggregator::FORMATTED); | 145 + FileAggregator::FORMATTED); |
148 +· | 146 +· |
149 + // Set the labels for this formatted output file. | 147 + // Set the labels for this formatted output file. |
150 + fileHelper.Set2dFormat ("Time (Seconds) = %.3e\tPacket Byte Count = %.0f")
; | 148 + fileHelper.Set2dFormat ("Time (Seconds) = %.3e\tPacket Byte Count = %.0f")
; |
(...skipping 112 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
263 + std::string tracePath; | 261 + std::string tracePath; |
264 + probeType = "ns3::Ipv6PacketProbe"; | 262 + probeType = "ns3::Ipv6PacketProbe"; |
265 + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; | 263 + tracePath = "/NodeList/*/$ns3::Ipv6L3Protocol/Tx"; |
266 | 264 |
267 We use them here: | 265 We use them here: |
268 | 266 |
269 :: | 267 :: |
270 ··· | 268 ··· |
271 + // Specify the probe type, trace source path (in configuration namespace),
and | 269 + // Specify the probe type, trace source path (in configuration namespace),
and |
272 + // probe output trace source ("OutputBytes") to plot. The fourth argument | 270 + // probe output trace source ("OutputBytes") to plot. The fourth argument |
273 + // specifies the name of the data series label on the plot. The last | 271 + // specifies the name of the data series label on the plot.·· |
274 + // argument formats the plot by specifying where the key should be placed. | 272 + plotHelper.AddProbe (probeType, |
275 + plotHelper.PlotProbe (probeType, | 273 + tracePath, |
276 + tracePath, | 274 + "OutputBytes", |
277 + "OutputBytes", | 275 + "Packet Byte Count"); |
278 + "Packet Byte Count", | |
279 + GnuplotAggregator::KEY_BELOW); | |
280 | 276 |
281 The first two arguments are the name of the probe type and the trace source path
. | 277 The first two arguments are the name of the probe type and the trace source path
. |
282 These two are probably the hardest to determine when you try to use | 278 These two are probably the hardest to determine when you try to use |
283 this framework to plot other traces. The probe trace here is the ``Tx`` | 279 this framework to plot other traces. The probe trace here is the ``Tx`` |
284 trace source of class ``Ipv6L3Protocol``. When we examine this class | 280 trace source of class ``Ipv6L3Protocol``. When we examine this class |
285 implementation (``src/internet/model/ipv6-l3-protocol.cc``) we can | 281 implementation (``src/internet/model/ipv6-l3-protocol.cc``) we can |
286 observe: | 282 observe: |
287 | 283 |
288 :: | 284 :: |
289 | 285 |
290 .AddTraceSource ("Tx", "Send IPv6 packet to outgoing interface.", | 286 .AddTraceSource ("Tx", "Send IPv6 packet to outgoing interface.", |
291 MakeTraceSourceAccessor (&Ipv6L3Protocol::m_txTrace)) | 287 MakeTraceSourceAccessor (&Ipv6L3Protocol::m_txTrace), |
| 288 "ns3::Ipv6L3Protocol::TxRxTracedCallback") |
292 | 289 |
293 This says that ``Tx`` is a name for variable ``m_txTrace``, which has | 290 This says that ``Tx`` is a name for variable ``m_txTrace``, which has |
294 a declaration of: | 291 a declaration of: |
295 | 292 |
296 :: | 293 :: |
297 | 294 |
298 /** | 295 /** |
299 * \brief Callback to trace TX (transmission) packets. | 296 * \brief Callback to trace TX (transmission) packets. |
300 */ | 297 */ |
301 TracedCallback<Ptr<const Packet>, Ptr<Ipv6>, uint32_t> m_txTrace; | 298 TracedCallback<Ptr<const Packet>, Ptr<Ipv6>, uint32_t> m_txTrace; |
302 | 299 |
| 300 |
| 301 The last argument specifies that it is a TxRxTracedCallback; this· |
| 302 documentation string allows the signature to be easily found using |
| 303 Doxygen. If we look at this signature in the same header file, we can |
| 304 see also: |
| 305 |
| 306 :: |
| 307 |
| 308 /** |
| 309 * TracedCallback signature for packet transmission or reception events. |
| 310 * |
| 311 * \param [in] packet The packet. |
| 312 * \param [in] ipv6 |
| 313 * \param [in] interface |
| 314 */ |
| 315 typedef void (* TxRxTracedCallback) |
| 316 (const Ptr<const Packet> packet, const Ptr<const Ipv6> ipv6, |
| 317 const uint32_t interface); |
| 318 |
| 319 i.e. the same information about the arguments is present in this typedef. |
| 320 |
303 It turns out that this specific trace source signature is supported | 321 It turns out that this specific trace source signature is supported |
304 by a Probe class (what we need here) of class Ipv6PacketProbe. | 322 by a Probe class (what we need here) of class Ipv6PacketProbe. |
305 See the files ``src/internet/model/ipv6-packet-probe.{h,cc}``. | 323 See the files ``src/internet/model/ipv6-packet-probe.{h,cc}``. |
306 | 324 |
307 So, in the PlotProbe statement above, we see that the statement is | 325 So, in the AddProbe statement above, we see that the statement is |
308 hooking the trace source (identified by path string) with a matching | 326 hooking the trace source (identified by path string) with a matching |
309 |ns3| Probe type of ``Ipv6PacketProbe``. If we did not support | 327 |ns3| Probe type of ``Ipv6PacketProbe``. If we did not support |
310 this probe type (matching trace source signature), we could have not | 328 this probe type (matching trace source signature), we could have not |
311 used this statement (although some more complicated lower-level statements | 329 used this statement (although some more complicated lower-level statements |
312 could have been used, as described in the manual). | 330 could have been used, as described in the manual). |
313 | 331 |
314 The Ipv6PacketProbe exports, itself, some trace sources that extract | 332 The Ipv6PacketProbe exports, itself, some trace sources that extract |
315 the data out of the probed Packet object: | 333 the data out of the probed Packet object: |
316 | 334 |
317 :: | 335 :: |
318 ·· | 336 ·· |
319 TypeId | 337 TypeId |
320 Ipv6PacketProbe::GetTypeId () | 338 Ipv6PacketProbe::GetTypeId () |
321 { | 339 { |
322 static TypeId tid = TypeId ("ns3::Ipv6PacketProbe") | 340 static TypeId tid = TypeId ("ns3::Ipv6PacketProbe") |
323 .SetParent<Probe> () | 341 .SetParent<Probe> () |
324 .SetGroupName ("Stats") | 342 .SetGroupName ("Stats") |
325 .AddConstructor<Ipv6PacketProbe> () | 343 .AddConstructor<Ipv6PacketProbe> () |
326 .AddTraceSource ( "Output", | 344 .AddTraceSource ( "Output", |
327 "The packet plus its IPv6 object and interface that serv
e as the output for this probe", | 345 "The packet plus its IPv6 object and interface " |
328 MakeTraceSourceAccessor (&Ipv6PacketProbe::m_output)) | 346 "that serve as the output for this probe", |
| 347 MakeTraceSourceAccessor (&Ipv6PacketProbe::m_output), |
| 348 "ns3::Ipv6PacketProbe::TracedCallback") |
329 .AddTraceSource ( "OutputBytes", | 349 .AddTraceSource ( "OutputBytes", |
330 "The number of bytes in the packet", | 350 "The number of bytes in the packet", |
331 MakeTraceSourceAccessor (&Ipv6PacketProbe::m_outputBytes
)) | 351 MakeTraceSourceAccessor (&Ipv6PacketProbe::m_outputBytes
), |
| 352 "ns3::Packet::PacketSizeTracedCallback") |
332 ; | 353 ; |
333 return tid; | 354 return tid; |
334 } | 355 } |
335 ·· | 356 ·· |
336 | 357 |
337 The third argument of our PlotProbe statement specifies that we are | 358 The third argument of our AddProbe statement specifies that we are |
338 interested in the number of bytes in this packet; specifically, the | 359 interested in the number of bytes in this packet; specifically, the |
339 "OutputBytes" trace source of Ipv6PacketProbe. | 360 "OutputBytes" trace source of Ipv6PacketProbe. |
340 Finally, the last two arguments of the statement provide the plot | 361 Finally, the last two arguments of the statement provide the plot |
341 legend for this data series ("Packet Byte Count"), and an optional | 362 legend for this data series ("Packet Byte Count"), and an optional |
342 gnuplot formatting statement (GnuplotAggregator::KEY_BELOW) that we want· | 363 gnuplot formatting statement (GnuplotAggregator::KEY_BELOW) that we want· |
343 the plot key to be inserted below the plot. Other options include | 364 the plot key to be inserted below the plot. Other options include |
344 NO_KEY, KEY_INSIDE, and KEY_ABOVE. | 365 NO_KEY, KEY_INSIDE, and KEY_ABOVE. |
345 | 366 |
| 367 Multiple data series can be added to a single plot. |
| 368 This can be done by repeatedly calling ``AddProbe()`` such as in the |
| 369 previous example (avoiding the use of wildcards): |
| 370 |
| 371 :: |
| 372 |
| 373 tracePath = "/NodeList/0/$ns3::Ipv4L3Protocol/Tx"; |
| 374 plotHelper.AddProbe (probeType, |
| 375 tracePath, |
| 376 "OutputBytes", |
| 377 "Packet Byte Count for node 0"); |
| 378 tracePath = "/NodeList/1/$ns3::Ipv4L3Protocol/Tx"; |
| 379 plotHelper.AddProbe (probeType, |
| 380 tracePath, |
| 381 "OutputBytes", |
| 382 "Packet Byte Count for node 1"); |
| 383 |
| 384 Finally, by default, the helper uses a Collector type of· |
| 385 ``ns3::EventDrivenCollector`` which does not do any processing |
| 386 of the data generated asynchronously by the trace sources. Other |
| 387 Collector types are possible, such as a TimeSeriesCollector to |
| 388 generate periodic time-series, a TimeAverageCollector to generate |
| 389 rates (such as data rate from an interface, sampled every second),· |
| 390 and the ability to scale the Y-axis data using a ScalingCollector. |
| 391 More details can be found in the |ns3| manual. |
346 | 392 |
347 Supported Trace Types | 393 Supported Trace Types |
348 ********************* | 394 ********************* |
349 | 395 |
350 The following traced values are supported with Probes as of this writing: | 396 The following traced values are supported with Probes as of this writing: |
351 | 397 |
352 +------------------+-------------------+------------------------------------+ | 398 +------------------+-------------------+------------------------------------+ |
353 | TracedValue type | Probe type | File | | 399 | TracedValue type | Probe type | File | |
354 +==================+=========+=========+====================================+ | 400 +==================+=========+=========+====================================+ |
355 | double | DoubleProbe | stats/model/double-probe.h | | 401 | double | DoubleProbe | stats/model/double-probe.h | |
(...skipping 86 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
442 | 488 |
443 Summary | 489 Summary |
444 ******* | 490 ******* |
445 | 491 |
446 Data collection support is new as of ns-3.18, and basic support for | 492 Data collection support is new as of ns-3.18, and basic support for |
447 providing time series output has been added. The basic pattern described | 493 providing time series output has been added. The basic pattern described |
448 above may be replicated within the scope of support of the existing | 494 above may be replicated within the scope of support of the existing |
449 probes and trace sources. More capabilities including statistics | 495 probes and trace sources. More capabilities including statistics |
450 processing will be added in future releases.· | 496 processing will be added in future releases.· |
451 | 497 |
OLD | NEW |