biztalk-checkmk-pulse/README.md

BizTalk Checkmk Pulse

BizTalk Checkmk Pulse ist ein lokaler Checkmk-Check fuer Microsoft BizTalk Server 2020 auf Windows. Er liest BizTalk-Betriebsdaten ueber WMI aus root\MicrosoftBizTalkServer, erzeugt Checkmk-Local-Check-Ausgaben und kann dadurch ohne serverseitigen Python-Check in Checkmk 2.4 integriert werden.

Der Ansatz ist fuer Umgebungen wie ACC, DEV, TST und PRD gedacht, in denen pro Umgebung ein BizTalk Server 2020 und ein SQL Server betrieben werden. SQL Server bleibt beim mitgelieferten Checkmk-MSSQL-Plugin; dieses Projekt ergaenzt die BizTalk-spezifische Sicht.

Warum Local Check statt serverseitigem Check-Plugin?

Checkmk 2.4 kann Windows-Agent-Plugins und Local Checks direkt ausfuehren. Fuer diese Umgebung ist ein C#/.NET-Framework-Programm mit .cmd-Wrapper die robusteste Variante:

• keine PowerShell-Ausfuehrung erforderlich
• keine BizTalk-ExplorerOM/OperationsOM-DLL als Build-Abhaengigkeit
• keine Python-Check-API-Abhaengigkeit auf der Checkmk-Site
• einfache Verteilung auf die BizTalk-Maschinen per Dateiablage, Softwareverteilung oder Agent Bakery
• automatische Service Discovery in Checkmk

Erzeugte Checkmk-Services

Standardmaessig entstehen diese stabilen Services:

• BizTalk Platform
• BizTalk Suspended Instances
• BizTalk Host Instances
• BizTalk Runtime Artifacts
• BizTalk Event Log

Wenn EnvironmentName=ACC, DEV, TST oder PRD gesetzt wird, wird der Name vor den Suffix gesetzt, z.B. BizTalk PRD Suspended Instances. Das ist praktisch, wenn die Umgebung bereits im Hostnamen oder Ordner abgebildet ist, aber nicht zwingend noetig.

Details zu Statuslogik und Metriken stehen in docs/CheckmkServices.md. Beispielausgaben stehen in docs/ExampleOutput.md.

Build

Voraussetzungen auf einem Windows-Build-Host:

• Visual Studio 2022 Build Tools oder Visual Studio
• MSBuild im PATH
• .NET Framework 4.7.2 Developer Pack

Build:

scripts\build-release.cmd

Deployment-Paket erstellen:

scripts\package-release.cmd

Ergebnis:

artifacts\BizTalkCheckmkPulse-deploy\
  biztalk_checkmk_pulse.cmd
  BizTalkCheckmkPulse\
    BizTalkCheckmkPulse.exe
    BizTalkCheckmkPulse.exe.config

Validierung nach dem Build:

artifacts\BizTalkCheckmkPulse-deploy\biztalk_checkmk_pulse.cmd --self-test

Installation auf dem BizTalk-Server

Kopiere den Inhalt von artifacts\BizTalkCheckmkPulse-deploy nach:

%ProgramData%\checkmk\agent\local

Zielstruktur:

%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config

Manueller Test auf dem BizTalk-Server:

"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd" --self-test
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"

Agent-Ausgabe wie Checkmk sie sieht:

"C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump

Danach in Checkmk fuer den BizTalk-Host eine Service Discovery ausfuehren, die neuen Services aufnehmen und Changes aktivieren.

Konfiguration

Die Konfiguration liegt neben der EXE:

%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config

Wichtige Werte:

Key	Default	Bedeutung
Server	.	Lokaler BizTalk-Server. Remote-WMI ist moeglich, aber nicht empfohlen.
ServicePrefix	BizTalk	Prefix fuer alle Checkmk-Services.
EnvironmentName	leer	Optional ACC, DEV, TST oder PRD.
QueryTimeoutSeconds	25	WMI-Timeout pro Query.
WarnResumableThreshold	1	WARN ab n resumable suspended instances.
CritNonResumableThreshold	1	CRIT ab n non-resumable suspended instances.
AlertOnArtifactRuntimeIssues	false	Wenn true, werden deaktivierte Receive Locations und inaktive Ports/Orchestrations als WARN gewertet.
EmitPerApplicationSuspensionServices	false	Erzeugt zusaetzliche Services pro Anwendung mit Suspensions.
ProbeEventLog	true	Liest das Windows Application Log nach BizTalk-bezogenen Sources.
EventLogLookbackMinutes	60	Zeitraum fuer Event-Log-Auswertung.
EventLogWarnThreshold	1	WARN ab n Errors oder Warnings.
EventLogCritThreshold	10	CRIT ab n Errors.

