biztalk-checkmk-pulse/Dokumentation.md

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

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:

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:

"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"

Wenn WMI nicht erreichbar ist:

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:

"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:

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