granicus.if.org Git - icinga2/blob - doc/20-debug.md

   1 # <a id="debug"></a> Debug Icinga 2
   2
   3 > **Note**
   4 >
   5 > If you are planning to build your own development environment,
   6 > please consult the `INSTALL.md` file from the source tree.
   7
   8 ## <a id="debug-requirements"></a> Debug Requirements
   9
  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`.
  14
  15 Debian/Ubuntu:
  16
  17     # apt-get install icinga2-dbg
  18
  19 RHEL/CentOS:
  20
  21     # yum install icinga2-debuginfo
  22
  23 SLES/openSUSE:
  24
  25     # zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo
  26
  27
  28 Furthermore, you may also have to install debug symbols for Boost and your C library.
  29
  30 If you're building your own binaries you should use the `-DCMAKE_BUILD_TYPE=Debug` cmake
  31 build flag for debug builds.
  32
  33
  34 ## <a id="development-debug-gdb"></a> GDB
  35
  36 Install gdb:
  37
  38 Debian/Ubuntu:
  39
  40     # apt-get install gdb
  41
  42 RHEL/CentOS/Fedora:
  43
  44     # yum install gdb
  45
  46 SLES/openSUSE:
  47
  48     # zypper install gdb
  49
  50
  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`).
  53
  54     $ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
  55
  56 Boost Pretty Printers compatible with Python 3:
  57
  58     $ git clone https://github.com/mateidavid/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer
  59     $ git checkout python-3
  60     $ pwd
  61     /home/michi/.gdb_printers/Boost-Pretty-Printer
  62
  63 Python Pretty Printers:
  64
  65     $ cd ~/.gdb_printers
  66     $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
  67
  68 Icinga 2 Pretty Printers:
  69
  70     $ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
  71     $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
  72
  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.
  75
  76 Example on Fedora 22:
  77
  78     $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
  79     $ vim ~/.gdbinit
  80
  81     set print pretty on
  82
  83     python
  84     import sys
  85     sys.path.insert(0, '/home/michi/.gdb_printers/icinga2')
  86     from icingadbg import register_icinga_printers
  87     register_icinga_printers()
  88     end
  89
  90     python
  91     import sys
  92     sys.path.insert(0, '/home/michi/.gdb_printers/python')
  93     from libstdcxx.v6.printers import register_libstdcxx_printers
  94     try:
  95         register_libstdcxx_printers(None)
  96     except:
  97         pass
  98     end
  99
 100     python
 101     import sys
 102     sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer')
 103     import boost_print
 104     boost_print.register_printers()
 105     end
 106
 107
 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.
 111
 112     RuntimeError: pretty-printer already registered: libstdc++-v6
 113
 114 ### <a id="development-debug-gdb-run"></a> GDB Run
 115
 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.
 118
 119     # gdb --args /usr/sbin/icinga2 daemon -x debug -DUseVfork=0
 120
 121 > **Note**
 122 >
 123 > If gdb tells you it's missing debug symbols, quit gdb and install
 124 > them: `Missing separate debuginfos, use: debuginfo-install ...`
 125
 126 Run the application.
 127
 128     (gdb) r
 129
 130 Kill the running application.
 131
 132     (gdb) k
 133
 134 Continue after breakpoint.
 135
 136     (gdb) c
 137
 138 ### <a id="development-debug-gdb-coredump"></a> GDB Core Dump
 139
 140 Either attach to the running process using `gdb -p PID` or start
 141 a new gdb run.
 142
 143     (gdb) r
 144     (gdb) generate-core-file
 145
 146 ### <a id="development-debug-gdb-backtrace"></a> GDB Backtrace
 147
 148 If Icinga 2 aborted its operation abnormally, generate a backtrace.
 149
 150     (gdb) bt
 151     (gdb) bt full
 152
 153 Generate a full backtrace for all threads and store it into a new file
 154 (e.g. for debugging dead locks):
 155
 156     # gdb -p PID -batch -ex "thread apply all bt full" -ex "detach" -ex "q" > gdb_bt.log
 157
 158 If you're opening an issue at [https://dev.icinga.org] make sure
 159 to attach as much detail as possible.
 160
 161 ### <a id="development-debug-gdb-backtrace-stepping"></a> GDB Backtrace Stepping
 162
 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.
 166
 167     (gdb) up
 168     (gdb) down
 169     (gdb) p checkable
 170     (gdb) p checkable.px->m_Name
 171
 172
 173 ### <a id="development-debug-gdb-breakpoint"></a> GDB Breakpoints
 174
 175 To set a breakpoint to a specific function call, or file specific line.
 176
 177     (gdb) b checkable.cpp:125
 178     (gdb) b icinga::Checkable::SetEnablePerfdata
 179
 180 GDB will ask about loading the required symbols later, select `yes` instead
 181 of `no`.
 182
 183 Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
 184 afterwards.
 185
 186     (gdb) run
 187     (gdb) c
 188
 189 If you want to delete all breakpoints, use `d` and select `yes`.
 190
 191     (gdb) d
 192
 193 > **Tip**
 194 >
 195 > When debugging exceptions, set your breakpoint like this: `b __cxa_throw`.
 196
 197 Breakpoint Example:
 198
 199     (gdb) b __cxa_throw
 200     (gdb) r
 201     (gdb) up
 202     ....
 203     (gdb) up
 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
 206     609                 callback(cpath);
 207     (gdb) l
 208     604
 209     605 #endif /* _WIN32 */
 210     606
 211     607         std::sort(files.begin(), files.end());
 212     608         BOOST_FOREACH(const String& cpath, files) {
 213     609                 callback(cpath);
 214     610         }
 215     611
 216     612         std::sort(dirs.begin(), dirs.end());
 217     613         BOOST_FOREACH(const String& cpath, dirs) {
 218     (gdb) p files
 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"}}