tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5655 from Icinga/feature/docs-attribute-value-types 

Enhance documentation with more details on value types for object attributes
This commit is contained in:
Michael Friedrich 2017-10-10 17:53:55 +02:00 committed by GitHub
parent 9a04a99400 2d8607d6b0
commit fc098ead59
8 changed files with 1393 additions and 1124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
doc/03-monitoring-basics.md
View File

@ -6,6 +6,22 @@ Keep in mind these examples are made with a Linux server. If you are
using Windows, you will need to change the services accordingly. See the [ITL reference](10-icinga-template-library.md#windows-plugins)
for further information.
## Attribute Value Types <a id="attribute-value-types"></a>
The Icinga 2 configuration uses different value types for attributes.
Type | Example
-------------------------------------------------------|---------------------------------------------------------
[Number](17-language-reference.md#numeric-literals) | `5`
[Duration](17-language-reference.md#duration-literals) | `1m`
[String](17-language-reference.md#string-literals) | `"These are notes"`
[Boolean](17-language-reference.md#boolean-literals) | `true`
[Array](17-language-reference.md#array) | `[ "value1", "value2" ]`)
[Dictionary](17-language-reference.md#dictionary) | `{ "key1" = "value1", "key2" = false }` )
It is important to use the correct value type for object attributes
as otherwise the [configuration validation](11-cli-commands.md#config-validation) will fail.
## Hosts and Services <a id="hosts-services"></a>
Icinga 2 can be used to monitor the availability of hosts and services. Hosts
@ -68,6 +84,19 @@ Services can be in any of the following states:
CRITICAL | The service is in a critical state.
UNKNOWN | The check could not determine the service's state.
### Check Result State Mapping <a id="check-result-state-mapping"></a>
[Check plugins](05-service-monitoring.md#service-monitoring-plugins) return with an exit code which is interpreted a state number.
Services map the states directly while hosts will treat `0` or `1` as `UP`
for example.
Value | Host State | Service State
------|------------|--------------
0 | Up | OK
1 | Up | Warning
2 | Down | Critical
3 | Down | Unknown
### Hard and Soft States <a id="hard-soft-states"></a>
When detecting a problem with a host/service Icinga re-checks the object a number of

2
doc/06-distributed-monitoring.md
View File

@ -747,7 +747,7 @@ configuration:
* [Puppet Module](https://github.com/Icinga/puppet-icinga2)
* [Chef Cookbook](https://github.com/Icinga/chef-icinga2)
More details can be found [here](#configuration-tools).
More details can be found [here](13-addons.md#configuration-tools).
### Top Down <a id="distributed-monitoring-top-down"></a>

204
doc/08-advanced-topics.md
View File

@ -876,98 +876,144 @@ can be used to retrieve references to other objects by name.
This allows you to access configuration and runtime object attributes. A detailed
list can be found [here](09-object-types.md#object-types).
Simple cluster example for accessing two host object states and calculating a virtual
#### Access Object Attributes at Runtime: Cluster Check <a id="access-object-attributes-at-runtime-cluster-check"></a>
This is a simple cluster example for accessing two host object states and calculating a virtual
cluster state and output:
object Host "cluster-host-01" {
check_command = "dummy"
vars.dummy_state = 2
vars.dummy_text = "This host is down."
```
object Host "cluster-host-01" {
check_command = "dummy"
vars.dummy_state = 2
vars.dummy_text = "This host is down."
}
object Host "cluster-host-02" {
check_command = "dummy"
vars.dummy_state = 0
vars.dummy_text = "This host is up."
}
object Host "cluster" {
check_command = "dummy"
vars.cluster_nodes = [ "cluster-host-01", "cluster-host-02" ]
vars.dummy_state = {{
var up_count = 0
var down_count = 0
var cluster_nodes = macro("$cluster_nodes$")
for (node in cluster_nodes) {
if (get_host(node).state > 0) {
down_count += 1
} else {
up_count += 1
}
}
object Host "cluster-host-02" {
check_command = "dummy"
vars.dummy_state = 0
vars.dummy_text = "This host is up."
if (up_count >= down_count) {
return 0 //same up as down -> UP
} else {
return 2 //something is broken
}
}}
vars.dummy_text = {{
var output = "Cluster hosts:\n"
var cluster_nodes = macro("$cluster_nodes$")
for (node in cluster_nodes) {
output += node + ": " + get_host(node).last_check_result.output + "\n"
}
object Host "cluster" {
check_command = "dummy"
vars.cluster_nodes = [ "cluster-host-01", "cluster-host-02" ]
vars.dummy_state = {{
var up_count = 0
var down_count = 0
var cluster_nodes = macro("$cluster_nodes$")
for (node in cluster_nodes) {
if (get_host(node).state > 0) {
down_count += 1
} else {
up_count += 1
}
}
if (up_count >= down_count) {
return 0 //same up as down -> UP
} else {
return 2 //something is broken
}
}}
vars.dummy_text = {{
var output = "Cluster hosts:\n"
var cluster_nodes = macro("$cluster_nodes$")
for (node in cluster_nodes) {
output += node + ": " + get_host(node).last_check_result.output + "\n"
}
return output
}}
}
return output
}}
}
```
#### Time Dependent Thresholds <a id="access-object-attributes-at-runtime-time-dependent-thresholds"></a>
The following example sets time dependent thresholds for the load check based on the current
time of the day compared to the defined time period.
object TimePeriod "backup" {
import "legacy-timeperiod"
```
object TimePeriod "backup" {
import "legacy-timeperiod"
ranges = {
monday = "02:00-03:00"
tuesday = "02:00-03:00"
wednesday = "02:00-03:00"
thursday = "02:00-03:00"
friday = "02:00-03:00"
saturday = "02:00-03:00"
sunday = "02:00-03:00"
}
ranges = {
monday = "02:00-03:00"
tuesday = "02:00-03:00"
wednesday = "02:00-03:00"
thursday = "02:00-03:00"
friday = "02:00-03:00"
saturday = "02:00-03:00"
sunday = "02:00-03:00"
}
}
object Host "webserver-with-backup" {
check_command = "hostalive"
address = "127.0.0.1"
}
object Service "webserver-backup-load" {
check_command = "load"
host_name = "webserver-with-backup"
vars.load_wload1 = {{
if (get_time_period("backup").is_inside) {
return 20
} else {
return 5
}
object Host "webserver-with-backup" {
check_command = "hostalive"
address = "127.0.0.1"
}
object Service "webserver-backup-load" {
check_command = "load"
host_name = "webserver-with-backup"
vars.load_wload1 = {{
if (get_time_period("backup").is_inside) {
return 20
} else {
return 5
}
}}
vars.load_cload1 = {{
if (get_time_period("backup").is_inside) {
return 40
} else {
return 10
}
}}
}}
vars.load_cload1 = {{
if (get_time_period("backup").is_inside) {
return 40
} else {
return 10
}
}}
}
```
## Advanced Value Types <a id="advanced-value-types"></a>
In addition to the default value types Icinga 2 also uses a few other types
to represent its internal state. The following types are exposed via the [API](12-icinga2-api.md#icinga2-api).
### CheckResult <a id="advanced-value-types-checkresult"></a>
Name | Type | Description
--------------------------|-----------------------|----------------------------------
exit\_status | Number | The exit status returned by the check execution.
output | String | The check output.
performance\_data | Array | Array of [performance data values](08-advanced-topics.md#advanced-value-types-perfdatavalue).
check\_source | String | Name of the node executing the check.
state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
command | Value | Array of command with shell-escaped arguments or command line string.
execution\_start | Timestamp | Check execution start time (as a UNIX timestamp).
execution\_end | Timestamp | Check execution end time (as a UNIX timestamp).
schedule\_start | Timestamp | Scheduled check execution start time (as a UNIX timestamp).
schedule\_end | Timestamp | Scheduled check execution end time (as a UNIX timestamp).
active | Boolean | Whether the result is from an active or passive check.
vars\_before | Dictionary | Internal attribute used for calculations.
vars\_after | Dictionary | Internal attribute used for calculations.
### PerfdataValue <a id="advanced-value-types-perfdatavalue"></a>
Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](12-icinga2-api.md#icinga2-api)).
Name | Type | Description
--------------------------|-----------------------|----------------------------------
label | String | Performance data label.
value | Number | Normalized performance data value without unit.
counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`.
unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
crit | Value | Critical threshold value.
warn | Value | Warning threshold value.
min | Value | Minimum value returned by the check.
max | Value | Maximum value returned by the check.

1977
doc/09-object-types.md
View File

File diff suppressed because it is too large Load Diff

4
doc/11-cli-commands.md
View File

@ -136,7 +136,7 @@ added.
## CLI command: Api <a id="cli-command-api"></a>
Provides the setup CLI command to enable the REST API. More details
in the [Icinga 2 API](#icinga2-api-setup) chapter.
in the [Icinga 2 API](12-icinga2-api.md#icinga2-api-setup) chapter.
```
# icinga2 api --help
@ -169,7 +169,7 @@ Icinga home page: <https://www.icinga.com/>
## CLI command: Ca <a id="cli-command-ca"></a>
List and manage incoming certificate signing requests. More details
can be found in the [signing methods](#distributed-monitoring-setup-sign-certificates-master)
can be found in the [signing methods](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master)
chapter. This CLI command is available since v2.8.
```

233
doc/12-icinga2-api.md
View File

@ -395,9 +395,9 @@ The following URL parameters are available:
Parameters | Type | Description
-----------|--------------|----------------------------
attrs | string array | **Optional.** Limits attributes in the output.
joins | string array | **Optional.** Join related object types and their attributes (`?joins=host` for the entire set, or selectively by `?joins=host.name`).
meta | string array | **Optional.** Enable meta information using `?meta=used_by` (references from other objects) and/or `?meta=location` (location information). Defaults to disabled.
attrs | Array | **Optional.** Limited attribute list in the output.
joins | Array | **Optional.** Join related object types and their attributes specified as list (`?joins=host` for the entire set, or selectively by `?joins=host.name`).
meta | Array | **Optional.** Enable meta information using `?meta=used_by` (references from other objects) and/or `?meta=location` (location information) specified as list. Defaults to disabled.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) may be provided.
@ -431,11 +431,11 @@ Each response entry in the results array contains the following attributes:
Attribute | Type | Description
-----------|------------|--------------
name | string | Full object name.
type | string | Object type.
attrs | dictionary | Object attributes (can be filtered using the URL parameter `attrs`).
joins | dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default.
meta | dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter.
name | String | Full object name.
type | String | Object type.
attrs | Dictionary | Object attributes (can be filtered using the URL parameter `attrs`).
joins | Dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default.
meta | Dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter.
#### Object Query Joins <a id="icinga2-api-config-objects-query-joins"></a>
@ -584,8 +584,8 @@ parameters need to be passed inside the JSON body:
Parameters | Type | Description
-----------|--------------|--------------------------
templates | string array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)-
attrs | dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
templates | Array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)-
attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
The object name must be specified as part of the URL path. For objects with composite names (e.g. services)
the full name (e.g. `example.localdomain!http`) must be specified.
@ -646,7 +646,7 @@ parameters need to be passed inside the JSON body:
Parameters | Type | Description
-----------|------------|---------------------------
attrs | dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
@ -689,7 +689,7 @@ request.
Parameters | Type | Description
-----------|---------|---------------
cascade | boolean | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
cascade | Boolean | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
@ -800,13 +800,13 @@ Send a `POST` request to the URL endpoint `/v1/actions/process-check-result`.
Parameter | Type | Description
------------------|--------------|--------------
exit\_status | integer | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
plugin\_output | string | **Required.** The plugins main output. Does **not** contain the performance data.
performance\_data | string array | **Optional.** The performance data.
check\_command | string array | **Optional.** The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument.
check\_source | string | **Optional.** Usually the name of the `command_endpoint`
execution\_start | timestamp | **Optional.** The timestamp where a script/process started its execution.
execution\_end | timestamp | **Optional.** The timestamp where a script/process ended its execution. This timestamp is used in features to determine e.g. the metric timestamp.
exit\_status | Number | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
plugin\_output | String | **Required.** The plugins main output. Does **not** contain the performance data.
performance\_data | Array | **Optional.** The performance data.
check\_command | Array | **Optional.** The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument.
check\_source | String | **Optional.** Usually the name of the `command_endpoint`
execution\_start | Timestamp | **Optional.** The timestamp where a script/process started its execution.
execution\_end | Timestamp | **Optional.** The timestamp where a script/process ended its execution. This timestamp is used in features to determine e.g. the metric timestamp.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -839,8 +839,8 @@ Send a `POST` request to the URL endpoint `/v1/actions/reschedule-check`.
Parameter | Type | Description
-------------|-----------|--------------
next\_check | timestamp | **Optional.** The next check will be run at this time. If omitted, the current time is used.
force\_check | boolean | **Optional.** Defaults to `false`. If enabled, the checks are executed regardless of time period restrictions and checks being disabled per object or on a global basis.
next\_check | Timestamp | **Optional.** The next check will be run at this time. If omitted, the current time is used.
force\_check | Boolean | **Optional.** Defaults to `false`. If enabled, the checks are executed regardless of time period restrictions and checks being disabled per object or on a global basis.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -870,9 +870,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/send-custom-notification`
Parameter | Type | Description
----------|---------|--------------
author | string | **Required.** Name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty.
force | boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.
author | String | **Required.** Name of the author, may be empty.
comment | String | **Required.** Comment text, may be empty.
force | Boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -905,7 +905,7 @@ Send a `POST` request to the URL endpoint `/v1/actions/delay-notification`.
Parameter | Type | Description
----------|-----------|--------------
timestamp | timestamp | **Required.** Delay notifications until this timestamp.
timestamp | Timestamp | **Required.** Delay notifications until this timestamp.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -936,12 +936,12 @@ Send a `POST` request to the URL endpoint `/v1/actions/acknowledge-problem`.
Parameter | Type | Description
---------------------|-----------|--------------
author | string | **Required.** Name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty.
expiry | timestamp | **Optional.** Whether the acknowledgement will be removed at the timestamp.
sticky | boolean | **Optional.** Whether the acknowledgement will be set until the service or host fully recovers. Defaults to `false`.
notify | boolean | **Optional.** Whether a notification of the `Acknowledgement` type will be sent. Defaults to `false`.
persistent | boolean | **Optional.** When the comment is of type `Acknowledgement` and this is set to `true`, the comment will remain after the acknowledgement recovers or expires. Defaults to `false`.
author | String | **Required.** Name of the author, may be empty.
comment | String | **Required.** Comment text, may be empty.
expiry | Timestamp | **Optional.** Whether the acknowledgement will be removed at the timestamp.
sticky | Boolean | **Optional.** Whether the acknowledgement will be set until the service or host fully recovers. Defaults to `false`.
notify | Boolean | **Optional.** Whether a notification of the `Acknowledgement` type will be sent. Defaults to `false`.
persistent | Boolean | **Optional.** When the comment is of type `Acknowledgement` and this is set to `true`, the comment will remain after the acknowledgement recovers or expires. Defaults to `false`.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -1070,14 +1070,14 @@ Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
Parameter | Type | Description
--------------|-----------|--------------
author | string | **Required.** Name of the author.
comment | string | **Required.** Comment text.
start\_time | timestamp | **Required.** Timestamp marking the beginning of the downtime.
end\_time | timestamp | **Required.** Timestamp marking the end of the downtime.
fixed | boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
duration | integer | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
trigger\_name | string | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
child\_options | integer | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`.
author | String | **Required.** Name of the author.
comment | String | **Required.** Comment text.
start\_time | Timestamp | **Required.** Timestamp marking the beginning of the downtime.
end\_time | Timestamp | **Required.** Timestamp marking the end of the downtime.
fixed | Boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
duration | Number | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
trigger\_name | String | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
child\_options | Number | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -1209,7 +1209,7 @@ Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
Parameter | Type | Description
--------------|-----------|--------------
cn | string | **Required.** The host's common name for which the ticket should be geenerated.
cn | String | **Required.** The host's common name for which the ticket should be geenerated.
Example:
@ -1233,9 +1233,9 @@ The following parameters need to be specified (either as URL parameters or in a
Parameter | Type | Description
-----------|--------------|-------------
types | string array | **Required.** Event type(s). Multiple types as URL parameters are supported.
queue | string | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter.
filter | string | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters).
types | Array | **Required.** Event type(s). Multiple types as URL parameters are supported.
queue | String | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter.
filter | String | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters).
### Event Stream Types <a id="icinga2-api-event-streams-types"></a>
@ -1262,6 +1262,131 @@ Example for all downtime events:
&types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
#### <a id="icinga2-api-event-streams-type-checkresult"></a> Event Stream Type: CheckResult
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `CheckResult`.
timestamp | Timestamp | Unix timestamp when the event happened.
host | String | [Host](09-object-types.md#objecttype-host) name.
service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host check result.
check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
#### <a id="icinga2-api-event-streams-type-statechange"></a> Event Stream Type: StateChange
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `StateChange`.
timestamp | Timestamp | Unix timestamp when the event happened.
host | String | [Host](09-object-types.md#objecttype-host) name.
service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host state change.
state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
#### <a id="icinga2-api-event-streams-type-notification"></a> Event Stream Type: Notification
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `Notification`.
timestamp | Timestamp | Unix timestamp when the event happened.
host | String | [Host](09-object-types.md#objecttype-host) name.
service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host notification.
users | Array | List of notified [user](09-object-types.md#objecttype-user) names.
notification\_type | String | [$notification.type$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
author | String | [$notification.author$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
text | String | [$notification.comment$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
#### <a id="icinga2-api-event-streams-type-flapping"></a> Event Stream Type: Flapping
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `Flapping`.
timestamp | Timestamp | Unix timestamp when the event happened.
host | String | [Host](09-object-types.md#objecttype-host) name.
service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host flapping event.
state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
is\_flapping | Boolean | Whether this object is flapping.
#### <a id="icinga2-api-event-streams-type-acknowledgementset"></a> Event Stream Type: AcknowledgementSet
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `AcknowledgementSet`.
timestamp | Timestamp | Unix timestamp when the event happened.
host | String | [Host](09-object-types.md#objecttype-host) name.
service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host acknowledgement.
state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
author | String | Acknowledgement author set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
comment | String | Acknowledgement comment set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
acknowledgement\_type | Number | 0 = None, 1 = Normal, 2 = Sticky. `sticky` can be set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
notify | Boolean | Notifications were enabled via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
expiry | Timestamp | Acknowledgement expire time set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
#### <a id="icinga2-api-event-streams-type-acknowledgementcleared"></a> Event Stream Type: AcknowledgementCleared
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `AcknowledgementCleared`.
timestamp | Timestamp | Unix timestamp when the event happened.
host | String | [Host](09-object-types.md#objecttype-host) name.
service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host acknowledgement.
state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
#### <a id="icinga2-api-event-streams-type-commentadded"></a> Event Stream Type: CommentAdded
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `CommentAdded`.
timestamp | Timestamp | Unix timestamp when the event happened.
comment | Dictionary | Serialized [Comment](09-object-types.md#objecttype-comment) object.
#### <a id="icinga2-api-event-streams-type-commentremoved"></a> Event Stream Type: CommentRemoved
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `CommentRemoved`.
timestamp | Timestamp | Unix timestamp when the event happened.
comment | Dictionary | Serialized [Comment](09-object-types.md#objecttype-comment) object.
#### <a id="icinga2-api-event-streams-type-downtimeadded"></a> Event Stream Type: DowntimeAdded
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `DowntimeAdded`.
timestamp | Timestamp | Unix timestamp when the event happened.
downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
#### <a id="icinga2-api-event-streams-type-downtimeremoved"></a> Event Stream Type: DowntimeRemoved
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `DowntimeRemoved`.
timestamp | Timestamp | Unix timestamp when the event happened.
downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
#### <a id="icinga2-api-event-streams-type-downtimestarted"></a> Event Stream Type: DowntimeStarted
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `DowntimeStarted`.
timestamp | Timestamp | Unix timestamp when the event happened.
downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
#### <a id="icinga2-api-event-streams-type-downtimetriggered"></a> Event Stream Type: DowntimeTriggered
Name | Type | Description
--------------|---------------|--------------------------
type | String | Event type `DowntimeTriggered`.
timestamp | Timestamp | Unix timestamp when the event happened.
downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
### Event Stream Filter <a id="icinga2-api-event-streams-filter"></a>
@ -1589,14 +1714,14 @@ endpoint `/v1/types`.
Each response entry in the results array contains the following attributes:
Attribute | Type | Description
---------------|--------------|---------------------
name | string | The type name.
plural_name | string | The plural type name.
fields | dictionary | Available fields including details on e.g. the type and attribute accessibility.
abstract | boolean | Whether objects can be instantiated for this type.
base | boolean | The base type (e.g. `Service` inherits fields and prototype methods from `Checkable`).
prototype_keys | string array | Available prototype methods.
Attribute | Type | Description
----------------|--------------|---------------------
name | String | The type name.
plural\_name | String | The plural type name.
fields | Dictionary | Available fields including details on e.g. the type and attribute accessibility.
abstract | Boolean | Whether objects can be instantiated for this type.
base | Boolean | The base type (e.g. `Service` inherits fields and prototype methods from `Checkable`).
prototype\_keys | Array | Available prototype methods.
In order to view a specific configuration object type specify its name inside the URL path:
@ -1641,9 +1766,9 @@ The following parameters need to be specified (either as URL parameters or in a
Parameter | Type | Description
-----------|--------------|-------------
session | string | **Optional.** The session ID. Ideally this should be a GUID or some other unique identifier.
command | string | **Required.** Command expression for execution or auto-completion.
sandboxed | number | **Optional.** Whether runtime changes are allowed or forbidden. Defaults to disabled.
session | String | **Optional.** The session ID. Ideally this should be a GUID or some other unique identifier.
command | String | **Required.** Command expression for execution or auto-completion.
sandboxed | Number | **Optional.** Whether runtime changes are allowed or forbidden. Defaults to disabled.
The [API permission](12-icinga2-api.md#icinga2-api-permissions) `console` is required for executing
expressions.

58
doc/14-features.md
View File

@ -267,8 +267,66 @@ You can enable the feature using
By default the [InfluxdbWriter](09-object-types.md#objecttype-influxdbwriter) feature
expects the InfluxDB daemon to listen at `127.0.0.1` on port `8086`.
Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
object will automatically add a `metric` tag to each data point. This correlates to the
perfdata label. Fields (value, warn, crit, min, max) are created from data if available
and the configuration allows it. If a value associated with a tag is not able to be
resolved, it will be dropped and not sent to the target host.
Backslashes are allowed in tag keys, tag values and field keys, however they are also
escape characters when followed by a space or comma, but cannot be escaped themselves.
As a result all trailling slashes in these fields are replaced with an underscore. This
predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
The database is assumed to exist so this object will make no attempt to create it currently.
More configuration details can be found [here](09-object-types.md#objecttype-influxdbwriter).
#### Instance Tagging <a id="influxdb-writer-instance-tags"></a>
Consider the following service check:
```
apply Service "disk" for (disk => attributes in host.vars.disks) {
import "generic-service"
check_command = "disk"
display_name = "Disk " + disk
vars.disk_partitions = disk
assign where host.vars.disks
}
```
This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
with a host. What would be useful is to have the data points tagged with the specific instance
for that check. This would allow you to query time series data for a check on a host and for a
specific instance e.g. /dev/sda. To do this quite simply add the instance to the service variables:
```
apply Service "disk" for (disk => attributes in host.vars.disks) {
...
vars.instance = disk
...
}
```
Then modify your writer configuration to add this tag to your data points if the instance variable
is associated with the service:
```
object InfluxdbWriter "influxdb" {
...
service_template = {
measurement = "$service.check_command$"
tags = {
hostname = "$host.name$"
service = "$service.name$"
instance = "$service.vars.instance$"
}
}
...
}
```
### Elastic Stack Integration <a id="elastic-stack-integration"></a>
[Icingabeat](https://github.com/icinga/icingabeat) is an Elastic Beat that fetches data

10
etc/icinga2/conf.d/timeperiods.conf
View File

@ -1,13 +1,9 @@
/**
* Sample timeperiods for Icinga 2 requiring
* 'legacy-timeperiod' template from the Icinga
* Template Library (ITL).
* Sample timeperiods for Icinga 2.
* Check the documentation for details.
*/
object TimePeriod "24x7" {
import "legacy-timeperiod"
display_name = "Icinga 2 24x7 TimePeriod"
ranges = {
"monday" = "00:00-24:00"
@ -21,8 +17,6 @@ object TimePeriod "24x7" {
}
object TimePeriod "9to5" {
import "legacy-timeperiod"
display_name = "Icinga 2 9to5 TimePeriod"
ranges = {
"monday" = "09:00-17:00"
@ -34,8 +28,6 @@ object TimePeriod "9to5" {
}
object TimePeriod "never" {
import "legacy-timeperiod"
display_name = "Icinga 2 never TimePeriod"
ranges = {
}