Documentation: Move Debug from Troubleshooting into a separate section

This commit is contained in:
Michael Friedrich 2015-02-11 16:58:15 +01:00
parent 2ae06b7a52
commit 06e6da081a
7 changed files with 215 additions and 219 deletions

View File

@ -16,7 +16,7 @@ re-implementation of the Livestatus protocol which is compatible with MK
Livestatus. Livestatus.
Details on the available tables and attributes with Icinga 2 can be found Details on the available tables and attributes with Icinga 2 can be found
in the [Livestatus Schema](18-appendix.md#schema-livestatus) section. in the [Livestatus Schema](19-apendix.md#schema-livestatus) section.
You can enable Livestatus using icinga2 feature enable: You can enable Livestatus using icinga2 feature enable:
@ -92,7 +92,7 @@ Example using the tcp socket listening on port `6558`:
### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries ### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries
A list of available external commands and their parameters can be found [here](18-appendix.md#external-commands-list-detail) A list of available external commands and their parameters can be found [here](19-apendix.md#external-commands-list-detail)
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558 $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
@ -190,5 +190,5 @@ Default separators.
The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects. The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](18-appendix.md#schema-livestatus). A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](19-apendix.md#schema-livestatus).

View File

@ -8,7 +8,7 @@
* Provide complete configuration snippets explaining your problem in detail * Provide complete configuration snippets explaining your problem in detail
* Provide complete logs targetting your problem * Provide complete logs targetting your problem
* If the check command failed - what's the output of your manual plugin tests? * If the check command failed - what's the output of your manual plugin tests?
* In case of [debugging](13-troubleshooting.md#debug) Icinga 2, the full back traces and outputs * In case of [debugging](18-debug.md#debug) Icinga 2, the full back traces and outputs
## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output ## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
@ -219,214 +219,3 @@ If the cluster zones do not sync their configuration, make sure to check the fol
** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes
** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/` ** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`
* The `icinga2.log` log file will indicate whether this ApiListener [accepts config](9-monitoring-remote-systems.md#zone-config-sync-permissions), or not * The `icinga2.log` log file will indicate whether this ApiListener [accepts config](9-monitoring-remote-systems.md#zone-config-sync-permissions), or not
## <a id="debug"></a> Debug Icinga 2
> **Note**
>
> If you are planning to build your own development environment,
> please consult the `INSTALL.md` file from the source tree.
### <a id="debug-requirements"></a> 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`
or `icinga2-ido-mysql`.
Debian/Ubuntu:
# apt-get install icinga2-dbg
RHEL/CentOS:
# yum install icinga2-debuginfo
SLES/openSUSE:
# zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo
Furthermore, you may also have to install debug symbols for Boost and your C library.
If you're building your own binaries you should use the `-DCMAKE_BUILD_TYPE=Debug` cmake
build flag for debug builds.
### <a id="development-debug-gdb"></a> GDB
Install gdb:
Debian/Ubuntu:
# apt-get install gdb
RHEL/CentOS/Fedora:
# yum install gdb
SLES/openSUSE:
# zypper 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`).
Boost Pretty Printers:
$ mkdir -p ~/.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 && cd ~/.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.
Example on Fedora:
$ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
$ vim ~/.gdbinit
set print pretty on
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
If you are getting the following error when running gdb, the `libstdcxx`
printers are already preloaded in your environment and you can remove
the duplicate import in your `~/.gdbinit` file.
RuntimeError: pretty-printer already registered: libstdc++-v6
### <a id="development-debug-gdb-run"></a> 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
Kill the running application.
(gdb) k
Continue after breakpoint.
(gdb) c
### <a id="development-debug-gdb-backtrace"></a> GDB Backtrace
If Icinga 2 aborted its operation abnormally, generate a backtrace.
(gdb) bt
(gdb) bt full
>**Tip**
>
> If you're opening an issue at [https://dev.icinga.org] make sure
> to attach as much detail as possible.
### <a id="development-debug-gdb-backtrace-stepping"></a> GDB Backtrace Stepping
Identifying the problem may require stepping into the backtrace, analysing
the current scope, attributes, and possible unmet requirements. `p` prints
the value of the selected variable or function call result.
(gdb) up
(gdb) down
(gdb) p checkable
(gdb) p checkable.px->m_Name
### <a id="development-debug-gdb-breakpoint"></a> GDB Breakpoints
To set a breakpoint to a specific function call, or file specific line.
(gdb) b checkable.cpp:125
(gdb) b icinga::Checkable::SetEnablePerfdata
GDB will ask about loading the required symbols later, select `yes` instead
of `no`.
Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
afterwards.
(gdb) run
(gdb) c
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<void (icinga::String const&)> 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"}}

207
doc/18-debug.md Normal file
View File

@ -0,0 +1,207 @@
# <a id="debug"></a> Debug Icinga 2
> **Note**
>
> If you are planning to build your own development environment,
> please consult the `INSTALL.md` file from the source tree.
## <a id="debug-requirements"></a> 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`
or `icinga2-ido-mysql`.
Debian/Ubuntu:
# apt-get install icinga2-dbg
RHEL/CentOS:
# yum install icinga2-debuginfo
SLES/openSUSE:
# zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo
Furthermore, you may also have to install debug symbols for Boost and your C library.
If you're building your own binaries you should use the `-DCMAKE_BUILD_TYPE=Debug` cmake
build flag for debug builds.
## <a id="development-debug-gdb"></a> GDB
Install gdb:
Debian/Ubuntu:
# apt-get install gdb
RHEL/CentOS/Fedora:
# yum install gdb
SLES/openSUSE:
# zypper 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`).
Boost Pretty Printers:
$ mkdir -p ~/.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 && cd ~/.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.
Example on Fedora:
$ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
$ vim ~/.gdbinit
set print pretty on
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
If you are getting the following error when running gdb, the `libstdcxx`
printers are already preloaded in your environment and you can remove
the duplicate import in your `~/.gdbinit` file.
RuntimeError: pretty-printer already registered: libstdc++-v6
### <a id="development-debug-gdb-run"></a> 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
Kill the running application.
(gdb) k
Continue after breakpoint.
(gdb) c
### <a id="development-debug-gdb-backtrace"></a> GDB Backtrace
If Icinga 2 aborted its operation abnormally, generate a backtrace.
(gdb) bt
(gdb) bt full
>**Tip**
>
> If you're opening an issue at [https://dev.icinga.org] make sure
> to attach as much detail as possible.
### <a id="development-debug-gdb-backtrace-stepping"></a> GDB Backtrace Stepping
Identifying the problem may require stepping into the backtrace, analysing
the current scope, attributes, and possible unmet requirements. `p` prints
the value of the selected variable or function call result.
(gdb) up
(gdb) down
(gdb) p checkable
(gdb) p checkable.px->m_Name
### <a id="development-debug-gdb-breakpoint"></a> GDB Breakpoints
To set a breakpoint to a specific function call, or file specific line.
(gdb) b checkable.cpp:125
(gdb) b icinga::Checkable::SetEnablePerfdata
GDB will ask about loading the required symbols later, select `yes` instead
of `no`.
Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
afterwards.
(gdb) run
(gdb) c
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<void (icinga::String const&)> 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"}}

View File

@ -1430,7 +1430,7 @@ Rephrased: If the parent service object changes into the `Warning` state, this
dependency will fail and render all child objects (hosts or services) unreachable. dependency will fail and render all child objects (hosts or services) unreachable.
You can determine the child's reachability by querying the `is_reachable` attribute You can determine the child's reachability by querying the `is_reachable` attribute
in for example [DB IDO](18-appendix.md#schema-db-ido-extensions). in for example [DB IDO](19-apendix.md#schema-db-ido-extensions).
### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host ### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host

View File

@ -276,7 +276,7 @@ a forced service check:
### <a id="external-command-list"></a> External Command List ### <a id="external-command-list"></a> External Command List
A list of currently supported external commands can be found [here](18-appendix.md#external-commands-list-detail). A list of currently supported external commands can be found [here](19-apendix.md#external-commands-list-detail).
Detailed information on the commands and their required parameters can be found Detailed information on the commands and their required parameters can be found
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html). on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
@ -613,7 +613,7 @@ Example for PostgreSQL:
(1 Zeile) (1 Zeile)
A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](18-appendix.md#schema-db-ido). A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](19-apendix.md#schema-db-ido).
## <a id="check-result-files"></a> Check Result Files ## <a id="check-result-files"></a> Check Result Files

View File

@ -789,7 +789,7 @@ SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourcefo
and specific trap handlers passing the check results to Icinga 2. and specific trap handlers passing the check results to Icinga 2.
Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT) Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT)
documentation and the Icinga external command syntax found [here](18-appendix.md#external-commands-list-detail) documentation and the Icinga external command syntax found [here](19-apendix.md#external-commands-list-detail)
we can create generic services that can accommodate any number of hosts for a given scenario. we can create generic services that can accommodate any number of hosts for a given scenario.
#### <a id="simple-traps"></a> Simple SNMP Traps #### <a id="simple-traps"></a> Simple SNMP Traps