author | Tom Henderson <tomh@tomh.org> |
Wed, 22 Oct 2008 22:13:22 -0700 | |
changeset 3771 | 21f40ccb03b3 |
parent 3382 | d5f8e5fae1c6 |
child 4032 | 2b675a0b3b94 |
permissions | -rw-r--r-- |
3332 | 1 |
|
2 |
@c ======================================================================== |
|
3 |
@c Begin document body here |
|
4 |
@c ======================================================================== |
|
5 |
||
6 |
@c ======================================================================== |
|
3340 | 7 |
@c PART: Tweaking ns-3 |
3332 | 8 |
@c ======================================================================== |
3340 | 9 |
@c The below chapters are under the major heading "Tweaking ns-3" |
3332 | 10 |
@c This is similar to the Latex \part command |
11 |
@c |
|
12 |
@c ======================================================================== |
|
3340 | 13 |
@c Tweaking ns-3 |
3332 | 14 |
@c ======================================================================== |
3340 | 15 |
@node Tweaking ns-3 |
16 |
@chapter Tweaking ns-3 |
|
3332 | 17 |
|
18 |
@menu |
|
19 |
* Using the Logging Module:: |
|
20 |
* Using Command Line Arguments:: |
|
21 |
* Using the Tracing System:: |
|
22 |
@end menu |
|
23 |
||
24 |
@c ======================================================================== |
|
25 |
@c Using the Logging Module |
|
26 |
@c ======================================================================== |
|
27 |
@node Using the Logging Module |
|
28 |
@section Using the Logging Module |
|
29 |
||
30 |
@cindex logging |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
31 |
We have already taken a brief look at the @command{ns-3} logging module while |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
32 |
going over the @code{first.cc} script. We will now take a closer look and |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
33 |
see what kind of use-cases the logging subsystem was designed to cover. |
3332 | 34 |
|
3342
8762b90e6f7e
formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents:
3340
diff
changeset
|
35 |
@node Logging Overview |
8762b90e6f7e
formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents:
3340
diff
changeset
|
36 |
@subsection Logging Overview |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
37 |
Many large systems support some kind of message logging facility, and |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
38 |
@command{ns-3} is not an exception. In some cases, only error messages are |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
39 |
logged to the ``operator console'' (which is typically @code{stderr} in Unix- |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
40 |
based systems). In other systems, warning messages may be output as well as |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
41 |
more detailed informational messages. In some cases, logging facilities are |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
42 |
used to output debug messages which can quickly turn the output into a blur. |
3332 | 43 |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
44 |
@command{Ns-3} takes the view that all of these verbosity levels are useful |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
45 |
and we provide a selectable, multi-level approach to message logging. Logging |
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
46 |
can be disabled completely, enabled on a component-by-component basis, or |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
47 |
enabled globally; and it provides selectable verbosity levels. The |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
48 |
@command{ns-3} log module provides a straightforward, relatively easy to use |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
49 |
way to get useful information out of your simulation. |
3332 | 50 |
|
51 |
You should understand that we do provide a general purpose mechanism --- |
|
52 |
tracing --- to get data out of your models which should be preferred for |
|
53 |
simulation output (see the tutorial section Using the Tracing System for |
|
54 |
more details on our tracing system). Logging should be preferred for |
|
55 |
debugging information, warnings, error messages, or any time you want to |
|
56 |
easily get a quick message out of your scripts or models. |
|
57 |
||
58 |
There are currently seven levels of log messages of increasing verbosity |
|
59 |
defined in the system. |
|
60 |
||
61 |
@itemize @bullet |
|
62 |
@item NS_LOG_ERROR --- Log error messages; |
|
63 |
@item NS_LOG_WARN --- Log warning messages; |
|
64 |
@item NS_LOG_DEBUG --- Log relatively rare, ad-hoc debugging messages; |
|
65 |
@item NS_LOG_INFO --- Log informational messages about program progress; |
|
66 |
@item NS_LOG_FUNCTION --- Log a message describing each function called; |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
67 |
@item NS_LOG_LOGIC -- Log messages describing logical flow within a function; |
3332 | 68 |
@item NS_LOG_ALL --- Log everything. |
69 |
@end itemize |
|
70 |
||
71 |
We also provide an unconditional logging level that is always displayed, |
|
72 |
irrespective of logging levels or component selection. |
|
73 |
||
74 |
@itemize @bullet |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
75 |
@item NS_LOG_UNCOND -- Log the associated message unconditionally. |
3332 | 76 |
@end itemize |
77 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
78 |
Each level can be requested singly or cumulatively; and logging can be set |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
79 |
up using a shell environment variable (NS_LOG) or by logging system function |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
80 |
call. As was seen earlier in the tutorial, the logging system has Doxygen |
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
81 |
documentation and now would be a good time to peruse the Logging Module |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
82 |
documentation if you have not done so. |
3332 | 83 |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
84 |
Now that you have read the documentation in great detail, let's use some of |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
85 |
that knowledge to get some interesting information out of the @code{first.cc} |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
86 |
example script you have already built. |
3332 | 87 |
|
3342
8762b90e6f7e
formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents:
3340
diff
changeset
|
88 |
@node Enabling Logging |
3356
be3532c51a37
Tutorial TOC tweaks
Craig Dowell <craigdo@ee.washington.edu>
parents:
3355
diff
changeset
|
89 |
@subsection Enabling Logging |
3332 | 90 |
@cindex NS_LOG |
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
91 |
Let's use the NS_LOG environment variable to turn on some more logging, but |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
92 |
to get our bearings, go ahead and run the script just as you did previously, |
3332 | 93 |
|
94 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
95 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
96 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 97 |
Compilation finished successfully |
98 |
Sent 1024 bytes to 10.1.1.2 |
|
99 |
Received 1024 bytes from 10.1.1.1 |
|
100 |
Received 1024 bytes from 10.1.1.2 |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
101 |
~/repos/ns-3-dev > |
3332 | 102 |
@end verbatim |
103 |
||
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
104 |
It turns out that the ``Sent'' and ``Received'' messages are actually logging |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
105 |
messages from the @code{UdpEchoClientApplication} and |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
106 |
@code{UdpEchoServerApplication}. We can ask the client application, for |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
107 |
example, to print more information by setting its logging level via the |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
108 |
NS_LOG environment variable. |
3332 | 109 |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
110 |
I am going to assume from here on that are using an sh-like shell that uses |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
111 |
the``VARIABLE=value'' syntax. If you are using a csh-like shell, then you |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
112 |
will have to convert my examples to the ``setenv VARIABLE value'' syntax |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
113 |
required by those shells. |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
114 |
|
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
115 |
Right now, the UDP echo client application is responding to the following line |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
116 |
of code in @code{first.cc}, |
3332 | 117 |
|
118 |
@verbatim |
|
119 |
LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO); |
|
120 |
@end verbatim |
|
121 |
||
122 |
This line of code enables the @code{LOG_LEVEL_INFO} level of logging. When |
|
123 |
we pass a logging level flag, we are actually enabling the given level and |
|
124 |
all lower levels. In this case, we have enabled @code{NS_LOG_INFO}, |
|
125 |
@code{NS_LOG_DEBUG}, @code{NS_LOG_WARN} and @code{NS_LOG_ERROR}. We can |
|
126 |
increase the logging level and get more information without changing the |
|
127 |
script and recompiling by setting the NS_LOG environment variable like this: |
|
128 |
||
129 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
130 |
~/repos/ns-3-dev > export NS_LOG=UdpEchoClientApplication=level_all |
3332 | 131 |
@end verbatim |
132 |
||
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
133 |
This sets the shell environment variable @code{NS_LOG} to the string, |
3332 | 134 |
|
135 |
@verbatim |
|
136 |
UdpEchoClientApplication=level_all |
|
137 |
@end verbatim |
|
138 |
||
139 |
The left hand side of the assignment is the name of the logging component we |
|
140 |
want to set, and the right hand side is the flag we want to use. In this case, |
|
141 |
we are going to turn on all of the debugging levels for the application. If |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
142 |
you run the script with NS_LOG set this way, the @command{ns-3} logging |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
143 |
system will pick up the change and you should see the following output: |
3332 | 144 |
|
145 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
146 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
147 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 148 |
Compilation finished successfully |
149 |
UdpEchoClientApplication:UdpEchoClient() |
|
150 |
UdpEchoClientApplication:StartApplication() |
|
151 |
UdpEchoClientApplication:ScheduleTransmit() |
|
152 |
UdpEchoClientApplication:Send() |
|
153 |
Sent 1024 bytes to 10.1.1.2 |
|
154 |
Received 1024 bytes from 10.1.1.1 |
|
155 |
UdpEchoClientApplication:HandleRead(0x62c640, 0x62cd70) |
|
156 |
Received 1024 bytes from 10.1.1.2 |
|
157 |
UdpEchoClientApplication:StopApplication() |
|
158 |
UdpEchoClientApplication:DoDispose() |
|
159 |
UdpEchoClientApplication:~UdpEchoClient() |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
160 |
~/repos/ns-3-dev > |
3332 | 161 |
@end verbatim |
162 |
||
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
163 |
The additional debug information provided by the application is from |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
164 |
the NS_LOG_FUNCTION level. This shows every time a function in the application |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
165 |
is called during script execution. Note that there are no requirements in the |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
166 |
@command{ns-3} system that models must support any particular logging |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
167 |
functionality. The decision regarding how much information is logged |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
168 |
is left to the individual model developer. In the case of the echo |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
169 |
applications, a good deal of log output is available. |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
170 |
|
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
171 |
You can now see a log of the function calls that were made to the application. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
172 |
If you look closely you will notice a single colon between the string |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
173 |
@code{UdpEchoClientApplication} and the method name where you might have |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
174 |
expected a C++ scope operator (@code{::}). This is intentional. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
175 |
|
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
176 |
The name is not actually a class name, it is a logging component name. When |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
177 |
there is a one-to-one correspondence between a source file and a class, this |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
178 |
will generally be the class name but you should understand that it is not |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
179 |
actually a class name, and there is a single colon there instead of a double |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
180 |
colon to remind you in a relatively subtle way to conceptually separate the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
181 |
logging component name from the class name. |
3332 | 182 |
|
3771
21f40ccb03b3
tutorial typos fixed (bug 379)
Tom Henderson <tomh@tomh.org>
parents:
3382
diff
changeset
|
183 |
It turns out that in some cases, it can be hard to determine which method |
3332 | 184 |
actually generates a log message. If you look in the text above, you may |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
185 |
wonder where the string ``@code{Received 1024 bytes from 10.1.1.2}'' comes |
3332 | 186 |
from. You can resolve this by ORing the @code{prefix_func} level into the |
187 |
@code{NS_LOG} environment variable. Try doing the following, |
|
188 |
||
189 |
@verbatim |
|
190 |
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func' |
|
191 |
@end verbatim |
|
192 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
193 |
Note that the quotes are required since the vertical bar we use to indicate an |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
194 |
OR operation is also a Unix pipe connector. |
3332 | 195 |
|
196 |
Now, if you run the script you will see that the logging system makes sure |
|
197 |
that every message from the given log component is prefixed with the component |
|
198 |
name. |
|
199 |
||
200 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
201 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
202 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 203 |
Compilation finished successfully |
204 |
UdpEchoClientApplication:UdpEchoClient() |
|
205 |
UdpEchoClientApplication:StartApplication() |
|
206 |
UdpEchoClientApplication:ScheduleTransmit() |
|
207 |
UdpEchoClientApplication:Send() |
|
208 |
UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2 |
|
209 |
Received 1024 bytes from 10.1.1.1 |
|
210 |
UdpEchoClientApplication:HandleRead(0x62c710, 0x62ce40) |
|
211 |
UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2 |
|
212 |
UdpEchoClientApplication:StopApplication() |
|
213 |
UdpEchoClientApplication:DoDispose() |
|
214 |
UdpEchoClientApplication:~UdpEchoClient() |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
215 |
~/repos/ns-3-dev > |
3332 | 216 |
@end verbatim |
217 |
||
218 |
You can now see all of the messages coming from the UDP echo client application |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
219 |
are identified as such. The message ``Received 1024 bytes from 10.1.1.2'' is |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
220 |
now clearly identified as coming from the echo client application. The |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
221 |
remaining message must be coming from the UDP echo server application. We |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
222 |
can enable that component by entering a colon separated list of components in |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
223 |
the NS_LOG environment variable. |
3332 | 224 |
|
225 |
@verbatim |
|
226 |
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func: |
|
227 |
UdpEchoServerApplication=level_all|prefix_func' |
|
228 |
@end verbatim |
|
229 |
||
230 |
Note that you will need to remove the newline after the @code{:} in the |
|
231 |
example text above. |
|
232 |
||
233 |
Now, if you run the script you will see all of the log messages from both the |
|
234 |
echo client and server applications. You may see that this can be very useful |
|
235 |
in debugging problems. |
|
236 |
||
237 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
238 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
239 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 240 |
Compilation finished successfully |
241 |
UdpEchoServerApplication:UdpEchoServer() |
|
242 |
UdpEchoClientApplication:UdpEchoClient() |
|
243 |
UdpEchoServerApplication:StartApplication() |
|
244 |
UdpEchoClientApplication:StartApplication() |
|
245 |
UdpEchoClientApplication:ScheduleTransmit() |
|
246 |
UdpEchoClientApplication:Send() |
|
247 |
UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2 |
|
248 |
UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1 |
|
249 |
UdpEchoServerApplication:HandleRead(): Echoing packet |
|
250 |
UdpEchoClientApplication:HandleRead(0x62c760, 0x62ce90) |
|
251 |
UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2 |
|
252 |
UdpEchoServerApplication:StopApplication() |
|
253 |
UdpEchoClientApplication:StopApplication() |
|
254 |
UdpEchoClientApplication:DoDispose() |
|
255 |
UdpEchoServerApplication:DoDispose() |
|
256 |
UdpEchoClientApplication:~UdpEchoClient() |
|
257 |
UdpEchoServerApplication:~UdpEchoServer() |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
258 |
~/repos/ns-3-dev > |
3332 | 259 |
@end verbatim |
260 |
||
261 |
It is also sometimes useful to be able to see the simulation time at which a |
|
262 |
log message is generated. You can do this by ORing in the prefix_time bit. |
|
263 |
||
264 |
@verbatim |
|
265 |
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time: |
|
266 |
UdpEchoServerApplication=level_all|prefix_func|prefix_time' |
|
267 |
@end verbatim |
|
268 |
||
269 |
If you run the script now, you should see the following output: |
|
270 |
||
271 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
272 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
273 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 274 |
Compilation finished successfully |
275 |
0ns UdpEchoServerApplication:UdpEchoServer() |
|
276 |
0ns UdpEchoClientApplication:UdpEchoClient() |
|
277 |
1000000000ns UdpEchoServerApplication:StartApplication() |
|
278 |
2000000000ns UdpEchoClientApplication:StartApplication() |
|
279 |
2000000000ns UdpEchoClientApplication:ScheduleTransmit() |
|
280 |
2000000000ns UdpEchoClientApplication:Send() |
|
281 |
2000000000ns UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2 |
|
282 |
2003686400ns UdpEchoServerApplication:HandleRead(): Received 1024 bytes |
|
283 |
from 10.1.1.1 |
|
284 |
2003686400ns UdpEchoServerApplication:HandleRead(): Echoing packet |
|
285 |
2007372800ns UdpEchoClientApplication:HandleRead(0x62c8c0, 0x62d020) |
|
286 |
2007372800ns UdpEchoClientApplication:HandleRead(): Received 1024 bytes |
|
287 |
from 10.1.1.2 |
|
288 |
10000000000ns UdpEchoServerApplication:StopApplication() |
|
289 |
10000000000ns UdpEchoClientApplication:StopApplication() |
|
290 |
UdpEchoClientApplication:DoDispose() |
|
291 |
UdpEchoServerApplication:DoDispose() |
|
292 |
UdpEchoClientApplication:~UdpEchoClient() |
|
293 |
UdpEchoServerApplication:~UdpEchoServer() |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
294 |
~/repos/ns-3-dev > |
3332 | 295 |
@end verbatim |
296 |
||
297 |
You can see that the constructor for the UdpEchoServer was called at a |
|
298 |
simulation time of 0 nanoseconds. This is actually happening before the |
|
299 |
simulation starts. The same for the UdpEchoClient constructor. |
|
300 |
||
301 |
Recall that the @code{first.cc} script started the echo server application at |
|
302 |
one second into the simulation. You can now see that the |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
303 |
@code{StartApplication} method of the server is, in fact, called at one second |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
304 |
(or one billion nanoseconds). You can also see that the echo client |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
305 |
application is started at a simulation time of two seconds as we requested in |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
306 |
the script. |
3332 | 307 |
|
308 |
You can now follow the progress of the simulation from the |
|
309 |
@code{ScheduleTransmit} call in the client that calls @code{Send} to the |
|
310 |
@code{HandleRead} callback in the echo server application. Note that the |
|
311 |
elapsed time as the packet is sent across the point-to-point link is 3.6864 |
|
312 |
milliseconds. You see the echo server logging a message telling you that it |
|
313 |
has echoed the packet and then, after a delay, you see the echo client receive |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
314 |
the echoed packet in its @code{HandleRead} method. |
3332 | 315 |
|
316 |
There is a lot that is happening under the covers in this simulation that you |
|
317 |
are not seeing as well. You can very easily follow the entire process by |
|
318 |
turning on all of the logging components in the system. Try setting the |
|
319 |
@code{NS_LOG} variable to the following, |
|
320 |
||
321 |
@verbatim |
|
322 |
export 'NS_LOG=*=level_all|prefix_func|prefix_time' |
|
323 |
@end verbatim |
|
324 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
325 |
The asterisk above is the logging component wildcard. This will turn on all |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
326 |
of the logging in all of the components used in the simulation. I won't |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
327 |
reproduce the output here (as of this writing it produces 772 lines of output |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
328 |
for the single packet echo) but you can redirect this information into a file |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
329 |
and look through it with your favorite editor if you like, |
3332 | 330 |
|
331 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
332 |
~/repos/ns-3-dev > ./waf --run scratch/first >& log.out |
3332 | 333 |
@end verbatim |
334 |
||
335 |
I personally use this quite a bit when I am presented with a problem and I |
|
336 |
have no idea where things are going wrong. I can follow the progress of the |
|
337 |
code quite easily without having to set breakpoints and step through code |
|
338 |
in a debugger. When I have a general idea about what is going wrong, I |
|
339 |
transition into a debugger for fine-grained examination of the problem. This |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
340 |
kind of output can be especially useful when your script does something |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
341 |
completely unexpected. If you are stepping using a debugger you may miss an |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
342 |
unexpected excursion completely. Logging the excursion makes it quickly |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
343 |
visible. |
3332 | 344 |
|
3342
8762b90e6f7e
formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents:
3340
diff
changeset
|
345 |
@node Adding Logging to your Code |
8762b90e6f7e
formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents:
3340
diff
changeset
|
346 |
@subsection Adding Logging to your Code |
3332 | 347 |
@cindex NS_LOG |
348 |
You can add new logging to your simulations by making calls to the log |
|
349 |
component via several macros. Let's do so in the @code{first.cc} script we |
|
350 |
have in the @code{scratch} directory. |
|
351 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
352 |
Recall that we have defined a logging component in that script: |
3332 | 353 |
|
354 |
@verbatim |
|
355 |
NS_LOG_COMPONENT_DEFINE ("FirstScriptExample"); |
|
356 |
@end verbatim |
|
357 |
||
358 |
You now know that you can enable all of the logging for this component by |
|
359 |
setting the @code{NS_LOG} environment variable to the various levels. Let's |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
360 |
go ahead add some logging to the script. The macro used to add an |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
361 |
informational level log message is @code{NS_LOG_INFO}. Go ahead and add one |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
362 |
just before we start creating the nodes that tells you that the script is |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
363 |
``Creating Topology.'' This is done as in this code snippet, |
3332 | 364 |
|
365 |
@verbatim |
|
366 |
NS_LOG_INFO ("Creating Topology"); |
|
367 |
@end verbatim |
|
368 |
||
369 |
Now build the script using waf and clear the @code{NS_LOG} variable to turn |
|
370 |
off the torrent of logging we previously enabled: |
|
371 |
||
372 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
373 |
~/repos/ns-3-dev > export NS_LOG= |
3332 | 374 |
@end verbatim |
375 |
||
376 |
Now, if you run the script, you will not see your new message since its |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
377 |
associated logging component (@code{FirstScriptExample}) has not been enabled. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
378 |
In order to see your message you will have to enable the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
379 |
@code{FirstScriptExample} logging component with a level greater than or equal |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
380 |
to @code{NS_LOG_INFO}. If you just want to see this particular level of |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
381 |
logging, you can enable it by, |
3332 | 382 |
|
383 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
384 |
~/repos/ns-3-dev > export NS_LOG=FirstScriptExample=info |
3332 | 385 |
@end verbatim |
386 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
387 |
If you now run the script you will see your new ``Creating Topology'' log |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
388 |
message, |
3332 | 389 |
|
390 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
391 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
392 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 393 |
Compilation finished successfully |
394 |
Creating Topology |
|
395 |
Sent 1024 bytes to 10.1.1.2 |
|
396 |
Received 1024 bytes from 10.1.1.1 |
|
397 |
Received 1024 bytes from 10.1.1.2 |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
398 |
~/repos/ns-3-dev > |
3332 | 399 |
@end verbatim |
400 |
||
401 |
@c ======================================================================== |
|
402 |
@c Using Command Line Arguments |
|
403 |
@c ======================================================================== |
|
404 |
@node Using Command Line Arguments |
|
405 |
@section Using Command Line Arguments |
|
406 |
||
3342
8762b90e6f7e
formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents:
3340
diff
changeset
|
407 |
@subsection Overriding Default Attributes |
3339
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
408 |
@cindex command line arguments |
3349
e6259dcffada
more editing passes through tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3348
diff
changeset
|
409 |
Another way you can change how @command{ns-3} scripts behave without editing |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
410 |
and building is via @emph{command line arguments.} We provide a mechanism to |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
411 |
parse command line arguments and automatically set local and global variables |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
412 |
based on those arguments. |
3332 | 413 |
|
414 |
The first step in using the command line argument system is to declare the |
|
415 |
command line parser. This is done quite simply (in your main program) as |
|
416 |
in the following code, |
|
417 |
||
418 |
@verbatim |
|
419 |
int |
|
420 |
main (int argc, char *argv[]) |
|
421 |
{ |
|
422 |
... |
|
423 |
||
424 |
CommandLine cmd; |
|
425 |
cmd.Parse (argc, argv); |
|
426 |
||
427 |
... |
|
428 |
} |
|
429 |
@end verbatim |
|
430 |
||
431 |
This simple two line snippet is actually very useful by itself. It opens the |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
432 |
door to the @command{ns-3} global variable and attribute systems. Go ahead |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
433 |
and add that two lines of code to the @code{first.cc} script at the start of |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
434 |
@code{main}. Go ahead and build the script and run it, but ask the script |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
435 |
for help in the following way, |
3332 | 436 |
|
437 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
438 |
~/repos/ns-3-dev > ./waf --run "scratch/first --PrintHelp" |
3332 | 439 |
@end verbatim |
440 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
441 |
This will ask Waf to run the @code{scratch/first} script and pass the command |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
442 |
line argument @code{--PrintHelp} to the script. The quotes are required to |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
443 |
sort out which program gets which argument. The command line parser will |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
444 |
now see the @code{--PrintHelp} argument and respond with, |
3332 | 445 |
|
446 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
447 |
~/repos/ns-3-dev > ./waf --run ``scratch/first --PrintHelp'' |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
448 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 449 |
Compilation finished successfully |
450 |
--PrintHelp: Print this help message. |
|
451 |
--PrintGroups: Print the list of groups. |
|
452 |
--PrintTypeIds: Print all TypeIds. |
|
453 |
--PrintGroup=[group]: Print all TypeIds of group. |
|
454 |
--PrintAttributes=[typeid]: Print all attributes of typeid. |
|
455 |
--PrintGlobals: Print the list of globals. |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
456 |
~/repos/ns-3-dev > |
3332 | 457 |
@end verbatim |
458 |
||
459 |
Let's focus on the @code{--PrintAttributes} option. We have already hinted |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
460 |
at the @command{ns-3} attribute system while walking through the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
461 |
@code{first.cc} script. We looked at the following lines of code, |
3332 | 462 |
|
463 |
@verbatim |
|
464 |
PointToPointHelper pointToPoint; |
|
3382
d5f8e5fae1c6
fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents:
3356
diff
changeset
|
465 |
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps")); |
d5f8e5fae1c6
fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents:
3356
diff
changeset
|
466 |
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms")); |
3332 | 467 |
@end verbatim |
468 |
||
469 |
and mentioned that @code{DataRate} was actually an @code{Attribute} of the |
|
470 |
@code{PointToPointNetDevice}. Let's use the command line argument parser |
|
471 |
to take a look at the attributes of the PointToPointNetDevice. The help |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
472 |
listing says that we should provide a @code{TypeId}. This corresponds to the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
473 |
class name of the class to which the attributes belong. In this case it will |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
474 |
be @code{ns3::PointToPointNetDevice}. Let's go ahead and type in, |
3332 | 475 |
|
476 |
@verbatim |
|
477 |
./waf --run "scratch/first --PrintAttributes=ns3::PointToPointNetDevice" |
|
478 |
@end verbatim |
|
479 |
||
480 |
The system will print out all of the attributes of this kind of net device. |
|
481 |
Among the attributes you will see listed is, |
|
482 |
||
483 |
@verbatim |
|
484 |
--ns3::PointToPointNetDevice::DataRate=[32768bps]: |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
485 |
The default data rate for point to point links |
3332 | 486 |
@end verbatim |
487 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
488 |
This is the default value that will be used when a @code{PointToPointNetDevice} |
3382
d5f8e5fae1c6
fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents:
3356
diff
changeset
|
489 |
is created in the system. We overrode this default with the attribute |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
490 |
setting in the @code{PointToPointHelper} above. Let's use the default values |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
491 |
for the point-to-point devices and channels by deleting the |
3382
d5f8e5fae1c6
fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents:
3356
diff
changeset
|
492 |
@code{SetDeviceAttribute} call and the @code{SetChannelAttribute} call from |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
493 |
the @code{first.cc} we have in the scratch directory. |
3332 | 494 |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
495 |
Your script should now just declare the @code{PointToPointHelper} and not do |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
496 |
any @code{set} operations as in the following example, |
3332 | 497 |
|
498 |
@verbatim |
|
499 |
... |
|
500 |
||
501 |
NodeContainer nodes; |
|
502 |
nodes.Create (2); |
|
503 |
||
504 |
PointToPointHelper pointToPoint; |
|
505 |
||
506 |
NetDeviceContainer devices; |
|
507 |
devices = pointToPoint.Install (nodes); |
|
508 |
||
509 |
... |
|
510 |
@end verbatim |
|
511 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
512 |
Go ahead and build the new script with Waf (@code{./waf}) and let's go back |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
513 |
and enable some logging from the UDP echo server application and turn on the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
514 |
time prefix. |
3332 | 515 |
|
516 |
@verbatim |
|
517 |
export 'NS_LOG=UdpEchoServerApplication=level_all|prefix_time' |
|
518 |
@end verbatim |
|
519 |
||
520 |
If you run the script, you should now see the following output, |
|
521 |
||
522 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
523 |
~/repos/ns-3-dev > ./waf --run scratch/first |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
524 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 525 |
Compilation finished successfully |
526 |
0ns UdpEchoServerApplication:UdpEchoServer() |
|
527 |
1000000000ns UdpEchoServerApplication:StartApplication() |
|
528 |
Sent 1024 bytes to 10.1.1.2 |
|
529 |
2257324218ns Received 1024 bytes from 10.1.1.1 |
|
530 |
2257324218ns Echoing packet |
|
531 |
Received 1024 bytes from 10.1.1.2 |
|
532 |
10000000000ns UdpEchoServerApplication:StopApplication() |
|
533 |
UdpEchoServerApplication:DoDispose() |
|
534 |
UdpEchoServerApplication:~UdpEchoServer() |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
535 |
~/repos/ns-3-dev > |
3332 | 536 |
@end verbatim |
537 |
||
538 |
Recall that the last time we looked at the simulation time at which the packet |
|
539 |
was received by the echo server, it was at 2.0036864 seconds. Now it is |
|
540 |
receiving the packet at about 2.257 seconds. This is because we just dropped |
|
541 |
the data rate of the @code{PointToPointNetDevice} down to its default of |
|
542 |
32768 bits per second from five megabits per second. |
|
543 |
||
544 |
If we were to provide a new @code{DataRate} using the command line, we could |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
545 |
speed our simulation up again. We do this in the following way, according to |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
546 |
the formula implied by the help item: |
3332 | 547 |
|
548 |
@verbatim |
|
549 |
./waf --run "scratch/first --ns3::PointToPointNetDevice::DataRate=5Mbps" |
|
550 |
@end verbatim |
|
551 |
||
552 |
This will set the default value of the @code{DataRate} attribute back to |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
553 |
five megabits per second. To get the original behavior of the script back, |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
554 |
we will have to set the speed-of-light delay of the channel. We can ask the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
555 |
command line system to print out the @code{Attributes} of the channel just |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
556 |
like we did the net device: |
3332 | 557 |
|
558 |
@verbatim |
|
559 |
./waf --run "scratch/first --PrintAttributes=ns3::PointToPointChannel" |
|
560 |
@end verbatim |
|
561 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
562 |
We discover the @code{Delay} attribute of the channel is set in the following |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
563 |
way: |
3332 | 564 |
|
565 |
@verbatim |
|
566 |
--ns3::PointToPointChannel::Delay=[0ns]: |
|
567 |
Transmission delay through the channel |
|
568 |
@end verbatim |
|
569 |
||
570 |
We can then set both of these default values through the command line system, |
|
571 |
||
572 |
@verbatim |
|
573 |
./waf --run "scratch/first |
|
574 |
--ns3::PointToPointNetDevice::DataRate=5Mbps |
|
575 |
--ns3::PointToPointChannel::Delay=2ms" |
|
576 |
@end verbatim |
|
577 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
578 |
in which case we recover the timing we had when we explicitly set the |
3332 | 579 |
@code{DataRate} and @code{Delay} in the script: |
580 |
||
581 |
@verbatim |
|
582 |
Compilation finished successfully |
|
583 |
0ns UdpEchoServerApplication:UdpEchoServer() |
|
584 |
1000000000ns UdpEchoServerApplication:StartApplication() |
|
585 |
Sent 1024 bytes to 10.1.1.2 |
|
586 |
2003686400ns Received 1024 bytes from 10.1.1.1 |
|
587 |
2003686400ns Echoing packet |
|
588 |
Received 1024 bytes from 10.1.1.2 |
|
589 |
10000000000ns UdpEchoServerApplication:StopApplication() |
|
590 |
UdpEchoServerApplication:DoDispose() |
|
591 |
UdpEchoServerApplication:~UdpEchoServer() |
|
592 |
@end verbatim |
|
593 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
594 |
Note that the packet is again received by the server at 2.0036864 seconds. We |
3332 | 595 |
could actually set any of the attributes used in the script in this way. In |
596 |
particular we could set the @code{UdpEchoClient} attribute @code{MaxPackets} |
|
597 |
to some other value than one. |
|
598 |
||
599 |
How would you go about that? Give it a try. Remember you have to comment |
|
600 |
out the place we override the default attribute in the script. Then you |
|
601 |
have to rebuild the script using the default. You will also have to find the |
|
602 |
syntax for actually setting the new default atribute value using the command |
|
603 |
line help facility. Once you have this figured out you should be able to |
|
604 |
control the number of packets echoed from the command line. Since we're nice |
|
605 |
folks, we'll tell you that your command line should end up looking something |
|
606 |
like, |
|
607 |
||
608 |
@verbatim |
|
609 |
./waf --run "scratch/first |
|
610 |
--ns3::PointToPointNetDevice::DataRate=5Mbps |
|
611 |
--ns3::PointToPointChannel::Delay=2ms |
|
612 |
--ns3::UdpEchoClient::MaxPackets=2" |
|
613 |
@end verbatim |
|
614 |
||
615 |
@subsection Hooking Your Own Values |
|
616 |
You can also add your own hooks to the command line system. This is done |
|
617 |
quite simply by using the @code{AddValue} method to the command line parser. |
|
618 |
||
619 |
Let's use this facility to specify the number of packets to echo in a |
|
620 |
completely different way. Let's add a local variable called @code{nPackets} |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
621 |
to the @code{main} function. We'll initialize it to one to match our previous |
3332 | 622 |
default behavior. To allow the command line parser to change this value, we |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
623 |
need to hook the value into the parser. We do this by adding a call to |
3332 | 624 |
@code{AddValue}. Go ahead and change the @code{scratch/first.cc} script to |
625 |
start with the following code, |
|
626 |
||
627 |
@verbatim |
|
3771
21f40ccb03b3
tutorial typos fixed (bug 379)
Tom Henderson <tomh@tomh.org>
parents:
3382
diff
changeset
|
628 |
int |
3332 | 629 |
main (int argc, char *argv[]) |
630 |
{ |
|
631 |
uint32_t nPackets = 1; |
|
632 |
||
633 |
CommandLine cmd; |
|
634 |
cmd.AddValue("nPackets", "Number of packets to echo", nPackets); |
|
635 |
cmd.Parse (argc, argv); |
|
636 |
||
637 |
... |
|
638 |
@end verbatim |
|
639 |
||
640 |
Scroll down to the point in the script where we set the @code{MaxPackets} |
|
641 |
attribute and change it so that it is set to the variable @code{nPackets} |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
642 |
instead of the constant @code{1} as is shown below. |
3332 | 643 |
|
644 |
@verbatim |
|
645 |
echoClient.SetAppAttribute ("MaxPackets", UintegerValue (nPackets)); |
|
646 |
@end verbatim |
|
647 |
||
648 |
Now if you run the script and provide the @code{--PrintHelp} argument, you |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
649 |
should see your new @code{User Argument} listed in the help display. |
3332 | 650 |
|
651 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
652 |
~/repos/ns-3-dev > ./waf --run "scratch/first --PrintHelp" |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
653 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 654 |
Compilation finished successfully |
655 |
--PrintHelp: Print this help message. |
|
656 |
--PrintGroups: Print the list of groups. |
|
657 |
--PrintTypeIds: Print all TypeIds. |
|
658 |
--PrintGroup=[group]: Print all TypeIds of group. |
|
659 |
--PrintAttributes=[typeid]: Print all attributes of typeid. |
|
660 |
--PrintGlobals: Print the list of globals. |
|
661 |
User Arguments: |
|
662 |
--nPackets: Number of packets to echo |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
663 |
~/repos/ns-3-dev > |
3332 | 664 |
@end verbatim |
665 |
||
666 |
If you want to specify the number of packets to echo, you can now do so by |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
667 |
setting the @code{--nPackets} argument in the command line, |
3332 | 668 |
|
669 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
670 |
~/repos/ns-3-dev > ./waf --run "scratch/first --nPackets=2" |
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
671 |
Entering directory `/home/craigdo/repos/ns-3-dev/build' |
3332 | 672 |
Compilation finished successfully |
673 |
Sent 1024 bytes to 10.1.1.2 |
|
674 |
Received 1024 bytes from 10.1.1.1 |
|
675 |
Received 1024 bytes from 10.1.1.2 |
|
676 |
Sent 1024 bytes to 10.1.1.2 |
|
677 |
Received 1024 bytes from 10.1.1.1 |
|
678 |
Received 1024 bytes from 10.1.1.2 |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
679 |
~/repos/ns-3-dev > |
3332 | 680 |
@end verbatim |
681 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
682 |
You have now echoed two packets. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
683 |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
684 |
You can see that if you are an @command{ns-3} user, you can use the command |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
685 |
line argument system to control global values and attributes. If you are a |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
686 |
model author, you can add new attributes to your Objects and they will |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
687 |
automatically be available for setting by your users through the command line |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
688 |
system. If you are a script author, you can add new variables to your scripts |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
689 |
and hook them into the command line system quite painlessly. |
3332 | 690 |
|
691 |
@c ======================================================================== |
|
692 |
@c Using the Tracing System |
|
693 |
@c ======================================================================== |
|
694 |
@node Using the Tracing System |
|
695 |
@section Using the Tracing System |
|
696 |
||
697 |
The whole point of simulation is to generate output for further study, and |
|
698 |
the @command{ns-3} tracing system is a primary mechanism for this. Since |
|
699 |
@command{ns-3} is a C++ program, standard facilities for generating output |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
700 |
from C++ programs could be used: |
3332 | 701 |
|
702 |
@verbatim |
|
703 |
#include <iostream> |
|
704 |
... |
|
705 |
int main () |
|
706 |
{ |
|
707 |
... |
|
708 |
std::cout << "The value of x is " << x << std::endl; |
|
709 |
... |
|
710 |
} |
|
711 |
@end verbatim |
|
712 |
||
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
713 |
You could even use the logging module to add a little structure to your |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
714 |
solution. There are many well-known problems generated by such approaches |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
715 |
and so we have provided a generic event tracing subsystem to address the |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
716 |
issues we thought were important. |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
717 |
|
3332 | 718 |
The basic goals of the @command{ns-3} tracing system are: |
719 |
||
720 |
@itemize @bullet |
|
721 |
@item For basic tasks, the tracing system should allow the user to generate |
|
722 |
standard tracing for popular tracing sources, and to customize which objects |
|
723 |
generate the tracing; |
|
724 |
@item Intermediate users must be able to extend the tracing system to modify |
|
725 |
the output format generated, or to insert new tracing sources, without |
|
726 |
modifying the core of the simulator; |
|
727 |
@item Advanced users can modify the simulator core to add new tracing sources |
|
728 |
and sinks. |
|
729 |
@end itemize |
|
730 |
||
731 |
The @command{ns-3} tracing system is built on the concepts of independent |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
732 |
tracing sources and tracing sinks, and a uniform mechanism for connecting |
3332 | 733 |
sources to sinks. Trace sources are entities that can signal events that |
734 |
happen in a simulation and provide access to interesting underlying data. |
|
735 |
For example, a trace source could indicate when a packet is received by a net |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
736 |
device and provide access to the packet contents for interested trace sinks. |
3332 | 737 |
|
738 |
Trace sources are not useful by themselves, they must be ``connected'' to |
|
739 |
other pieces of code that actually do something useful with the information |
|
740 |
provided by the sink. Trace sinks are consumers of the events and data |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
741 |
provided by the trace sources. For example, one could create a trace sink |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
742 |
that would (when connected to the trace source of the previous example) print |
3332 | 743 |
out interesting parts of the received packet. |
744 |
||
745 |
The rationale for this explicit division is to allow users to attach new |
|
746 |
types of sinks to existing tracing sources, without requiring editing and |
|
747 |
recompilation of the the core of the simulator. Thus, in the example above, |
|
748 |
a user could define a new tracing sink in her script and attach it to an |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
749 |
existing tracing source defined in the simulation core by editing only the |
3332 | 750 |
user script. |
751 |
||
752 |
In this tutorial, we will walk through some pre-defined sources and sinks and |
|
753 |
show how they may be customized with little user effort. See the ns-3 manual |
|
754 |
or how-to sections for information on advanced tracing configuration including |
|
755 |
extending the tracing namespace and creating new tracing sources. |
|
756 |
||
757 |
@cindex tracing |
|
3339
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
758 |
@cindex ASCII tracing |
3332 | 759 |
@subsection ASCII Tracing |
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
760 |
@command{Ns-3} provides helper functionality that wraps the low-level tracing |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
761 |
system to help you with the details involved in configuring some easily |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
762 |
understood packet traces. If you enable this functionality, you will see |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
763 |
output in a ASCII files --- thus the name. For those familiar with |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
764 |
@command{ns-2} output, this type of trace is analogous to the @command{out.tr} |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
765 |
generated by many scripts. |
3332 | 766 |
|
3339
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
767 |
@cindex tracing packets |
3332 | 768 |
Let's just jump right in and add some ASCII tracing output to our |
769 |
@code{first.cc} script. The first thing you need to do is to add the |
|
770 |
following code to the script just before the call to @code{Simulator::Run ()}. |
|
771 |
||
772 |
@verbatim |
|
773 |
std::ofstream ascii; |
|
774 |
ascii.open ("first.tr"); |
|
775 |
PointToPointHelper::EnableAsciiAll (ascii); |
|
776 |
@end verbatim |
|
777 |
||
778 |
The first two lines are just vanilla C++ code to open a stream that will be |
|
779 |
written to a file named ``first.tr.'' See your favorite C++ tutorial if you |
|
780 |
are unfamiliar with this code. The last line of code in the snippet above |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
781 |
tells @command{ns-3} that you want to enable ASCII tracing on all |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
782 |
point-to-point devices in your simulation; and you want the (provided) trace |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
783 |
sinks to write out information about packet movement in ASCII format to the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
784 |
stream provided. For those familiar with @command{ns-2}, the traced events are |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
785 |
equivalent to the popular trace points that log "+", "-", "d", and "r" events. |
3332 | 786 |
|
787 |
Since we have used a @code{std::ofstream} object, we also need to include the |
|
788 |
appropriate header. Add the following line to the script (I typically add it |
|
789 |
above the ns-3 includes): |
|
790 |
||
791 |
@verbatim |
|
792 |
#include <fstream> |
|
793 |
@end verbatim |
|
794 |
||
795 |
You can now build the script and run it from the command line: |
|
796 |
||
797 |
@verbatim |
|
798 |
./waf --run scratch/first |
|
799 |
@end verbatim |
|
800 |
||
801 |
@cindex first.tr |
|
802 |
Just as you have seen previously, you may see some messages from Waf and then |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
803 |
the ``Compilation finished successfully'' with some number of messages from |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
804 |
the running program. |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
805 |
|
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
806 |
When it ran, the program will have created a file named @code{first.tr}. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
807 |
Because of the way that Waf works, the file is not created in the local |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
808 |
directory, it is created at the top-level directory of the repository by |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
809 |
default. If you want to control where the traces are saved you can use the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
810 |
@code{--cwd} option of Waf to specify this. We have not done so, thus we |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
811 |
need to change into the top level directory of our repo and take a look at |
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
812 |
the ASCII trace file @code{first.tr} in your favorite editor. |
3332 | 813 |
|
814 |
@subsubsection Parsing Ascii Traces |
|
815 |
@cindex parsing ascii traces |
|
816 |
There's a lot of information there in a pretty dense form, but the first thing |
|
817 |
to notice is that there are a number of distinct lines in this file. It may |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
818 |
be difficult to see this clearly unless you widen your window considerably. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
819 |
|
3332 | 820 |
Each line in the file corresponds to a @emph{trace event}. In this case |
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
821 |
we are tracing events on the @emph{transmit queue} present in every |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
822 |
point-to-point net device in the simulation. The transmit queue is a queue |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
823 |
through which every packet destined for a point-to-point channel must pass. |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
824 |
Note that each line in the trace file begins with a lone character (has a |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
825 |
space after it). This character will have the following meaning: |
3332 | 826 |
|
3339
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
827 |
@cindex ascii trace enqueue operation |
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
828 |
@cindex ascii trace dequeue operation |
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
829 |
@cindex ascii trace drop operation |
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
830 |
@cindex ascii trace receive operation |
3332 | 831 |
@itemize @bullet |
832 |
@item @code{+}: An enqueue operation occurred on the device queue; |
|
833 |
@item @code{-}: A dequeue operation occurred on the device queue; |
|
834 |
@item @code{d}: A packet was dropped, typically because the queue was full; |
|
835 |
@item @code{r}: A packet was received by the net device. |
|
836 |
@end itemize |
|
837 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
838 |
Let's take a more detailed view of the first line in the trace file. I'll |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
839 |
break it down into sections (indented for clarity) with a two digit reference |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
840 |
number on the left side: |
3332 | 841 |
|
842 |
@verbatim |
|
843 |
00 + |
|
844 |
01 2 |
|
845 |
02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue |
|
846 |
03 ns3::PppHeader ( |
|
847 |
04 Point-to-Point Protocol: IP (0x0021)) |
|
848 |
05 ns3::Ipv4Header ( |
|
849 |
06 tos 0x0 ttl 64 id 0 offset 0 flags [none] |
|
850 |
07 length: 1052 10.1.1.1 > 10.1.1.2) |
|
851 |
08 ns3::UdpHeader ( |
|
852 |
09 length: 1032 49153 > 9) |
|
853 |
10 Payload (size=1024) |
|
854 |
@end verbatim |
|
855 |
||
856 |
@cindex trace event |
|
857 |
@cindex simulation time |
|
858 |
The first line of this expanded trace event (reference number 00) is the |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
859 |
operation. We have a @code{+} character, so this corresponds to an |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
860 |
@emph{enqueue} operation on the transmit queue. The second line (reference 01) |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
861 |
is the simulation time expressed in seconds. You may recall that we asked the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
862 |
@code{UdpEchoClientApplication} to start sending packets at two seconds. Here |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
863 |
we see confirmation that this is, indeed, happening. |
3332 | 864 |
|
865 |
@cindex node number |
|
866 |
@cindex net device number |
|
867 |
@cindex smart pointer |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
868 |
The next line of the example trace (reference 02) tell us which trace source |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
869 |
originated this event (expressed in the tracing namespace). You can think |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
870 |
of the tracing namespace somewhat like you would a filesystem namespace. The |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
871 |
root of the namespace is the @code{NodeList}. This corresponds to a container |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
872 |
managed in the @command{ns-3} core code that contains all of the nodes that are |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
873 |
created in a script. Just as a filesystem may have directories under the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
874 |
root, we may have node numbers in the @code{NodeList}. The string |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
875 |
@code{/NodeList/0} therefore refers to the zeroth node in the @code{NodeList} |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
876 |
which we typically think of as ``node 0.'' In each node there is a list of |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
877 |
devices that have been installed. This list appears next in the namespace. |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
878 |
You can see that this trace event comes from @code{DeviceList/0} which is the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
879 |
zeroth device installed in the node. |
3332 | 880 |
|
881 |
The next string, @code{$ns3::PointToPointNetDevice} tells you what kind of |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
882 |
device is in the zeroth position of the device list for node zero. |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
883 |
Recall that the operation @code{+} found at reference 00 meant that an enqueue |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
884 |
operation happened on the transmit queue of the device. This is reflected in |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
885 |
the final segments of the ``trace path'' which are @code{TxQueue/Enqueue}. |
3332 | 886 |
|
887 |
The remaining lines in the trace should be fairly intuitive. References 03-04 |
|
888 |
indicate that the packet is encapulated in the point-to-point protocol. |
|
889 |
References 05-07 show that the packet has an IP version four header and has |
|
890 |
originated from IP address 10.1.1.1 and is destined for 10.1.1.2. References |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
891 |
08-09 show that this packet has a UDP header and, finally, reference 10 shows |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
892 |
that the payload is the expected 1024 bytes. |
3332 | 893 |
|
894 |
The next line in the trace file shows the same packet being dequeued from the |
|
895 |
transmit queue on the same node. |
|
896 |
||
897 |
The Third line in the trace file shows the packet being received by the net |
|
898 |
device on the node with the echo server. I have reproduced that event below. |
|
899 |
||
900 |
@verbatim |
|
901 |
00 r |
|
902 |
01 2.25732 |
|
903 |
02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/Rx |
|
904 |
03 ns3::PppHeader ( |
|
905 |
04 Point-to-Point Protocol: IP (0x0021)) |
|
906 |
05 ns3::Ipv4Header ( |
|
907 |
06 tos 0x0 ttl 64 id 0 offset 0 flags [none] |
|
908 |
07 length: 1052 10.1.1.1 > 10.1.1.2) |
|
909 |
08 ns3::UdpHeader ( |
|
910 |
09 length: 1032 49153 > 9) |
|
911 |
10 Payload (size=1024) |
|
912 |
@end verbatim |
|
913 |
||
914 |
Notice that the trace operation is now @code{r} and the simulation time has |
|
915 |
increased to 2.25732 seconds. If you have been following the tutorial steps |
|
916 |
closely this means that you have left the @code{DataRate} of the net devices |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
917 |
and the channel @code{Delay} set to their default values. This time should |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
918 |
be familiar as you have seen it before in a previous section. |
3332 | 919 |
|
920 |
The trace source namespace entry (reference 02) has changed to reflect that |
|
921 |
this event is coming from node 1 (@code{/NodeList/1}) and the packet reception |
|
922 |
trace source (@code{/Rx}). It should be quite easy for you to follow the |
|
923 |
progress of the packet through the topology by looking at the rest of the |
|
924 |
traces in the file. |
|
925 |
||
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
926 |
@subsection PCAP Tracing |
3332 | 927 |
@cindex pcap |
928 |
@cindex Wireshark |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
929 |
The @command{ns-3} device helpers can also be used to create trace files in the |
3332 | 930 |
@code{.pcap} format. The acronym pcap (usually written in lower case) stands |
931 |
for @emph{p}acket @emph{cap}ture, and is actually an API that includes the |
|
932 |
definition of a @code{.pcap} file format. The most popular program that can |
|
933 |
read and display this format is Wireshark (formerly called Ethereal). |
|
934 |
However, there are many traffic trace analyzers that use this packet format. |
|
935 |
We encourage users to exploit the many tools available for analyzing pcap |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
936 |
traces. In this tutorial, we concentrate on viewing pcap traces with tcpdump. |
3332 | 937 |
|
3339
ff29f4ba75ed
finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents:
3332
diff
changeset
|
938 |
@cindex pcap tracing |
3332 | 939 |
The code used to enable pcap tracing is a one-liner. |
940 |
||
941 |
@verbatim |
|
942 |
PointToPointHelper::EnablePcapAll ("first"); |
|
943 |
@end verbatim |
|
944 |
||
945 |
Go ahead and insert this line of code after the ASCII tracing code we just |
|
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
946 |
added to @code{scratch/first.cc}. Notice that we only passed the string |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
947 |
``first,'' and not ``first.pcap'' or something similar. This is because the |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
948 |
parameter is a prefix, not a complete file name. The helper will actually |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
949 |
create a trace file for every point-to-point device in the simulation. The |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
950 |
file names will be built using the prefix, the node number, the device number |
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
951 |
and a ``.pcap'' suffix. |
3332 | 952 |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
953 |
In our example script, we will eventually see files named ``first-0-0.pcap'' |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
954 |
and ``first.1-0.pcap'' which are the pcap traces for node 0-device 0 and |
3348
fe47da29d783
cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3343
diff
changeset
|
955 |
node 1-device 1, respectively. |
3332 | 956 |
|
3355
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
957 |
Once you have added the line of code to enable pcap tracing, you can run the |
ea06eff669b3
some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3354
diff
changeset
|
958 |
script in the usual way: |
3332 | 959 |
|
960 |
@verbatim |
|
961 |
./waf --run scratch/first |
|
962 |
@end verbatim |
|
963 |
||
964 |
If you look at the top level directory of your distribution, you should now |
|
965 |
see three log files: @code{first.tr} is the ASCII trace file we have |
|
966 |
previously examined. @code{first-0-0.pcap} and @code{first-1-0.pcap} |
|
967 |
are the new pcap files we just generated. |
|
968 |
||
969 |
@subsubsection Reading output with tcpdump |
|
970 |
@cindex tcpdump |
|
971 |
The easiest thing to do at this point will be to use @code{tcpdump} to look |
|
972 |
at the @code{pcap} files. Output from dumping both files is shown below: |
|
973 |
||
974 |
@verbatim |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
975 |
~/repos/ns-3-dev > /usr/sbin/tcpdump -r first-0-0.pcap -nn -tt |
3332 | 976 |
reading from file first-0-0.pcap, link-type PPP (PPP) |
977 |
2.000000 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024 |
|
978 |
2.514648 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024 |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
979 |
~/repos/ns-3-dev > /usr/sbin/tcpdump -r first-1-0.pcap -nn -tt |
3332 | 980 |
reading from file first-1-0.pcap, link-type PPP (PPP) |
981 |
2.257324 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024 |
|
982 |
2.257324 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024 |
|
3354
f11e4def3fc4
tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
3351
diff
changeset
|
983 |
~/repos/ns-3-dev > |
3332 | 984 |
@end verbatim |
985 |
||
986 |
You can see in the dump of ``first-0.0.pcap'' (the client device) that the |
|
987 |
echo packet is sent at 2 seconds into the simulation. If you look at the |
|
988 |
second dump (of ``first-1-0.pcap'') you can see that packet being received |
|
989 |
at 2.257324 seconds. You see the packet being echoed at 2.257324 seconds |
|
990 |
in the second dump, and finally, you see the packet being received back at |
|
991 |
the client in the first dump at 2.514648 seconds. |
|
992 |
||
993 |
@subsubsection Reading output with Wireshark |
|
994 |
@cindex Wireshark |
|
995 |
If you are unfamilar with Wireshark, there is a web site available from which |
|
996 |
you can download programs and documentation: @uref{http://www.wireshark.org/}. |
|
997 |
||
998 |
Wireshark is a graphical user interface which can be used for displaying these |
|
999 |
trace files. If you have Wireshark available, you can open each of the trace |
|
1000 |
files and display the contents as if you had captured the packets using a |
|
1001 |
@emph{packet sniffer}. |