Docs: Add new runtime checkable attributes and explain severity in tech concepts

fixes #7100

diff --git a/doc/09-object-types.md b/doc/09-object-types.md
index 8c1eb59cc270f460a7def297cdbc4b6b971fcd66..52dcd729ce1cf075880cc46283d6c07108b390b9 100644 (file)
--- a/doc/09-object-types.md
+++ b/doc/09-object-types.md
@@ -441,6 +441,11 @@ Runtime Attributes:
   last\_hard\_state         | Number                | The last hard state (0 = UP, 1 = DOWN).
   last\_state\_up           | Timestamp             | When the last UP state occurred (as a UNIX timestamp).
   last\_state\_down         | Timestamp             | When the last DOWN state occurred (as a UNIX timestamp).
+  last\_state\_unreachable  | Timestamp             | When the host was unreachable the last time (as a UNIX timestamp).
+  previous\_state\_change   | Timestamp             | Previous timestamp of `last_state_change` before processing a new check result.
+  severity                  | Number                | [Severity](19-technical-concepts.md#technical-concepts-checks-severity) calculated value.
+  problem                   | Boolean               | Whether the host is considered in a problem state type (NOT-UP).
+  handled                   | Boolean               | Whether the host problem is handled (downtime or acknowledgement).
 
 
 
@@ -792,7 +797,7 @@ Runtime Attributes:
   downtime\_depth           | Number                | Whether the service has one or more active downtimes.
   flapping\_last\_change    | Timestamp             | When the last flapping change occurred (as a UNIX timestamp).
   flapping\_current         | Number                | Current flapping value in percent (see flapping\_thresholds)
-  flapping                  | Boolean               | Whether the host is flapping between states.
+  flapping                  | Boolean               | Whether the service is flapping between states.
   state                     | Number                | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
   last\_state               | Number                | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
   last\_hard\_state         | Number                | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
@@ -800,6 +805,11 @@ Runtime Attributes:
   last\_state\_warning      | Timestamp             | When the last WARNING state occurred (as a UNIX timestamp).
   last\_state\_critical     | Timestamp             | When the last CRITICAL state occurred (as a UNIX timestamp).
   last\_state\_unknown      | Timestamp             | When the last UNKNOWN state occurred (as a UNIX timestamp).
+  last\_state\_unreachable  | Timestamp             | When the service was unreachable the last time (as a UNIX timestamp).
+  previous\_state\_change   | Timestamp             | Previous timestamp of `last_state_change` before processing a new check result.
+  severity                  | Number                | [Severity](19-technical-concepts.md#technical-concepts-checks-severity) calculated value.
+  problem                   | Boolean               | Whether the service is considered in a problem state type (NOT-OK).
+  handled                   | Boolean               | Whether the service problem is handled (downtime or acknowledgement).
 
 
 ### ServiceGroup <a id="objecttype-servicegroup"></a>

diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md
index 31b0ef57f2bd11844de7feb9a3248c9237efc75c..e6483132a264a6729192b36a87a6dd2c4e4f422d 100644 (file)
--- a/doc/19-technical-concepts.md
+++ b/doc/19-technical-concepts.md
@@ -7,6 +7,7 @@ into specific Icinga 2 components such as:
 * [Configuration](19-technical-concepts.md#technical-concepts-configuration)
 * [Features](19-technical-concepts.md#technical-concepts-features)
 * [Check Scheduler](19-technical-concepts.md#technical-concepts-check-scheduler)
+* [Checks](19-technical-concepts.md#technical-concepts-checks)
 * [Cluster](19-technical-concepts.md#technical-concepts-cluster)
 * [TLS Network IO](19-technical-concepts.md#technical-concepts-tls-network-io)
 
@@ -371,7 +372,9 @@ deletes/inserts the next check event from the scheduling queue. This basically
 is a list with multiple indexes with the keys for scheduling info and the object.
 
 
-### Check Latency and Execution Time <a id="technical-concepts-check-scheduler-latency"></a>
+## Checks<a id="technical-concepts-checks"></a>
+
+### Check Latency and Execution Time <a id="technical-concepts-checks-latency"></a>
 
 Each check command execution logs the start and end time where
 Icinga 2 (and the end user) is able to calculate the plugin execution time from it.
@@ -396,6 +399,81 @@ The difference between the two deltas is called `check latency`.
 (GetScheduleEnd() - GetScheduleStart()) - CalculateExecutionTime()
 ```
 
+### Severity <a id="technical-concepts-checks-severity"></a>
+
+The severity attribute is introduced with Icinga v2.11 and provides
+a bit mask calculated value from specific checkable object states.
+
+The severity value is pre-calculated for visualization interfaces
+such as Icinga Web which sorts the problem dashboard by severity by default.
+
+The higher the severity number is, the more important the problem is.
+
+Flags:
+
+```
+/**
+ * Severity Flags
+ *
+ * @ingroup icinga
+ */
+enum SeverityFlag
+{
+       SeverityFlagDowntime = 1,
+       SeverityFlagAcknowledgement = 2,
+       SeverityFlagHostDown = 4,
+       SeverityFlagUnhandled = 8,
+       SeverityFlagPending = 16,
+       SeverityFlagWarning = 32,
+       SeverityFlagUnknown = 64,
+       SeverityFlagCritical = 128,
+};
+```
+
+
+Host:
+
+```
+       /* OK/Warning = Up, Critical/Unknown = Down */
+       if (!HasBeenChecked())
+               severity |= SeverityFlagPending;
+       else if (state == ServiceUnknown)
+               severity |= SeverityFlagCritical;
+       else if (state == ServiceCritical)
+               severity |= SeverityFlagCritical;
+
+       if (IsInDowntime())
+               severity |= SeverityFlagDowntime;
+       else if (IsAcknowledged())
+               severity |= SeverityFlagAcknowledgement;
+       else
+               severity |= SeverityFlagUnhandled;
+```
+
+
+Service:
+
+```
+       if (!HasBeenChecked())
+               severity |= SeverityFlagPending;
+       else if (state == ServiceWarning)
+               severity |= SeverityFlagWarning;
+       else if (state == ServiceUnknown)
+               severity |= SeverityFlagUnknown;
+       else if (state == ServiceCritical)
+               severity |= SeverityFlagCritical;
+
+       if (IsInDowntime())
+               severity |= SeverityFlagDowntime;
+       else if (IsAcknowledged())
+               severity |= SeverityFlagAcknowledgement;
+       else if (m_Host->GetProblem())
+               severity |= SeverityFlagHostDown;
+       else
+               severity |= SeverityFlagUnhandled;
+```
+
+
 
 ## Cluster <a id="technical-concepts-cluster"></a>