add more options (issue #5137)
[asterisk/asterisk.git] / doc / README.backtrace
1
2
3 This document is to provide information on how to obtain the backtraces required on the asterisk bug tracker, available at http://bugs.digium.com.
4 The information is required by developers to help fix problem with bugs of any kind.
5 Backtraces provide information about what was wrong when a program crashed; in our case, Asterisk.
6 There are two kind of backtraces (aka 'bt'), which are useful: bt and bt full.
7
8 First of all, when you start Asterisk, you MUST start it with option -g (this tells Asterisk to produce a core file if it crashes).
9 If you start Asterisk with the safe_asterisk script, it automatically starts using the option -g.
10
11 If you're not sure if Asterisk is running with the -g option, type the following command in your shell:
12
13 debian:/tmp# ps aux | grep asterisk
14 root     17832  0.0  1.2   2348   788 pts/1    S    Aug12   0:00 /bin/sh /usr/sbin/safe_asterisk
15 root     26686  0.0  2.8  15544  1744 pts/1    S    Aug13   0:02 asterisk -vvvg -c
16 [...]
17
18 The interesting information is located in the last column.
19
20
21 After Asterisk crashes, a core file will be "dumped" in your /tmp/ directory
22 To make sure it's really there, you can just type the following command in your shell:
23
24 debian:/tmp# ls -l /tmp/core.*
25 -rw-------  1 root root 10592256 Aug 12 19:40 /tmp/core.26252
26 -rw-------  1 root root  9924608 Aug 12 20:12 /tmp/core.26340
27 -rw-------  1 root root 10862592 Aug 12 20:14 /tmp/core.26374
28 -rw-------  1 root root  9105408 Aug 12 20:19 /tmp/core.26426
29 -rw-------  1 root root  9441280 Aug 12 20:20 /tmp/core.26462
30 -rw-------  1 root root  8331264 Aug 13 00:32 /tmp/core.26647
31 debian:/tmp#
32
33 Now that we've verified the core file has been written to disk, the final part is to extract 'bt' from the core file.
34 Core files are pretty big, don't be scared, it's normal.
35
36 *** NOTE: Don't attach core files on the bug tracker, we only need the bt and bt full. ***
37
38 For extraction, we use a really nice tool, called gdb. To verify that you have gdb installed on your system:
39
40 debian:/tmp# gdb -v
41 GNU gdb 6.3-debian
42 Copyright 2004 Free Software Foundation, Inc.
43 GDB is free software, covered by the GNU General Public License, and you are
44 welcome to change it and/or distribute copies of it under certain conditions.
45 Type "show copying" to see the conditions.
46 There is absolutely no warranty for GDB.  Type "show warranty" for details.
47 This GDB was configured as "i386-linux".
48 debian:/tmp#
49
50 Which is great, we can continue. If you don't have gdb installed, go install gdb.
51
52 Now load the core file in gdb, as follows:
53
54 debian:/tmp# gdb -se "asterisk" -c /tmp/core.26252
55 [...]
56 (You would see a lot of output here.)
57 [...]
58 Reading symbols from /usr/lib/asterisk/modules/app_externalivr.so...done.
59 Loaded symbols for /usr/lib/asterisk/modules/app_externalivr.so
60 #0  0x29b45d7e in ?? ()
61 (gdb)
62
63 Now at the gdb prompt, type: bt
64 You would see output similar to:
65 (gdb) bt
66 #0  0x29b45d7e in ?? ()
67 #1  0x08180bf8 in ?? ()
68 #2  0xbcdffa58 in ?? ()
69 #3  0x08180bf8 in ?? ()
70 #4  0xbcdffa60 in ?? ()
71 #5  0x08180bf8 in ?? ()
72 #6  0x180bf894 in ?? ()
73 #7  0x0bf80008 in ?? ()
74 #8  0x180b0818 in ?? ()
75 #9  0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180
76 #10 0x000000a0 in ?? ()
77 #11 0x000000a0 in ?? ()
78 #12 0x00000000 in ?? ()
79 #13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262
80 #14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965
81 #15 0xbcdffbe0 in ?? ()
82 #16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0
83 #17 0x401ec92a in clone () from /lib/libc.so.6
84 (gdb)
85
86
87 The bt's output is the informations that we need on the bug tracker.
88
89 Now do a bt full as follows:
90 (gdb) bt full
91 #0  0x29b45d7e in ?? ()
92 No symbol table info available.
93 #1  0x08180bf8 in ?? ()
94 No symbol table info available.
95 #2  0xbcdffa58 in ?? ()
96 No symbol table info available.
97 #3  0x08180bf8 in ?? ()
98 No symbol table info available.
99 #4  0xbcdffa60 in ?? ()
100 No symbol table info available.
101 #5  0x08180bf8 in ?? ()
102 No symbol table info available.
103 #6  0x180bf894 in ?? ()
104 No symbol table info available.
105 #7  0x0bf80008 in ?? ()
106 No symbol table info available.
107 #8  0x180b0818 in ?? ()
108 No symbol table info available.
109 #9  0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180
110 No locals.
111 #10 0x000000a0 in ?? ()
112 No symbol table info available.
113 #11 0x000000a0 in ?? ()
114 No symbol table info available.
115 #12 0x00000000 in ?? ()
116 No symbol table info available.
117 #13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262
118         f = (struct ast_frame *) 0x8180bf8
119         trans = (struct ast_trans_pvt *) 0x0
120 #14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965
121 No locals.
122 #15 0xbcdffbe0 in ?? ()
123 No symbol table info available.
124 #16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0
125 No symbol table info available.
126 #17 0x401ec92a in clone () from /lib/libc.so.6
127 No symbol table info available.
128 (gdb)
129
130
131 We also need gdb's output.
132 That output gives more details compared to the simple "bt". So we recommend that you use bt full instead of bt.
133 But, if you could include both, we appreciate that.
134
135 The final "extraction" would the to know all traces by all threads. Even if asterisk runs on the same thread for each calls, it could have some new threads created.
136 To make sure we have the correct informations, just do:
137 (gdb) thread apply all bt
138
139 Thread 1 (process 26252):
140 #0  0x29b45d7e in ?? ()
141 #1  0x08180bf8 in ?? ()
142 #2  0xbcdffa58 in ?? ()
143 #3  0x08180bf8 in ?? ()
144 #4  0xbcdffa60 in ?? ()
145 #5  0x08180bf8 in ?? ()
146 #6  0x180bf894 in ?? ()
147 #7  0x0bf80008 in ?? ()
148 #8  0x180b0818 in ?? ()
149 #9  0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180
150 #10 0x000000a0 in ?? ()
151 #11 0x000000a0 in ?? ()
152 #12 0x00000000 in ?? ()
153 #13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262
154 #14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965
155 #15 0xbcdffbe0 in ?? ()
156 #16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0
157 #17 0x401ec92a in clone () from /lib/libc.so.6
158 (gdb)
159
160
161 That output tell us crucial informations for threads.
162
163 Now, just create a output.txt and dump your "bt full" (and/or "bt") AND with "thread apply all bt".
164
165 Note: Please ATTACH your output, DO NOT paste it as a note.
166
167 And you're ready for upload on bug tracker.
168
169
170 Questions or comments regarding this documentation, feel free to pass by #asterisk-bugs on FreeNode.