mirror of
https://github.com/Icinga/icinga2.git
synced 2025-04-08 17:05:25 +02:00
Documentation: Move Debug from Troubleshooting into a separate section
This commit is contained in:
Michael Friedrich
parent
2ae06b7a52
commit
06e6da081a
@ -16,7 +16,7 @@ re-implementation of the Livestatus protocol which is compatible with MK
|
||||
Livestatus.
|
||||
|
||||
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:
|
||||
|
||||
@ -92,7 +92,7 @@ Example using the tcp socket listening on port `6558`:
|
||||
|
||||
### <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
|
||||
|
||||
@ -190,5 +190,5 @@ Default separators.
|
||||
|
||||
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).
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
* Provide complete configuration snippets explaining your problem in detail
|
||||
* Provide complete logs targetting your problem
|
||||
* 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
|
||||
|
||||
@ -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 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
|
||||
|
||||
|
||||
## <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
207
doc/18-debug.md
Normal 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"}}
|
||||
@ -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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@ -276,7 +276,7 @@ a forced service check:
|
||||
|
||||
### <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
|
||||
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
|
||||
@ -613,7 +613,7 @@ Example for PostgreSQL:
|
||||
(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
|
||||
|
||||
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
#### <a id="simple-traps"></a> Simple SNMP Traps
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user