Add BizTalk Checkmk Pulse local check
This commit is contained in:
@@ -0,0 +1,265 @@
|
||||
# Dokumentation: BizTalk Checkmk Pulse
|
||||
|
||||
## Zielbild
|
||||
|
||||
Ziel ist ein wartbares Monitoring fuer BizTalk Server 2020 in den Umgebungen `ACC`, `DEV`, `TST` und `PRD`. Jede Umgebung besitzt einen BizTalk Server 2020 und einen SQL Server. SQL Server wird mit dem Checkmk-eigenen MSSQL-Plugin ueberwacht; fuer BizTalk liefert dieses Projekt die fehlende fachliche und technische Laufzeitsicht.
|
||||
|
||||
Das Monitoring soll:
|
||||
|
||||
- auf jeder BizTalk-Maschine lokal laufen
|
||||
- ohne PowerShell-Abhaengigkeit funktionieren
|
||||
- keine BizTalk-DLLs im Build erzwingen
|
||||
- Checkmk-2.4-kompatible Services und Metriken erzeugen
|
||||
- service-discovery-freundlich und dashboard-tauglich sein
|
||||
- bei Fehlern gueltige `UNKNOWN`-Services statt kaputter Agent-Ausgaben liefern
|
||||
|
||||
## Technische Bewertung
|
||||
|
||||
### Option A: Checkmk Local Check mit C#/.NET Framework
|
||||
|
||||
Bewertung: empfohlen und umgesetzt.
|
||||
|
||||
Vorteile:
|
||||
|
||||
- Checkmk 2.4 unterstuetzt Local Checks direkt.
|
||||
- Windows Server mit BizTalk 2020 bringt .NET Framework in der Regel passend mit.
|
||||
- `System.Management` kann BizTalk-WMI lesen.
|
||||
- Keine PowerShell Execution Policy, keine Script-Signing-Frage.
|
||||
- Kein serverseitiges Checkmk-Python-Plugin notwendig.
|
||||
- Rollout ist eine einfache Dateiablage unter `%ProgramData%\checkmk\agent\local`.
|
||||
|
||||
Nachteile:
|
||||
|
||||
- Schwellwerte sind in der `.exe.config`, nicht als Checkmk-Regelsatz in WATO.
|
||||
- Eigene Graphing-Definitionen sind nicht enthalten; Checkmk zeigt Local-Check-Metriken trotzdem als Performance-Daten und Graphen.
|
||||
|
||||
### Option B: Agent Plugin plus serverseitiges Checkmk-Plugin
|
||||
|
||||
Bewertung: technisch elegant, aber fuer den ersten produktiven Schritt schwerer.
|
||||
|
||||
Vorteile:
|
||||
|
||||
- Checkmk-Regeln, Discovery und Metrikdefinitionen koennen sauber zentral modelliert werden.
|
||||
- Bessere langfristige Erweiterbarkeit als MKP.
|
||||
|
||||
Nachteile:
|
||||
|
||||
- Checkmk-Check-API-Versionen muessen enger gepflegt werden.
|
||||
- Server-seitige Installation in jeder Site erforderlich.
|
||||
- Mehr Aufwand fuer Managed-Services-Betrieb und Updates.
|
||||
|
||||
Empfehlung: als Version 2 dieses Projekts denkbar, wenn die Local-Check-Variante stabil in PRD laeuft und zentrale Regelsaetze wirklich benoetigt werden.
|
||||
|
||||
### Option C: PowerShell Local Check
|
||||
|
||||
Bewertung: nicht empfohlen fuer diese Umgebung.
|
||||
|
||||
Vorteile:
|
||||
|
||||
- Schnell zu schreiben.
|
||||
- WMI/CIM-Zugriff ist komfortabel.
|
||||
|
||||
Nachteile:
|
||||
|
||||
- PowerShell ist in vielen Serverumgebungen eingeschraenkt oder signaturpflichtig.
|
||||
- Ausfuehrungsverhalten im Checkmk-Agent-Kontext ist haeufiger fehleranfaellig.
|
||||
|
||||
### Option D: BizTalk ExplorerOM/OperationsOM
|
||||
|
||||
Bewertung: fachlich stark, deployseitig unnoetig schwer.
|
||||
|
||||
Vorteile:
|
||||
|
||||
- Hoehere BizTalk-Abstraktion als rohe WMI-Klassen.
|
||||
|
||||
Nachteile:
|
||||
|
||||
- BizTalk-DLL-Versionen muessen beim Build und teilweise zur Laufzeit passen.
|
||||
- Build-Agenten brauchen BizTalk-Komponenten oder SDK-Dateien.
|
||||
- Fuer die benoetigten Zustandsdaten reicht WMI aus.
|
||||
|
||||
## Architektur
|
||||
|
||||
```text
|
||||
Checkmk Windows Agent
|
||||
|
|
||||
| startet lokale Checks aus %ProgramData%\checkmk\agent\local
|
||||
v
|
||||
biztalk_checkmk_pulse.cmd
|
||||
|
|
||||
| startet
|
||||
v
|
||||
BizTalkCheckmkPulse.exe
|
||||
|
|
||||
| liest lokal
|
||||
+-- WMI root\MicrosoftBizTalkServer
|
||||
+-- Windows Application Event Log
|
||||
|
|
||||
v
|
||||
Checkmk Local Check Zeilen nach STDOUT
|
||||
```
|
||||
|
||||
Der `.cmd`-Wrapper liefert auch dann eine gueltige `UNKNOWN`-Zeile, wenn die EXE fehlt. Die EXE selbst faengt Laufzeitfehler ab und schreibt fuer alle stabilen Services `UNKNOWN`, damit unvollstaendige Deployments oder WMI-Probleme in Checkmk sichtbar bleiben.
|
||||
|
||||
## Datenquellen
|
||||
|
||||
### BizTalk WMI Namespace
|
||||
|
||||
Namespace:
|
||||
|
||||
```text
|
||||
root\MicrosoftBizTalkServer
|
||||
```
|
||||
|
||||
Genutzte Klassen:
|
||||
|
||||
| Klasse | Zweck |
|
||||
| --- | --- |
|
||||
| `MSBTS_GroupSetting` | BizTalk-Gruppe und Management-DB-Hinweise. |
|
||||
| `MSBTS_MessageBoxSetting` | MessageBox-DB-Hinweise. |
|
||||
| `MSBTS_HostInstance` | Host-Instance-Zustand. |
|
||||
| `MSBTS_ServiceInstance` | Suspended service instances. |
|
||||
| `MSBTS_ReceiveLocation` | Receive-Location-Zustand. |
|
||||
| `MSBTS_SendPort` | Send-Port-Zustand. |
|
||||
| `MSBTS_Orchestration` | Orchestration-Zustand. |
|
||||
| `MSBTS_ReceivePort` | Application-Mapping fuer Details. |
|
||||
|
||||
### Windows Application Event Log
|
||||
|
||||
Der Check liest standardmaessig das lokale Application Log fuer die letzten 60 Minuten und filtert auf Quellen wie:
|
||||
|
||||
- `BizTalk Server`
|
||||
- `XLANG/s`
|
||||
- `ENTSSO`
|
||||
- `BizTalk Server Application`
|
||||
- `BizTalk Server EDI`
|
||||
|
||||
Die Liste ist ueber `EventLogSources` konfigurierbar.
|
||||
|
||||
## Resilienz
|
||||
|
||||
Das Plugin ist bewusst defensiv gebaut:
|
||||
|
||||
- WMI-Queries haben ein konfigurierbares Timeout.
|
||||
- Optionale WMI-Klassen erzeugen Diagnosehinweise statt Totalabbruch.
|
||||
- Fehlende Properties werden als leer/unknown behandelt.
|
||||
- Local-Check-Ausgaben verwenden gueltige Checkmk-Zeilen mit genau vier Feldern.
|
||||
- Fatal Errors erzeugen `UNKNOWN` fuer alle stabilen Services.
|
||||
- Event-Log-Auswertung ist isoliert; ein Fehler dort bricht WMI-Monitoring nicht ab.
|
||||
- Service-Namen sind stabil, damit Service Discovery nicht bei jedem Lauf neue Services erzeugt.
|
||||
|
||||
## Statusmodell
|
||||
|
||||
### BizTalk Platform
|
||||
|
||||
- `OK`: BizTalk-WMI erreichbar.
|
||||
- `UNKNOWN`: WMI nicht erreichbar oder kompletter Programmfehler.
|
||||
|
||||
Dieser Service ist der Integrationsindikator. Wenn er `UNKNOWN` ist, sind Berechtigungen, BizTalk-Installation oder WMI-Repository zu pruefen.
|
||||
|
||||
### BizTalk Suspended Instances
|
||||
|
||||
- `OK`: keine suspendierten Instanzen.
|
||||
- `WARN`: mindestens `WarnResumableThreshold` resumable suspended instances.
|
||||
- `CRIT`: mindestens `CritNonResumableThreshold` non-resumable suspended instances.
|
||||
- `UNKNOWN`: Datenquelle nicht lesbar.
|
||||
|
||||
### BizTalk Host Instances
|
||||
|
||||
- `OK`: alle Host-Instanzen sind started.
|
||||
- `WARN`: mindestens eine Host-Instanz ist pending.
|
||||
- `CRIT`: mindestens eine Host-Instanz ist stopped oder unknown.
|
||||
- `UNKNOWN`: keine Host-Instanzen gefunden oder Datenquelle nicht lesbar.
|
||||
|
||||
### BizTalk Runtime Artifacts
|
||||
|
||||
- `OK`: Artefakte lesbar, keine unbekannten Statuswerte.
|
||||
- `WARN`: nur wenn `AlertOnArtifactRuntimeIssues=true` und deaktivierte/inaktive Artefakte vorhanden sind.
|
||||
- `CRIT`: unbekannte Send-Port- oder Orchestration-Statuswerte.
|
||||
|
||||
Deaktivierte Receive Locations und gestoppte Ports koennen in BizTalk fachlich korrekt sein. Deshalb ist die Alarmierung hier standardmaessig informativ.
|
||||
|
||||
### BizTalk Event Log
|
||||
|
||||
- `OK`: keine relevanten Fehler/Warnungen ueber Schwellwert.
|
||||
- `WARN`: Fehler oder Warnungen ab `EventLogWarnThreshold`.
|
||||
- `CRIT`: Fehler ab `EventLogCritThreshold`.
|
||||
- `UNKNOWN`: Event Log nicht lesbar.
|
||||
|
||||
## Dashboard-Empfehlung
|
||||
|
||||
Pro Umgebung sollte der BizTalk-Host in einem eigenen Host-Ordner oder Host-Tag fuer `ACC`, `DEV`, `TST`, `PRD` liegen. Im Dashboard eignen sich:
|
||||
|
||||
- Service State Widgets fuer die fuenf BizTalk-Services
|
||||
- Graphen fuer `biztalk_suspended_total`, `biztalk_host_instances_stopped`, `biztalk_eventlog_errors`
|
||||
- Hostgruppe/Ordner pro Umgebung
|
||||
- Optional eine View gefiltert auf `Service starts with BizTalk`
|
||||
|
||||
Empfohlene Reihenfolge im Dashboard:
|
||||
|
||||
1. `BizTalk Platform`
|
||||
2. `BizTalk Suspended Instances`
|
||||
3. `BizTalk Host Instances`
|
||||
4. `BizTalk Event Log`
|
||||
5. `BizTalk Runtime Artifacts`
|
||||
6. SQL-Server-Services aus dem Checkmk-MSSQL-Plugin
|
||||
|
||||
## Rollout-Vorgehen
|
||||
|
||||
1. Build-Paket erzeugen.
|
||||
2. In `DEV` auf dem BizTalk-Server installieren.
|
||||
3. `--self-test` und normalen Lauf ausfuehren.
|
||||
4. Agent-Dump pruefen.
|
||||
5. Checkmk Discovery durchfuehren.
|
||||
6. Eine Woche Messwerte und false positives beobachten.
|
||||
7. Nach `TST` und `ACC` uebernehmen.
|
||||
8. In `PRD` mit `AlertOnArtifactRuntimeIssues=false` starten.
|
||||
9. Nach Betriebsfreigabe Schwellwerte feinjustieren.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service bleibt UNKNOWN
|
||||
|
||||
Pruefen:
|
||||
|
||||
```cmd
|
||||
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"
|
||||
```
|
||||
|
||||
Wenn WMI nicht erreichbar ist:
|
||||
|
||||
```cmd
|
||||
wmic /namespace:\\root\MicrosoftBizTalkServer path MSBTS_HostInstance get HostName,RunningServer,ServiceState
|
||||
```
|
||||
|
||||
Der Checkmk Windows Agent laeuft normalerweise als LocalSystem. Daher immer auch den Agent-Dump verwenden:
|
||||
|
||||
```cmd
|
||||
"C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump
|
||||
```
|
||||
|
||||
### Keine Services in Discovery
|
||||
|
||||
Pruefen:
|
||||
|
||||
- Liegt `biztalk_checkmk_pulse.cmd` direkt unter `%ProgramData%\checkmk\agent\local`?
|
||||
- Gibt der Wrapper direkt eine Zeile im Format `0 "Service" metric=value Details` aus?
|
||||
- Wurde der Checkmk-Agent nach Policy-/Bakery-Aenderungen neu ausgerollt?
|
||||
|
||||
### Runtime Artifacts zeigt deaktivierte Artefakte
|
||||
|
||||
Das ist standardmaessig `OK`, damit gewollt deaktivierte BizTalk-Artefakte nicht alarmieren. Fuer strengere PRD-Standards:
|
||||
|
||||
```xml
|
||||
<add key="AlertOnArtifactRuntimeIssues" value="true" />
|
||||
```
|
||||
|
||||
## Weiterentwicklung
|
||||
|
||||
Sinnvolle naechste Ausbaustufen:
|
||||
|
||||
- MKP mit Agent-Bakery-Regel fuer zentrale Konfiguration.
|
||||
- Optionales serverseitiges Check-Plugin nach Checkmk Check API V2.
|
||||
- Custom Dashboard/View als Checkmk GUI Extension.
|
||||
- Ergaenzung um MessageBox-Spool/Tracking-Daten, falls operativ benoetigt.
|
||||
|
||||
Reference in New Issue
Block a user