1 # <a id="debug"></a> Debug Icinga 2
5 > If you are planning to build your own development environment,
6 > please consult the `INSTALL.md` file from the source tree.
8 ## <a id="debug-requirements"></a> Debug Requirements
10 Make sure that the debug symbols are available for Icinga 2.
11 The Icinga 2 packages provide a debug package which must be
12 installed separately for all involved binaries, like `icinga2-bin`
13 or `icinga2-ido-mysql`.
17 # apt-get install icinga2-dbg
21 # yum install icinga2-debuginfo
25 # zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo
28 Furthermore, you may also have to install debug symbols for Boost and your C library.
30 If you're building your own binaries you should use the `-DCMAKE_BUILD_TYPE=Debug` cmake
31 build flag for debug builds.
34 ## <a id="development-debug-gdb"></a> GDB
51 Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required,
52 so please make sure to update the installation paths accordingly (`pwd`).
54 $ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
56 Boost Pretty Printers compatible with Python 3:
58 $ git clone https://github.com/mateidavid/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer
59 $ git checkout python-3
61 /home/michi/.gdb_printers/Boost-Pretty-Printer
63 Python Pretty Printers:
66 $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
68 Icinga 2 Pretty Printers:
70 $ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
71 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
73 Now you'll need to modify/setup your `~/.gdbinit` configuration file.
74 You can download the one from Icinga 2 and modify all paths.
78 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
85 sys.path.insert(0, '/home/michi/.gdb_printers/icinga2')
86 from icingadbg import register_icinga_printers
87 register_icinga_printers()
92 sys.path.insert(0, '/home/michi/.gdb_printers/python')
93 from libstdcxx.v6.printers import register_libstdcxx_printers
95 register_libstdcxx_printers(None)
102 sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer')
104 boost_print.register_printers()
108 If you are getting the following error when running gdb, the `libstdcxx`
109 printers are already preloaded in your environment and you can remove
110 the duplicate import in your `~/.gdbinit` file.
112 RuntimeError: pretty-printer already registered: libstdc++-v6
114 ### <a id="development-debug-gdb-run"></a> GDB Run
116 Call GDB with the binary and all arguments and run it in foreground.
117 If VFork causes trouble disable it inside the gdb run.
119 # gdb --args /usr/sbin/icinga2 daemon -x debug -DUseVfork=0
123 > If gdb tells you it's missing debug symbols, quit gdb and install
124 > them: `Missing separate debuginfos, use: debuginfo-install ...`
130 Kill the running application.
134 Continue after breakpoint.
138 ### <a id="development-debug-gdb-coredump"></a> GDB Core Dump
140 Either attach to the running process using `gdb -p PID` or start
144 (gdb) generate-core-file
146 ### <a id="development-debug-gdb-backtrace"></a> GDB Backtrace
148 If Icinga 2 aborted its operation abnormally, generate a backtrace.
153 Generate a full backtrace for all threads and store it into a new file
154 (e.g. for debugging dead locks):
156 # gdb -p PID -batch -ex "thread apply all bt full" -ex "detach" -ex "q" > gdb_bt.log
158 If you're opening an issue at [https://dev.icinga.org] make sure
159 to attach as much detail as possible.
161 ### <a id="development-debug-gdb-backtrace-stepping"></a> GDB Backtrace Stepping
163 Identifying the problem may require stepping into the backtrace, analysing
164 the current scope, attributes, and possible unmet requirements. `p` prints
165 the value of the selected variable or function call result.
170 (gdb) p checkable.px->m_Name
173 ### <a id="development-debug-gdb-breakpoint"></a> GDB Breakpoints
175 To set a breakpoint to a specific function call, or file specific line.
177 (gdb) b checkable.cpp:125
178 (gdb) b icinga::Checkable::SetEnablePerfdata
180 GDB will ask about loading the required symbols later, select `yes` instead
183 Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
189 If you want to delete all breakpoints, use `d` and select `yes`.
195 > When debugging exceptions, set your breakpoint like this: `b __cxa_throw`.
204 #11 0x00007ffff7cbf9ff in icinga::Utility::GlobRecursive(icinga::String const&, icinga::String const&, boost::function<void (icinga::String const&)> const&, int) (path=..., pattern=..., callback=..., type=1)
205 at /home/michi/coding/icinga/icinga2/lib/base/utility.cpp:609
209 605 #endif /* _WIN32 */
211 607 std::sort(files.begin(), files.end());
212 608 BOOST_FOREACH(const String& cpath, files) {
216 612 std::sort(dirs.begin(), dirs.end());
217 613 BOOST_FOREACH(const String& cpath, dirs) {
219 $3 = std::vector of length 11, capacity 16 = {{static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/agent.conf"}, {static NPos = 18446744073709551615,
220 m_Data = "/etc/icinga2/conf.d/commands.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/downtimes.conf"}, {static NPos = 18446744073709551615,
221 m_Data = "/etc/icinga2/conf.d/groups.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/notifications.conf"}, {static NPos = 18446744073709551615,
222 m_Data = "/etc/icinga2/conf.d/satellite.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/services.conf"}, {static NPos = 18446744073709551615,
223 m_Data = "/etc/icinga2/conf.d/templates.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/test.conf"}, {static NPos = 18446744073709551615,
224 m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}}