1 # Icinga 2 Features <a id="icinga2-features"></a>
3 ## Logging <a id="logging"></a>
5 Icinga 2 supports three different types of logging:
8 * Syslog (on Linux/UNIX)
9 * Console logging (`STDOUT` on tty)
11 You can enable additional loggers using the `icinga2 feature enable`
12 and `icinga2 feature disable` commands to configure loggers:
15 ---------|------------
16 debuglog | Debug log (path: `/var/log/icinga2/debug.log`, severity: `debug` or higher)
17 mainlog | Main log (path: `/var/log/icinga2/icinga2.log`, severity: `information` or higher)
18 syslog | Syslog (severity: `warning` or higher)
20 By default file the `mainlog` feature is enabled. When running Icinga 2
21 on a terminal log messages with severity `information` or higher are
22 written to the console.
24 Packages will install a configuration file for logrotate on supported
25 platforms. This configuration ensures that the `icinga2.log`, `error.log` and
26 `debug.log` files are rotated on a daily basis.
28 ## DB IDO <a id="db-ido"></a>
30 The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
31 configuration and status information into a database. The IDO database is used
34 Details on the installation can be found in the [Configuring DB IDO](02-getting-started.md#configuring-db-ido-mysql)
35 chapter. Details on the configuration can be found in the
36 [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and
37 [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection)
38 object configuration documentation.
39 The DB IDO feature supports [High Availability](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) in
42 The following example query checks the health of the current Icinga 2 instance
43 writing its current status to the DB IDO backend table `icinga_programstatus`
44 every 10 seconds. By default it checks 60 seconds into the past which is a reasonable
45 amount of time -- adjust it for your requirements. If the condition is not met,
46 the query returns an empty result.
50 > Use [check plugins](05-service-monitoring.md#service-monitoring-plugins) to monitor the backend.
52 Replace the `default` string with your instance name if different.
56 # mysql -u root -p icinga -e "SELECT status_update_time FROM icinga_programstatus ps
57 JOIN icinga_instances i ON ps.instance_id=i.instance_id
58 WHERE (UNIX_TIMESTAMP(ps.status_update_time) > UNIX_TIMESTAMP(NOW())-60)
59 AND i.instance_name='default';"
61 +---------------------+
62 | status_update_time |
63 +---------------------+
64 | 2014-05-29 14:29:56 |
65 +---------------------+
68 Example for PostgreSQL:
70 # export PGPASSWORD=icinga; psql -U icinga -d icinga -c "SELECT ps.status_update_time FROM icinga_programstatus AS ps
71 JOIN icinga_instances AS i ON ps.instance_id=i.instance_id
72 WHERE ((SELECT extract(epoch from status_update_time) FROM icinga_programstatus) > (SELECT extract(epoch from now())-60))
73 AND i.instance_name='default'";
76 ------------------------
77 2014-05-29 15:11:38+02
81 A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido).
84 ## External Commands <a id="external-commands"></a>
86 Icinga 2 provides an external command pipe for processing commands
87 triggering specific actions (for example rescheduling a service check
88 through the web interface).
90 In order to enable the `ExternalCommandListener` configuration use the
91 following command and restart Icinga 2 afterwards:
93 # icinga2 feature enable command
95 Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
96 using the default configuration.
98 Web interfaces and other Icinga addons are able to send commands to
99 Icinga 2 through the external command pipe, for example for rescheduling
100 a forced service check:
102 # /bin/echo "[`date +%s`] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;`date +%s`" >> /var/run/icinga2/cmd/icinga2.cmd
104 # tail -f /var/log/messages
106 Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
107 Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
109 A list of currently supported external commands can be found [here](23-appendix.md#external-commands-list-detail).
111 Detailed information on the commands and their required parameters can be found
112 on the [Icinga 1.x documentation](https://docs.icinga.com/latest/en/extcommands2.html).
114 ## Performance Data <a id="performance-data"></a>
116 When a host or service check is executed plugins should provide so-called
117 `performance data`. Next to that additional check performance data
118 can be fetched using Icinga 2 runtime macros such as the check latency
119 or the current service state (or additional custom attributes).
121 The performance data can be passed to external applications which aggregate and
122 store them in their backends. These tools usually generate graphs for historical
123 reporting and trending.
125 Well-known addons processing Icinga performance data are [PNP4Nagios](13-addons.md#addons-graphing-pnp),
126 [Graphite](13-addons.md#addons-graphing-graphite) or [OpenTSDB](14-features.md#opentsdb-writer).
128 ### Writing Performance Data Files <a id="writing-performance-data-files"></a>
130 PNP4Nagios and Graphios use performance data collector daemons to fetch
131 the current performance files for their backend updates.
133 Therefore the Icinga 2 [PerfdataWriter](09-object-types.md#objecttype-perfdatawriter)
134 feature allows you to define the output template format for host and services helped
135 with Icinga 2 runtime vars.
137 host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
138 service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
140 The default templates are already provided with the Icinga 2 feature configuration
141 which can be enabled using
143 # icinga2 feature enable perfdata
145 By default all performance data files are rotated in a 15 seconds interval into
146 the `/var/spool/icinga2/perfdata/` directory as `host-perfdata.<timestamp>` and
147 `service-perfdata.<timestamp>`.
148 External collectors need to parse the rotated performance data files and then
149 remove the processed files.
151 ### Graphite Carbon Cache Writer <a id="graphite-carbon-cache-writer"></a>
153 While there are some [Graphite](13-addons.md#addons-graphing-graphite)
154 collector scripts and daemons like Graphios available for Icinga 1.x it's more
155 reasonable to directly process the check and plugin performance
156 in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
157 write them to the defined Graphite Carbon daemon tcp socket.
159 You can enable the feature using
161 # icinga2 feature enable graphite
163 By default the [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) feature
164 expects the Graphite Carbon Cache to listen at `127.0.0.1` on TCP port `2003`.
166 #### Current Graphite Schema <a id="graphite-carbon-cache-writer-schema"></a>
168 The current naming schema is defined as follows. The [Icinga Web 2 Graphite module](https://github.com/icinga/icingaweb2-module-graphite)
169 depends on this schema.
171 The default prefix for hosts and services is configured using
172 [runtime macros](03-monitoring-basics.md#runtime-macros)like this:
174 icinga2.$host.name$.host.$host.check_command$
175 icinga2.$host.name$.services.$service.name$.$service.check_command$
177 You can customize the prefix name by using the `host_name_template` and
178 `service_name_template` configuration attributes.
180 The additional levels will allow fine granular filters and also template
181 capabilities, e.g. by using the check command `disk` for specific
182 graph templates in web applications rendering the Graphite data.
184 The following characters are escaped in prefix labels:
186 Character | Escaped character
187 --------------|--------------------------
193 Metric values are stored like this:
195 <prefix>.perfdata.<perfdata-label>.value
197 The following characters are escaped in perfdata labels:
199 Character | Escaped character
200 --------------|--------------------------
206 Note that perfdata labels may contain dots (`.`) allowing to
207 add more subsequent levels inside the Graphite tree.
208 `::` adds support for [multi performance labels](http://my-plugin.de/wiki/projects/check_multi/configuration/performance)
209 and is therefore replaced by `.`.
211 By enabling `enable_send_thresholds` Icinga 2 automatically adds the following threshold metrics:
213 <prefix>.perfdata.<perfdata-label>.min
214 <prefix>.perfdata.<perfdata-label>.max
215 <prefix>.perfdata.<perfdata-label>.warn
216 <prefix>.perfdata.<perfdata-label>.crit
218 By enabling `enable_send_metadata` Icinga 2 automatically adds the following metadata metrics:
220 <prefix>.metadata.current_attempt
221 <prefix>.metadata.downtime_depth
222 <prefix>.metadata.acknowledgement
223 <prefix>.metadata.execution_time
224 <prefix>.metadata.latency
225 <prefix>.metadata.max_check_attempts
226 <prefix>.metadata.reachable
227 <prefix>.metadata.state
228 <prefix>.metadata.state_type
230 Metadata metric overview:
233 -------------------|------------------------------------------
234 current_attempt | current check attempt
235 max_check_attempts | maximum check attempts until the hard state is reached
236 reachable | checked object is reachable
237 downtime_depth | number of downtimes this object is in
238 acknowledgement | whether the object is acknowledged or not
239 execution_time | check execution time
240 latency | check latency
241 state | current state of the checked object
242 state_type | 0=SOFT, 1=HARD state
244 The following example illustrates how to configure the storage schemas for Graphite Carbon
248 # intervals like PNP4Nagios uses them per default
250 retentions = 1m:2d,5m:10d,30m:90d,360m:4y
253 ### InfluxDB Writer <a id="influxdb-writer"></a>
255 Once there are new metrics available, Icinga 2 will directly write them to the
256 defined InfluxDB HTTP API.
258 You can enable the feature using
260 # icinga2 feature enable influxdb
262 By default the [InfluxdbWriter](09-object-types.md#objecttype-influxdbwriter) feature
263 expects the InfluxDB daemon to listen at `127.0.0.1` on port `8086`.
265 More configuration details can be found [here](09-object-types.md#objecttype-influxdbwriter).
267 ### Graylog Integration <a id="graylog-integration"></a>
269 #### GELF Writer <a id="gelfwriter"></a>
271 The `Graylog Extended Log Format` (short: [GELF](http://docs.graylog.org/en/latest/pages/gelf.html))
272 can be used to send application logs directly to a TCP socket.
274 While it has been specified by the [Graylog](https://www.graylog.org) project as their
275 [input resource standard](http://docs.graylog.org/en/latest/pages/sending_data.html), other tools such as
276 [Logstash](https://www.elastic.co/products/logstash) also support `GELF` as
277 [input type](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-gelf.html).
279 You can enable the feature using
281 # icinga2 feature enable gelf
283 By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`.
284 The default `source` attribute is set to `icinga2`. You can customize that for your needs if required.
286 Currently these events are processed:
291 ### Elastic Stack Integration <a id="elastic-stack-integration"></a>
293 [Icingabeat](https://github.com/icinga/icingabeat) is an Elastic Beat that fetches data
294 from the Icinga 2 API and sends it either directly to Elasticsearch or Logstash.
296 More integrations in development:
297 * [Logstash output](https://github.com/Icinga/logstash-output-icinga) for the Icinga 2 API.
298 * [Logstash Grok Pattern](https://github.com/Icinga/logstash-grok-pattern) for Icinga 2 logs.
300 ### OpenTSDB Writer <a id="opentsdb-writer"></a>
302 While there are some OpenTSDB collector scripts and daemons like tcollector available for
303 Icinga 1.x it's more reasonable to directly process the check and plugin performance
304 in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
305 write them to the defined TSDB TCP socket.
307 You can enable the feature using
309 # icinga2 feature enable opentsdb
311 By default the `OpenTsdbWriter` object expects the TSD to listen at
312 `127.0.0.1` on port `4242`.
314 The current naming schema is
316 icinga.host.<metricname>
317 icinga.service.<servicename>.<metricname>
319 for host and service checks. The tag host is always applied.
321 To make sure Icinga 2 writes a valid metric into OpenTSDB some characters are replaced
322 with `_` in the target name:
326 The resulting name in OpenTSDB might look like:
328 www-01 / http-cert / response time
329 icinga.http_cert.response_time
331 In addition to the performance data retrieved from the check plugin, Icinga 2 sends
332 internal check statistic data to OpenTSDB:
335 -------------------|------------------------------------------
336 current_attempt | current check attempt
337 max_check_attempts | maximum check attempts until the hard state is reached
338 reachable | checked object is reachable
339 downtime_depth | number of downtimes this object is in
340 acknowledgement | whether the object is acknowledged or not
341 execution_time | check execution time
342 latency | check latency
343 state | current state of the checked object
344 state_type | 0=SOFT, 1=HARD state
346 While reachable, state and state_type are metrics for the host or service the
347 other metrics follow the current naming schema
349 icinga.check.<metricname>
351 with the following tags
354 --------|------------------------------------------
355 type | the check type, one of [host, service]
356 host | hostname, the check ran on
357 service | the service name (if type=service)
361 > You might want to set the tsd.core.auto_create_metrics setting to `true`
362 > in your opentsdb.conf configuration file.
365 ## Livestatus <a id="setting-up-livestatus"></a>
367 The [MK Livestatus](https://mathias-kettner.de/checkmk_livestatus.html) project
368 implements a query protocol that lets users query their Icinga instance for
369 status information. It can also be used to send commands.
373 > Only install the Livestatus feature if your web interface or addon requires
374 > you to do so (for example, [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2)).
375 > Icinga Classic UI 1.x and Icinga Web 1.x do not use Livestatus as backend.
377 The Livestatus component that is distributed as part of Icinga 2 is a
378 re-implementation of the Livestatus protocol which is compatible with MK
381 Details on the available tables and attributes with Icinga 2 can be found
382 in the [Livestatus Schema](23-appendix.md#schema-livestatus) section.
384 You can enable Livestatus using icinga2 feature enable:
386 # icinga2 feature enable livestatus
388 After that you will have to restart Icinga 2:
390 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
392 # systemctl restart icinga2
394 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
396 # service icinga2 restart
398 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
400 In order for queries and commands to work you will need to add your query user
401 (e.g. your web server) to the `icingacmd` group:
403 # usermod -a -G icingacmd www-data
405 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
406 `nagios` if you're using Debian.
408 Change `www-data` to the user you're using to run queries.
410 In order to use the historical tables provided by the livestatus feature (for example, the
411 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
412 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
413 `compat_log_path` configuration attribute.
415 # icinga2 feature enable compatlog
418 ### Livestatus Sockets <a id="livestatus-sockets"></a>
420 Other to the Icinga 1.x Addon, Icinga 2 supports two socket types
422 * Unix socket (default)
425 Details on the configuration can be found in the [LivestatusListener](09-object-types.md#objecttype-livestatuslistener)
426 object configuration.
428 ### Livestatus GET Queries <a id="livestatus-get-queries"></a>
432 > All Livestatus queries require an additional empty line as query end identifier.
433 > The `nc` tool (`netcat`) provides the `-U` parameter to communicate using
436 There also is a Perl module available in CPAN for accessing the Livestatus socket
437 programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/)
440 Example using the unix socket:
442 # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus
444 Example using the tcp socket listening on port `6558`:
446 # echo -e 'GET services\n' | netcat 127.0.0.1 6558
448 # cat servicegroups <<EOF
453 (cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
456 ### Livestatus COMMAND Queries <a id="livestatus-command-queries"></a>
458 A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail)
460 $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
463 ### Livestatus Filters <a id="livestatus-filters"></a>
467 Operator | Negate | Description
468 ----------|------------------------
471 =~ | !=~ | Equality ignoring case
472 ~~ | !~~ | Regex ignoring case
475 <= | | Less than or equal
476 >= | | Greater than or equal
479 ### Livestatus Stats <a id="livestatus-stats"></a>
481 Schema: "Stats: aggregatefunction aggregateattribute"
483 Aggregate Function | Description
484 -------------------|--------------
489 std | standard deviation
490 suminv | sum (1 / value)
491 avginv | suminv / count
492 count | ordinary default for any stats query if not aggregate function defined
497 Filter: has_been_checked = 1
498 Filter: check_type = 0
499 Stats: sum execution_time
501 Stats: sum percent_state_change
502 Stats: min execution_time
504 Stats: min percent_state_change
505 Stats: max execution_time
507 Stats: max percent_state_change
509 ResponseHeader: fixed16
511 ### Livestatus Output <a id="livestatus-output"></a>
515 CSV output uses two levels of array separators: The members array separator
516 is a comma (1st level) while extra info and host|service relation separator
517 is a pipe (2nd level).
519 Separators can be set using ASCII codes like:
521 Separators: 10 59 44 124
527 ### Livestatus Error Codes <a id="livestatus-error-codes"></a>
530 ----------|--------------
532 404 | Table does not exist
533 452 | Exception on query
535 ### Livestatus Tables <a id="livestatus-tables"></a>
537 Table | Join |Description
538 --------------|-----------|----------------------------
539 hosts | | host config and status attributes, services counter
540 hostgroups | | hostgroup config, status attributes and host/service counters
541 services | hosts | service config and status attributes
542 servicegroups | | servicegroup config, status attributes and service counters
543 contacts | | contact config and status attributes
544 contactgroups | | contact config, members
545 commands | | command name and line
546 status | | programstatus, config and stats
547 comments | services | status attributes
548 downtimes | services | status attributes
549 timeperiods | | name and is inside flag
550 endpoints | | config and status attributes
551 log | services, hosts, contacts, commands | parses [compatlog](09-object-types.md#objecttype-compatlogger) and shows log attributes
552 statehist | hosts, services | parses [compatlog](09-object-types.md#objecttype-compatlogger) and aggregates state change attributes
553 hostsbygroup | hostgroups | host attributes grouped by hostgroup and its attributes
554 servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes
555 servicesbyhostgroup | hostgroups | service attributes grouped by hostgroup and its attributes
557 The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
559 A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus).
562 ## Status Data Files <a id="status-data"></a>
564 Icinga 1.x writes object configuration data and status data in a cyclic
565 interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
566 the `StatusDataWriter` object which dumps all configuration objects and
567 status updates in a regular interval.
569 # icinga2 feature enable statusdata
571 Icinga 1.x Classic UI requires this data set as part of its backend.
575 > If you are not using any web interface or addon which uses these files,
576 > you can safely disable this feature.
579 ## Compat Log Files <a id="compat-logging"></a>
581 The Icinga 1.x log format is considered being the `Compat Log`
582 in Icinga 2 provided with the `CompatLogger` object.
584 These logs are not only used for informational representation in
585 external web interfaces parsing the logs, but also to generate
586 SLA reports and trends in Icinga 1.x Classic UI. Furthermore the
587 [Livestatus](14-features.md#setting-up-livestatus) feature uses these logs for answering queries to
590 The `CompatLogger` object can be enabled with
592 # icinga2 feature enable compatlog
594 By default, the Icinga 1.x log file called `icinga.log` is located
595 in `/var/log/icinga2/compat`. Rotated log files are moved into
596 `var/log/icinga2/compat/archives`.
598 The format cannot be changed without breaking compatibility to
599 existing log parsers.
601 # tail -f /var/log/icinga2/compat/icinga.log
603 [1382115688] LOG ROTATION: HOURLY
604 [1382115688] LOG VERSION: 2.0
605 [1382115688] HOST STATE: CURRENT;localhost;UP;HARD;1;
606 [1382115688] SERVICE STATE: CURRENT;localhost;disk;WARNING;HARD;1;
607 [1382115688] SERVICE STATE: CURRENT;localhost;http;OK;HARD;1;
608 [1382115688] SERVICE STATE: CURRENT;localhost;load;OK;HARD;1;
609 [1382115688] SERVICE STATE: CURRENT;localhost;ping4;OK;HARD;1;
610 [1382115688] SERVICE STATE: CURRENT;localhost;ping6;OK;HARD;1;
611 [1382115688] SERVICE STATE: CURRENT;localhost;processes;WARNING;HARD;1;
612 [1382115688] SERVICE STATE: CURRENT;localhost;ssh;OK;HARD;1;
613 [1382115688] SERVICE STATE: CURRENT;localhost;users;OK;HARD;1;
614 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;disk;1382115705
615 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;http;1382115705
616 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;load;1382115705
617 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382115705
618 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ping6;1382115705
619 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;processes;1382115705
620 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ssh;1382115705
621 [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;users;1382115705
622 [1382115731] EXTERNAL COMMAND: PROCESS_SERVICE_CHECK_RESULT;localhost;ping6;2;critical test|
623 [1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test
626 ## Check Result Files <a id="check-result-files"></a>
628 Icinga 1.x writes its check result files to a temporary spool directory
629 where they are processed in a regular interval.
630 While this is extremely inefficient in performance regards it has been
631 rendered useful for passing passive check results directly into Icinga 1.x
632 skipping the external command pipe.
634 Several clustered/distributed environments and check-aggregation addons
635 use that method. In order to support step-by-step migration of these
636 environments, Icinga 2 supports the `CheckResultReader` object.
638 There is no feature configuration available, but it must be defined
639 on-demand in your Icinga 2 objects configuration.
641 object CheckResultReader "reader" {
642 spool_dir = "/data/check-results"