Empfehlung:

• In DEV, TST, ACC: AlertOnArtifactRuntimeIssues=false, damit bewusst gestoppte Artefakte nicht rauschen.
• In PRD: erst zwei Wochen beobachten; danach nur aktivieren, wenn die Runtime-Artefakte wirklich als Betriebsstandard immer aktiv sein muessen.
• EmitPerApplicationSuspensionServices=true nur verwenden, wenn Anwendungsteams eigene Services benoetigen. Sonst bleibt die Discovery schlanker.

Integration in Checkmk Managed Services Edition 2.4

Aufgaben der Checkmk-Kollegen:

1. BizTalk-Hosts in Checkmk anlegen oder bestehende Hosts pruefen.
2. Sicherstellen, dass der Checkmk Windows Agent installiert, registriert und erreichbar ist.
3. Plugin-Dateien auf die BizTalk-Server verteilen, manuell oder per Agent Bakery.
4. Optional EnvironmentName je Umgebung setzen, z.B. ACC, DEV, TST oder PRD.
5. Agent-Ausgabe mit cmk-agent-ctl.exe dump pruefen.
6. Service Discovery fuer jeden BizTalk-Host ausfuehren.
7. Gefundene BizTalk ... Services aufnehmen und Changes aktivieren.
8. Views, Dashboards, Servicegruppen und Benachrichtigungen fuer die BizTalk-Services konfigurieren.

Manuelle Integration:

1. Dateien auf dem BizTalk-Server nach %ProgramData%\checkmk\agent\local kopieren.
2. Optional BizTalkCheckmkPulse.exe.config je Umgebung anpassen.
3. Agent-Dump pruefen.
4. Service Discovery auf dem BizTalk-Host ausfuehren.
5. Services in ein BizTalk-Dashboard aufnehmen.

Integration ueber Agent Bakery:

1. Deployment-Dateien in der Checkmk-Site als Custom-Agent-Dateien bereitstellen.
2. Windows-Agent-Regel fuer die BizTalk-Hosts erstellen.
3. Agent backen und auf ACC/DEV/TST/PRD-BizTalk-Hosts ausrollen.
4. Discovery und Dashboard-Aufnahme durchfuehren.

Die Checkmk-Dokumentation nennt fuer Windows Local Checks %ProgramData%\checkmk\agent\local und fuer Windows Agent Plugins %ProgramData%\checkmk\agent\plugins. Dieses Projekt nutzt bewusst local, weil der Zustand direkt vom Host berechnet und sofort als Checkmk-Service geliefert wird.

Empfohlene Alarmierung:

• BizTalk Platform: UNKNOWN immer untersuchen, da dann WMI, Rechte oder Deployment betroffen sind.
• BizTalk Suspended Instances: in PRD direkt alarmieren; in Nicht-PRD nach Betriebsbedarf.
• BizTalk Host Instances: CRIT alarmieren, weil gestoppte Host Instances Laufzeitverarbeitung verhindern koennen.
• BizTalk Runtime Artifacts: zunaechst beobachten; strengere Alarmierung erst aktivieren, wenn deaktivierte Artefakte nicht fachlich gewollt sind.
• BizTalk Event Log: Schwellwerte nach Beobachtungsphase anpassen.

Quellen

• Checkmk Local Checks: https://docs.checkmk.com/latest/en/localchecks.html
• Checkmk Windows Agent und Plugin-Pfade: https://docs.checkmk.com/latest/en/agent_windows.html
• Checkmk Agent-Based Plugin-Entwicklung: https://docs.checkmk.com/latest/en/devel_check_plugins.html
• Checkmk Bakery API: https://docs.checkmk.com/latest/en/bakery_api.html
• Checkmk MKP-Pakete: https://docs.checkmk.com/latest/en/mkps.html
• Microsoft BizTalk WMI MSBTS_ServiceInstance: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-wmi
• Microsoft BizTalk WMI ServiceStatus: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-servicestatus-property-wmi