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

Enhance documentation with more details on value types for object attributes

doc/03-monitoring-basics.md

@@ -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

doc/06-distributed-monitoring.md

@@ -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>
 

doc/08-advanced-topics.md

@@ -876,9 +876,12 @@ 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
@@ -926,11 +929,14 @@ cluster state and 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"
 
@@ -969,5 +975,45 @@ time of the day compared to the defined time period.
     }
   }}
 }
+```
+
+
+## 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.
 
 

doc/11-cli-commands.md

@@ -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.
 
 ```

doc/12-icinga2-api.md

@@ -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>
 
@@ -1590,13 +1715,13 @@ 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.
+  ----------------|--------------|---------------------
+  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.

doc/14-features.md

@@ -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

etc/icinga2/conf.d/timeperiods.conf

@@ -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 = {
   }