From 8c9ba23cdc6b26d5d1bc4d6399af49b1539a7083 Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Mon, 3 Nov 2014 19:36:45 +0100 Subject: [PATCH] Docs: Update troubleshooting with gdb debug printer install refs #7514 --- doc/3-troubleshooting.md | 121 +++++++++++++++++++++++++++++++++++++- tools/debug/gdb/README.md | 40 +++++++++++++ 2 files changed, 159 insertions(+), 2 deletions(-) create mode 100644 tools/debug/gdb/README.md diff --git a/doc/3-troubleshooting.md b/doc/3-troubleshooting.md index 1768150c3..778c376c6 100644 --- a/doc/3-troubleshooting.md +++ b/doc/3-troubleshooting.md @@ -223,6 +223,13 @@ If the cluster zones do not sync their configuration, make sure to check the fol ## Debug Icinga 2 +> **Note** +> +> If you are planning to build your own development environment, +> please consult the `INSTALL.md` file from the source tree. + +### Debug Requirements + Make sure that the debug symbols are available for Icinga 2. The Icinga 2 packages provide a debug package which must be installed separately for all involved binaries, like `icinga2-bin` @@ -233,18 +240,93 @@ or `icinga2-ido-mysql`. # zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo # apt-get install icinga2-dbg + +Furthermore, boost and gcc require their debug symbols installed as well. Compiled binaries require the `-DCMAKE_BUILD_TYPE=RelWithDebInfo` or `-DCMAKE_BUILD_TYPE=Debug` cmake build flags. + ### GDB -Call GDB with the binary and all arguments and run it in foreground. +Install gdb: + + # yum install gdb + + # zypper install gdb + + # apt-get install gdb + +Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required, +so please make sure to update the installation paths accordingly (`pwd`). - # gdb --args /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -x +Boost Pretty Printers: + + $ mkdir ~/.gdb_printers && cd ~/.gdb_printers + $ git clone https://github.com/ruediger/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer + $ pwd + /home/michi/.gdb_printers/Boost-Pretty-Printer + +Python Pretty Printers: + + $ cd ~/.gdb_printers + $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python + +Icinga 2 Pretty Printers: + + $ mkdir -p ~/.gdb_printers/icinga2 && ~/.gdb_printers/icinga2 + $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py + +Now you'll need to modify/setup your `~/.gdbinit` configuration file. +You can download the one from Icinga 2 and modify all paths. + +> **Note** +> +> The path to the `pthread` library varies on distributions. Use +> `find /usr/lib* -type f -name '*libpthread.so*'` to get the proper +> path. + +Example on Fedora 20 x64: + + $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit + $ vim ~/.gdbinit + + set env LD_PRELOAD /usr/lib64/libpthread.so + + python + import sys + sys.path.insert(0, '/home/michi/.gdb_printers/icinga2') + from icingadbg import register_icinga_printers + register_icinga_printers() + end + + python + import sys + sys.path.insert(0, '/home/michi/.gdb_printers/python') + from libstdcxx.v6.printers import register_libstdcxx_printers + register_libstdcxx_printers(None) + end + + python + import sys + sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer') + from boost.printers import register_printer_gen + register_printer_gen(None) + end + + ### GDB Run +Call GDB with the binary and all arguments and run it in foreground. + + # gdb --args /usr/sbin/icinga2 daemon -x debug + +> **Note** +> +> If gdb tells you it's missing debug symbols, quit gdb and install +> them: `Missing separate debuginfos, use: debuginfo-install ...` + Run the application. (gdb) r @@ -301,3 +383,38 @@ afterwards. If you want to delete all breakpoints, use `d` and select `yes`. (gdb) d + +> **Tip** +> +> When debugging exceptions, set your breakpoint like this: `b __cxa_throw`. + +Breakpoint Example: + + (gdb) b __cxa_throw + (gdb) r + (gdb) up + .... + (gdb) up + #11 0x00007ffff7cbf9ff in icinga::Utility::GlobRecursive(icinga::String const&, icinga::String const&, boost::function const&, int) (path=..., pattern=..., callback=..., type=1) + at /home/michi/coding/icinga/icinga2/lib/base/utility.cpp:609 + 609 callback(cpath); + (gdb) l + 604 + 605 #endif /* _WIN32 */ + 606 + 607 std::sort(files.begin(), files.end()); + 608 BOOST_FOREACH(const String& cpath, files) { + 609 callback(cpath); + 610 } + 611 + 612 std::sort(dirs.begin(), dirs.end()); + 613 BOOST_FOREACH(const String& cpath, dirs) { + (gdb) p files + $3 = std::vector of length 11, capacity 16 = {{static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/agent.conf"}, {static NPos = 18446744073709551615, + m_Data = "/etc/icinga2/conf.d/commands.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/downtimes.conf"}, {static NPos = 18446744073709551615, + m_Data = "/etc/icinga2/conf.d/groups.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/notifications.conf"}, {static NPos = 18446744073709551615, + m_Data = "/etc/icinga2/conf.d/satellite.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/services.conf"}, {static NPos = 18446744073709551615, + m_Data = "/etc/icinga2/conf.d/templates.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/test.conf"}, {static NPos = 18446744073709551615, + m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}} + + diff --git a/tools/debug/gdb/README.md b/tools/debug/gdb/README.md new file mode 100644 index 000000000..e11bd6b20 --- /dev/null +++ b/tools/debug/gdb/README.md @@ -0,0 +1,40 @@ +# Pretty Printer Installation + +Requirements: +* icinga2 debug symbols +* boost, gcc, etc debug symbols + +Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required, +so please make sure to update the installation paths accordingly (`pwd`). + +Boost Pretty Printers: + + $ mkdir ~/.gdb_printers && cd ~/.gdb_printers + $ git clone https://github.com/ruediger/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer + $ pwd + /home/michi/.gdb_printers/Boost-Pretty-Printer + +Python Pretty Printers: + + $ cd ~/.gdb_printers + $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python + +Icinga 2 Pretty Printers: + + $ mkdir -p ~/.gdb_printers/icinga2 && ~/.gdb_printers/icinga2 + $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py + +Now you'll need to modify/setup your `~/.gdbinit` configuration file. +You can download the one from Icinga 2 and modify all paths. + +> **Note** +> +> The path to the `pthread` library varies on distributions. Use +> `find /usr/lib* -type f -name '*libpthread.so*'` to get the proper +> path. + + $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit + $ vim ~/.gdbinit + + +More details in the [troubleshooting debug documentation](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/troubleshooting#debug). -- 2.40.0