|
1 <html> |
|
2 <head> |
|
3 <title> DTN2 Manual: Logging </title> |
|
4 <link rel="stylesheet" type="text/css" href="manual.css" /> |
|
5 </head> |
|
6 <body> |
|
7 <h1>About the Logging System |
|
8 </h1> |
|
9 |
|
10 <p> |
|
11 The DTN2 implementation uses the logging facility from |
|
12 <tt>oasys</tt>. It supports multiple log paths and different log |
|
13 levels for each log path. |
|
14 |
|
15 <p> |
|
16 The logging in DTN is organized into hierarchical paths. |
|
17 The basic idea is that a logf command contains an arbitrary log path, |
|
18 a level, and a printf-style body. For example: |
|
19 <p> |
|
20 logf("/some/path", LOG_INFO, "something happened %d times", count); |
|
21 |
|
22 |
|
23 <a name="dtndebug"/> |
|
24 <p><h2>.dtndebug</h2> |
|
25 If the file <tt>~/.dtndebug</tt> exists, it can be used to customize |
|
26 which log messages are emitted and which are ignored. It is read |
|
27 from the top down, one line at a time. Lines may start with "#" to indicate a |
|
28 comment. Blank lines are ignored. Any other line should have |
|
29 a logpath in the left column, and a log level in the right |
|
30 column. The columns are separated by spaces and/or tabs. |
|
31 |
|
32 <p> |
|
33 For instance, this .dtndebug file makes the default level for |
|
34 /dtn/* to be info, but causes debug info to be printed for all link |
|
35 operations other than for tcp0. |
|
36 |
|
37 <blockquote><pre># example .dtndebug file |
|
38 |
|
39 /dtn/link/tcp0 info |
|
40 /dtn/link debug |
|
41 /dtn info |
|
42 </pre></blockquote> |
|
43 |
|
44 <p> |
|
45 Note that the order is important. If <tt>/dtn info</tt> was place |
|
46 first in the list the entries this would have the effect of overriding |
|
47 entries after to log level<tt> info</tt>. |
|
48 |
|
49 <blockquote><pre># example .dtndebug file |
|
50 |
|
51 /dtn info |
|
52 /dtn/link/tcp0 info |
|
53 /dtn/link debug |
|
54 </pre></blockquote> |
|
55 |
|
56 <p>In dtnd, the log messages go out to standard out, by default. You can |
|
57 change that using the "-o filename" option to dtnd. |
|
58 |
|
59 <p>Here is the list of the logging levels: |
|
60 |
|
61 <ul> |
|
62 <li>debug |
|
63 <li>info |
|
64 <li>warn, warning |
|
65 <li>err, error |
|
66 <li>crit, critical |
|
67 <li>always |
|
68 </ul> |
|
69 |
|
70 <p> |
|
71 |
|
72 <p><h3>~/.dtndebug file options</h3> |
|
73 |
|
74 <p>There are several options that can be used to customize the display |
|
75 of debug output, and these options are specified on a line in the |
|
76 .dtndebug file prefixed with '%' <p> A detailed example of a .dtndebug file with |
|
77 options (incomplete!) is provided <a href=".dtndebug">here</a>. |
|
78 <p> |
|
79 <table border> |
|
80 |
|
81 <tr><td>no_path <td>Don't display log path |
|
82 <tr><td>no_time <td>Don't display time stamp |
|
83 <tr><td>no_level <td>Don't display log level |
|
84 <tr><td>brief <td>Truncate log name to a fixed length and use brief error codes |
|
85 <tr><td>color <td>Use terminal escape code to colorize output |
|
86 <tr><td>object <td>When possible, display the address of the object that |
|
87 generated the log. |
|
88 <tr><td>classname <td>When possible, display the class that generated the log message. |
|
89 </table> |
|
90 <p>See comments in oasys/debug/{Log,Logger}.h for a more in-depth explanation. |
|
91 |
|
92 <h4>Logging Targets</h4> |
|
93 |
|
94 <p>Below is an incomplete list of logging targets used by the DTN2 |
|
95 implementation. You can find others by observing output with |
|
96 logging turned up to the maximum ("/ debug" || dtnd -l debug) or by searching |
|
97 for <tt>logpath</tt> in the source code. |
|
98 <p> |
|
99 <table> |
|
100 |
|
101 <tr><td>/command <td>Singleton tcl command interpreter |
|
102 <tr><td>/command/<command_name> <td>Specific command "command_name" |
|
103 <tr><td>/log <td>Internal logging system |
|
104 <tr><td>/timer <td>Timer system |
|
105 <tr><td>/thread <td>Threading system |
|
106 |
|
107 <tr><td>/dtnd <td>DTN daemon wrapper |
|
108 <tr><td>/dtn/bundle/actions <td>BundleActions interface |
|
109 <tr><td>/dtn/bundle/daemon <td>BundleDaemon forwarder and basic logic |
|
110 <tr><td>/dtn/bundle/fragmentation <td>Fragmentation related code |
|
111 <tr><td>/dtn/bundle/list/<name> <td>BundleList data structure |
|
112 <tr><td>/dtn/bundle/protocol <td>Bundle wire protocol |
|
113 <tr><td>/dtn/bundle/refs <td>Reference counting for in-memory bundle objs |
|
114 <tr><td>/dtn/cl/<name> <td>Convergence layer |
|
115 <tr><td>/dtn/cl/tcp <td>TCP Convergence Layer |
|
116 <tr><td>/dtn/cl/udp <td>UDP Convergence Laye |
|
117 <tr><td>/dtn/cl/tcp/conn <td>TCP convergence layer connection |
|
118 <tr><td>/dtn/contact/manager <td>Contact Managment |
|
119 <tr><td>/dtn/interface/table <td>Local Interface table |
|
120 <tr><td>/dtn/link/<name> <td>Links to next-hop peers |
|
121 <tr><td>/dtn/link/<name>/contact <td>Open contact on links |
|
122 <tr><td>/dtn/route/<name> <td>BundleRouter <name> |
|
123 <tr><td>/dtn/registration/<regid> <td>Registration |
|
124 <tr><td>/dtn/registration/table <td>Table of registrations |
|
125 <tr><td>/dtn/storage/bundles <td>Storage backend for bundles |
|
126 <tr><td>/dtn/storage/global <td>Storage backend for global data |
|
127 <tr><td>/dtn/interface <td>interface management |
|
128 <tr><td>/dtn/tclcmd <td>Errors from TCL commands |
|
129 <tr><td>/dtn/apiserver <td>API Server |
|
130 <tr><td>/dtn/apiclient <td>API Client |
|
131 <tr><td>/dtn/discovery$name <td>discovery |
|
132 <tr><td>/dtn/discovery/ip <td>IP discovery |
|
133 <tr><td>/dtn/discovery/bt <td>Bluetooth discovery |
|
134 <tr><td>/dtn/bundle <td>Bundle |
|
135 <tr><td>/dtn/bundle/actions <td>BundleActions interface |
|
136 <tr><td>/dtn/bundle/daemon <td>BundleDaemon forwarder and basic logic |
|
137 <tr><td>/dtn/bundle/fragmentation <td>Fragmentation related code |
|
138 <tr><td>/dtn/bundle/list/$name <td>BundleList data structure |
|
139 <tr><td>/dtn/bundle/protocol <td>Bundle wire protocol |
|
140 <tr><td>/dtn/bundle/refs <td>Reference counting for in-memory bundle objs |
|
141 <tr><td>/dtn/contact/manager <td>Contact manager |
|
142 </table> |
|
143 |
|
144 <h2>Rereading the .dtndebug file </h2> |
|
145 |
|
146 <p>You can force the daemon to reread the <tt>.dtndebug</tt> file |
|
147 while it is running by sending it a HUP signal. You can also use |
|
148 the <a href="configuration.html#reparse_debug_file"><tt>log |
|
149 reparse_debug_file</tt></a> TCL command. |
|
150 |
|
151 <h2>Rotating the log file </h2> |
|
152 |
|
153 <p>You can send the daemon the USR1 signal to make it reopen the |
|
154 log file. You could use a shell script like this to roll the log |
|
155 file and start a new one: |
|
156 |
|
157 <blockquote><pre>mv log.txt log-`date +%Y-%m-%d`.txt |
|
158 pkill -USR1 dtnd |
|
159 </pre></blockquote> |
|
160 |
|
161 <p> |
|
162 You can also rotate the log file from inside the TCL interpreter |
|
163 using the <a href="configuration.html#rotate"><tt>log rotate</tt></a> |
|
164 TCL command. |
|
165 |
|
166 </body> |
|
167 </html> |
|
168 |