granicus.if.org Git - icinga2/blob - doc/21-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 Boost Pretty Printers:
  55
  56     $ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
  57     $ git clone https://github.com/ruediger/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer
  58     $ pwd
  59     /home/michi/.gdb_printers/Boost-Pretty-Printer
  60
  61 Python Pretty Printers:
  62
  63     $ cd ~/.gdb_printers
  64     $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
  65
  66 Icinga 2 Pretty Printers:
  67
  68     $ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
  69     $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
  70
  71 Now you'll need to modify/setup your `~/.gdbinit` configuration file.
  72 You can download the one from Icinga 2 and modify all paths.
  73
  74 Example on Fedora:
  75
  76     $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
  77     $ vim ~/.gdbinit
  78
  79     set print pretty on
  80
  81     python
  82     import sys
  83     sys.path.insert(0, '/home/michi/.gdb_printers/icinga2')
  84     from icingadbg import register_icinga_printers
  85     register_icinga_printers()
  86     end
  87
  88     python
  89     import sys
  90     sys.path.insert(0, '/home/michi/.gdb_printers/python')
  91     from libstdcxx.v6.printers import register_libstdcxx_printers
  92     register_libstdcxx_printers(None)
  93     end
  94
  95     python
  96     import sys
  97     sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer')
  98     from boost.printers import register_printer_gen
  99     register_printer_gen(None)
 100     end
 101
 102 If you are getting the following error when running gdb, the `libstdcxx`
 103 printers are already preloaded in your environment and you can remove
 104 the duplicate import in your `~/.gdbinit` file.
 105
 106     RuntimeError: pretty-printer already registered: libstdc++-v6
 107
 108 ### <a id="development-debug-gdb-run"></a> GDB Run
 109
 110 Call GDB with the binary and all arguments and run it in foreground.
 111
 112     # gdb --args /usr/sbin/icinga2 daemon -x debug
 113
 114 > **Note**
 115 >
 116 > If gdb tells you it's missing debug symbols, quit gdb and install
 117 > them: `Missing separate debuginfos, use: debuginfo-install ...`
 118
 119 Run the application.
 120
 121     (gdb) r
 122
 123 Kill the running application.
 124
 125     (gdb) k
 126
 127 Continue after breakpoint.
 128
 129     (gdb) c
 130
 131 ### <a id="development-debug-gdb-backtrace"></a> GDB Backtrace
 132
 133 If Icinga 2 aborted its operation abnormally, generate a backtrace.
 134
 135     (gdb) bt
 136     (gdb) bt full
 137
 138 >**Tip**
 139 >
 140 > If you're opening an issue at [https://dev.icinga.org] make sure
 141 > to attach as much detail as possible.
 142
 143
 144 ### <a id="development-debug-gdb-backtrace-stepping"></a> GDB Backtrace Stepping
 145
 146 Identifying the problem may require stepping into the backtrace, analysing
 147 the current scope, attributes, and possible unmet requirements. `p` prints
 148 the value of the selected variable or function call result.
 149
 150     (gdb) up
 151     (gdb) down
 152     (gdb) p checkable
 153     (gdb) p checkable.px->m_Name
 154
 155
 156 ### <a id="development-debug-gdb-breakpoint"></a> GDB Breakpoints
 157
 158 To set a breakpoint to a specific function call, or file specific line.
 159
 160     (gdb) b checkable.cpp:125
 161     (gdb) b icinga::Checkable::SetEnablePerfdata
 162
 163 GDB will ask about loading the required symbols later, select `yes` instead
 164 of `no`.
 165
 166 Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
 167 afterwards.
 168
 169     (gdb) run
 170     (gdb) c
 171
 172 If you want to delete all breakpoints, use `d` and select `yes`.
 173
 174     (gdb) d
 175
 176 > **Tip**
 177 >
 178 > When debugging exceptions, set your breakpoint like this: `b __cxa_throw`.
 179
 180 Breakpoint Example:
 181
 182     (gdb) b __cxa_throw
 183     (gdb) r
 184     (gdb) up
 185     ....
 186     (gdb) up
 187     #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)
 188         at /home/michi/coding/icinga/icinga2/lib/base/utility.cpp:609
 189     609                 callback(cpath);
 190     (gdb) l
 191     604
 192     605 #endif /* _WIN32 */
 193     606
 194     607         std::sort(files.begin(), files.end());
 195     608         BOOST_FOREACH(const String& cpath, files) {
 196     609                 callback(cpath);
 197     610         }
 198     611
 199     612         std::sort(dirs.begin(), dirs.end());
 200     613         BOOST_FOREACH(const String& cpath, dirs) {
 201     (gdb) p files
 202     $3 = std::vector of length 11, capacity 16 = {{static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/agent.conf"}, {static NPos = 18446744073709551615,
 203         m_Data = "/etc/icinga2/conf.d/commands.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/downtimes.conf"}, {static NPos = 18446744073709551615,
 204         m_Data = "/etc/icinga2/conf.d/groups.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/notifications.conf"}, {static NPos = 18446744073709551615,
 205         m_Data = "/etc/icinga2/conf.d/satellite.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/services.conf"}, {static NPos = 18446744073709551615,
 206         m_Data = "/etc/icinga2/conf.d/templates.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/test.conf"}, {static NPos = 18446744073709551615,
 207         m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}}