API updates and formal changes, pick-24

Author: thomaskoslowski

src/onprem/de/livestatus.asciidoc

@@ -3,9 +3,9 @@
 // NONASCII …​
 include::global_attr.adoc[]
 = Statusdaten abrufen via Livestatus
-:revdate: 2022-10-27
 :title: Statusdaten abrufen via Livestatus
 :description: Livestatus ermöglicht Ihnen den direkten Zugriff auf alle Daten der mit {CMK} überwachten Objekte. Hier erfahren Sie, wie Sie die Livestatus-API nutzen.
+:experimental:
 
 {related-start}
 xref:livestatus_references#[Livestatus Befehlsreferenz]
@@ -14,6 +14,7 @@ xref:rest_api#[Die {CMK} REST-API]
 {related-end}
 
 
+[#intro]
 == Einleitung
 
 Der Livestatus ist die wichtigste Schnittstelle in {CMK}. Durch sie bekommen
@@ -199,16 +200,16 @@ reply = "".join(chunks)
 print(json.loads(reply))
 ----
 
+
+[#api]
 === Nutzung der Livestatus-API
 
-{CMK} stellt auch eine API für die Programmiersprachen Python, Perl und
-C++ zur Verfügung, welche den Zugriff auf den Livestatus vereinfachen. Zu
-jeder Sprache steht Ihnen Beispielcode zur Verfügung, welcher die Nutzung
-erläutert. Die Pfade zu diesen Beispielen finden Sie in dem Kapitel
-xref:livestatus#files[Dateien und Verzeichnisse].
-// TODO: Hier noch einen Hinweis einbauen, sobald es einen Artikel in der
-//       Sektion "Erweiterungen Programmieren" dazu gibt.
+{CMK} stellt auch eine API für die Programmiersprache Python zur Verfügung, welche den Zugriff auf den Livestatus vereinfachen.
+Zu dieser API steht Ihnen Beispielcode zur Verfügung, welcher die Nutzung erläutert.
+Sie finden diese API auf link:https://github.com/Checkmk/checkmk/tree/master/packages/cmk-livestatus-client/[GitHub^].
+
 
+[#simple_queries]
 == Einfache Abfragen
 
 === Spalten abfragen (Columns)
@@ -229,9 +230,11 @@ myserver234;192.168.0.73
 Wie Sie sehen, erfolgt die Trennung der einzelnen Werte einer Zeile wiederum
 durch ein Semikolon.
 
-*Wichtig:* Wenn Sie diesen Header benutzen, werden die Kopfzeilen
-in der Ausgabe unterdrückt. Sie können diese aber mit dem Header
-xref:livestatus#columnheader[ColumnHeaders] der Ausgabe wieder hinzufügen.
+[TIP]
+====
+Wenn Sie diesen Header benutzen, werden die Kopfzeilen in der Ausgabe unterdrückt.
+Sie können diese aber mit dem Header xref:livestatus#columnheader[ColumnHeaders] der Ausgabe wieder hinzufügen.
+====
 
 
 === Einfache Filter setzen (Filter)
@@ -326,6 +329,7 @@ ahost;uptime|48959
 ----
 
 
+[#complex_queries]
 == Komplexe Abfragen
 
 [#filter]
@@ -460,8 +464,10 @@ myserver123     Filesystem /home        0
 
 ----
 
-*Wichtig:* Die Reihenfolge der Separatoren ist fest und darf daher
-nicht vertauscht werden.
+[TIP]
+====
+Die Reihenfolge der Separatoren ist fest und darf daher nicht vertauscht werden.
+====
 
 
 [#output_format]
@@ -610,6 +616,7 @@ guest=0.000000 steal=0.000000 system=34.515000 user=98.209000 wait=23.008000
 ----
 
 
+[#limit]
 == Begrenzung der Ausgabe (Limit)
 
 Die Anzahl der Zeilen in der Ausgabe ist begrenzbar. Das kann z.B. nützlich
@@ -631,6 +638,7 @@ haben und die Ausgabe auf 10 begrenzen, werden nur die ersten 10 Hosts
 berücksichtigt.
 
 
+[#timelimit]
 == Zeitbeschränkungen (Timelimit)
 
 Sie können nicht nur die Anzahl der ausgegebenen Zeilen einschränken. Auch
@@ -646,7 +654,6 @@ Abfrage dauern darf:
 ----
 
 
-
 [#columnheader]
 == Kopfzeilen aktivieren (ColumnHeaders)
 
@@ -665,7 +672,7 @@ myserver345;192.168.0.44;cluster_a
 ----
 
 
-
+[#authuser]
 == Berechtigungen (AuthUser)
 
 Wenn Sie Skripten auf Basis des Livestatus zur Verfügung stellen möchten,
@@ -708,7 +715,7 @@ myserver123;CPU load;hhrisch,kkleber
 ----
 
 
-
+[#wait]
 == Verzögerungen (Wait)
 
 Mit den Wait-Headern erstellen Sie Abfragen, um bestimmte Datensätze zu
@@ -766,13 +773,14 @@ Columns: host_name description state
 myserver;Memory;0
 ----
 
-*Wichtig:* Achten Sie darauf,
-dass der Zeitstempel in `last_check` aus dem Beispiel durch einen
-aktuellen ersetzt werden muss.  Andernfalls ist die Bedingung immer erfüllt
-und die Ausgabe kommt sofort.
-
+[TIP]
+====
+Achten Sie darauf, dass der Zeitstempel in `last_check` aus dem Beispiel durch einen aktuellen ersetzt werden muss.
+Andernfalls ist die Bedingung immer erfüllt und die Ausgabe kommt sofort.
+====
 
 
+[#localtime]
 == Zeitzonen (Localtime)
 
 Viele größere Monitoring-Umgebungen rufen auf globaler Ebene Hosts und
@@ -809,7 +817,6 @@ myserver123;Memory;1511173526
 ----
 
 
-
 [#response_header]
 == Statuscodes (ResponseHeader)
 
@@ -839,9 +846,9 @@ einen Filter falsch setzen bzw. mit dem Namen einer Spalte _verwechseln._
 Coluns: undefined request header
 ----
 
-*Wichtig:* Das xref:livestatus#output_format[Ausgabeformat] ist im Fehlerfall
-immer eine Fehlermeldung in Textform. Das gilt unabhängig davon, wie Sie
-es angepasst haben.
+Das xref:livestatus#output_format[Ausgabeformat] ist im Fehlerfall immer eine Fehlermeldung in Textform.
+Das gilt unabhängig davon, wie Sie es angepasst haben.
+
 
 [#keepalive]
 == Verbindung aufrecht erhalten (KeepAlive)
@@ -854,12 +861,13 @@ einen Kanal zu _reservieren_. Nach einem xref:livestatus#commands[Befehl]
 bleibt eine Livestatus-Verbindung übrigens immer offen. Sie benötigen dafür
 keine Angabe eines zusätzlichen Headers.
 
-*Wichtig:* Da der Kanal für die Dauer der Verbindung für andere Prozesse
-blockiert ist, kann das zu einem Problem werden, wenn keine Verbindungen
-mehr zur Verfügung stehen. Andere Prozesse müssen dann warten, bis wieder
-eine Verbindung frei ist. In der Standardkonfiguration hält {CMK} 20
-Verbindungen bereit -- erhöhen Sie bei Bedarf die maximale Anzahl dieser
-Verbindungen in [.guihint]#Setup > General > Global Settings > Monitoring Core > Maximum concurrent Livestatus connections#.
+[TIP]
+====
+Da der Kanal für die Dauer der Verbindung für andere Prozesse blockiert ist, kann das zu einem Problem werden, wenn keine Verbindungen mehr zur Verfügung stehen.
+Andere Prozesse müssen dann warten, bis wieder eine Verbindung frei ist.
+In der Standardkonfiguration hält {CMK} 20 Verbindungen bereit
+-- erhöhen Sie bei Bedarf die maximale Anzahl dieser Verbindungen in [.guihint]#Setup > General > Global Settings > Monitoring Core > Maximum concurrent Livestatus connections#.
+====
 
 Kombinieren Sie `KeepAlive` immer mit dem
 xref:livestatus#response_header[`ResponseHeader`], um die
@@ -941,9 +949,11 @@ myserver123;Memory;1511343338;2
 myserver234;CPU load;1511342512;0
 ----
 
-*Wichtig:* Achten Sie darauf, dass Sie im interaktiven Modus des Eingabe-Streams keine
-Variablen wie in dem Beispiel nutzen können. Und schränken Sie die Abfragen
-*immer* auf einen Zeitraum ein.
+[TIP]
+====
+Achten Sie darauf, dass Sie im interaktiven Modus des Eingabe-Streams keine Variablen wie in dem Beispiel nutzen können.
+Und schränken Sie die Abfragen *immer* auf einen Zeitraum ein.
+====
 
 
 === Die Monitoring-Historie konfigurieren
@@ -962,13 +972,11 @@ welche Sie in unter [.guihint]#Setup > General > Global Settings > Monitoring Co
 
 |[.guihint]#History log rotation: Regular interval of rotations# |Hier wird festgelegt, in welchem Zeitintervall die Historie in einer neuen Datei weitergeführt wird.
 |[.guihint]#History log rotation: Rotate by size (Limit of the size)# |Unabhängig von dem Zeitintervall wird hier die maximale Größe einer Datei festgelegt. Die Größe stellt einen Kompromiss zwischen der möglichen Leserate und den möglichen IOs dar.
-// TK: IOs sind nochmal was?
 |[.guihint]#Maximum number of parsed lines per log file# |Nach der angegeben Anzahl an Zeilen wird eine Datei nicht weiter gelesen. Das verhindert Timeouts, falls eine Datei aus irgendwelchen Gründen doch sehr groß geworden sein sollte.
 |===
 
 
-
-
+[#availability]
 == Verfügbarkeiten prüfen
 
 Mit der Tabelle `statehist` können Sie die Rohdaten zu der
@@ -1023,6 +1031,7 @@ Wie Sie eine vollständige Liste der verfügbaren Spalten abrufen, wird in der
 xref:livestatus#columns[Befehlsreferenz] näher erläutert.
 
 
+[#variables]
 == Variablen im Livestatus
 
 Sie können an verschiedenen Stellen in der {CMK}-Oberfläche Variablen
@@ -1048,9 +1057,6 @@ bekommen Sie den eigentlichen Wert des Makros ausgegeben:
 myserver123;\https://mymonitoring/heute/wiki/doku.php?id=hosts:myserver123
 ----
 
-// TODO: Link zu einem Artikel in dem die verfügbaren Makros/Variablen
-//       erläutert werden? In welchem Artikel würde das dokumentiert werden?
-
 
 [#network]
 == Livestatus über das Netzwerk nutzen
@@ -1113,7 +1119,7 @@ Server certificate
 read R BLOCK
 ----
 
-Erfolgt keine weitere Ausgabe mehr, können Sie interaktiv LQL-Befehle absetzen, welche Sie mit einer Leerzeile (zweimal Return-Taste) abschließen.
+Erfolgt keine weitere Ausgabe mehr, können Sie interaktiv LQL-Befehle absetzen, welche Sie mit einer Leerzeile (zweimal kbd:[Enter]-Taste) abschließen.
 Klappt dies, können Sie Livestatus-Abfragen auch per Pipeline übergeben, der zusätzliche Parameter `-quiet` unterdrückt hier Debugging-Ausgaben:
 
 [{shell}]
@@ -1183,8 +1189,8 @@ Nach Neustart des stunnel ist der Zugriff auf den lokalen Port unverschlüsselt
 Falls Sie per Skript via SSL auf Livestatus zugreifen wollen, verwenden Sie möglichst nicht `openssl s_client`.
 Primärer Zweck dieses Tools ist der Test des Verbindungsaufbaus und das Debugging von Zertifikatsketten.
 Um im Falle von Verbindungsabbrüchen zu erkennen, ob die erwartete Ausgabe vollständig war, empfehlen wir, den xref:response_header[`ResponseHeader`] auszuwerten.
-Ein gut gepflegtes API, welches SSL und Header-Auswertung unterstützt, ist jenes für Python, das Sie unter `share/doc/check_mk/livestatus/api/python` finden.
-Weitere APIs listet das Kapitel xref:files[_Dateien und Verzeichnisse_].
+Eine gut gepflegtes API, welche SSL und Header-Auswertung unterstützt, ist jene für Python, die Sie auf link:https://github.com/Checkmk/checkmk/tree/master/packages/cmk-livestatus-client/[GitHub^] finden.
+
 
 === Verbindung über SSH
 
@@ -1294,9 +1300,7 @@ gegebenenfalls die Variablen:
 |`~/var/log/nagios.log` |Die Log-Datei des Nagios-Core, in der unter anderem die Abfragen/Befehle dokumentiert werden.
 |`~/var/nagios/archive/` |Hier werden die `history`-Log-Dateien archiviert. Diese werden nur nach Bedarf eingelesen.
 |`~/share/doc/check_mk/livestatus/LQL-examples/` |In diesem Verzeichnis finden Sie einige Beispiele zu Livestatus-Abfragen, die Sie ausprobieren können. Die Beispiele werden an den Skriptbefehl `lq` geleitet, wie z.B.: `lq < 1.lql`
-|`~/share/doc/check_mk/livestatus/api/python` |In diesem Verzeichnis finden Sie die API zu Python sowie einige Beispiele. Lesen Sie auch das `README` in diesem Verzeichnis.
-|`~/share/doc/check_mk/livestatus/api/perl` |Die API zu Perl finden Sie hier. Auch hier gibt es wieder ein `README`. Die Beispiele zur Nutzung befinden sich hier in dem Unterverzeichnis `examples`.
-|`~/share/doc/check_mk/livestatus/api/c++` |Zu der Programmiersprache C++ finden Sie hier ebenfalls Beispielcode. Der Code zu der API selbst liegt ebenfalls unkompiliert vor, so dass Sie maximalen Einblick in die Funktionsweise der API haben.
+haben.
 |===