Lokaler Checkmk-Check fuer Microsoft BizTalk Server 2020. Der Check prueft ueber WMI im Namespace root\MicrosoftBizTalkServer, ob suspendierte BizTalk-Service-Instanzen vorhanden sind, und liefert zusaetzliche Betriebsinformationen zu Host-Instanzen und BizTalk-Artefakten.

Entscheidung

PowerShell ist in der Zielumgebung abgeriegelt. Die sinnvollste Option ist deshalb ein kleines C#/.NET-Framework-Konsolenprogramm, das per .cmd aus dem Checkmk-Agent-Local-Verzeichnis gestartet wird.

Bewertung:

C#/.NET Framework: geeignet. Auf Windows Server mit BizTalk vorhanden, direkte WMI-Unterstuetzung via System.Management, keine PowerShell-Ausfuehrung, keine BizTalk-DLL als Compile-Time-Abhaengigkeit.
PowerShell: fachlich moeglich, aber in der Umgebung ausgeschlossen.
VBScript/JScript: technisch moeglich, aber schlechter wartbar und fehleranfaelliger bei Encoding und Fehlerbehandlung.
BizTalk OperationsOM/ExplorerOM DLLs: fachlich moeglich, aber deploy- und buildseitig unnoetig schwer, da die DLLs auf Build- und Laufzeitumgebung passen muessen.

Der Check nutzt fuer Suspensions die WMI-Klasse MSBTS_ServiceInstance. Microsoft dokumentiert fuer ServiceStatus den Wert 4 als Suspended (resumable) und 32 als Suspended (not resumable). Fuer die weiteren Betriebsinformationen werden MSBTS_HostInstance, MSBTS_ReceiveLocation, MSBTS_SendPort und MSBTS_Orchestration gelesen.

Checkmk-Verhalten

Der Check erzeugt standardmaessig drei stabile Checkmk-Services:

BizTalk Suspended Instances
BizTalk Host Instances
BizTalk Runtime Artifacts

BizTalk Suspended Instances

Statuslogik:

OK: keine suspendierten Instanzen
WARN: mindestens eine resumable suspendierte Instanz
CRIT: mindestens eine non-resumable suspendierte Instanz
UNKNOWN: WMI-Zugriff, Konfiguration oder Laufzeitfehler

Metriken:

biztalk_suspended_total
biztalk_suspended_resumable
biztalk_suspended_nonresumable

Die betroffenen BizTalk-Anwendungen stehen in der Checkmk-Summary, z.B. ApplicationA R=2 NR=0; ApplicationB R=0 NR=1.

BizTalk Host Instances

Statuslogik:

OK: alle Host-Instanzen sind Started
WARN: Host-Instanzen sind in StartPending oder StopPending
CRIT: mindestens eine Host-Instanz ist Stopped oder hat einen unbekannten Zustand
UNKNOWN: WMI liefert keine Host-Instanzen

Metriken:

biztalk_host_instances_total
biztalk_host_instances_started
biztalk_host_instances_stopped
biztalk_host_instances_pending
biztalk_host_instances_unknown

Die Summary zeigt Gesamtzahlen und bis zu 12 nicht gestartete Host-Instanzen im Format Host@Server=Status.

BizTalk Runtime Artifacts

Dieser Service ist standardmaessig informativ (OK), solange keine unbekannten WMI-Zustaende auftreten. Grund: deaktivierte Receive Locations, gestoppte Send Ports oder gestoppte Orchestrations koennen in BizTalk fachlich beabsichtigt sein.

Statuslogik:

OK: Artefaktstatus lesbar, keine unbekannten Statuswerte
CRIT: Send Ports oder Orchestrations haben unbekannte WMI-Statuswerte
Optional WARN: wenn AlertOnArtifactRuntimeIssues=true und deaktivierte/inaktive Artefakte gefunden werden

Metriken:

biztalk_applications
biztalk_receive_locations, biztalk_receive_locations_disabled
biztalk_send_ports, biztalk_send_ports_started, biztalk_send_ports_stopped, biztalk_send_ports_bound, biztalk_send_ports_unknown
biztalk_orchestrations, biztalk_orchestrations_started, biztalk_orchestrations_stopped, biztalk_orchestrations_bound, biztalk_orchestrations_unbound, biztalk_orchestrations_unknown

Die Summary ist bewusst bereits lesbar formatiert und enthaelt Abschnittstrenner, z.B. ReceiveLocations total=20, disabled=1 | SendPorts ... | Notable apps: ....

Build

Voraussetzungen auf dem Build-Host:

Windows
Visual Studio Build Tools oder Visual Studio mit MSBuild
.NET Framework 4.6.1 Developer Pack

Build:

scripts\build-release.cmd

Deployment-Ordner erzeugen:

scripts\package-release.cmd

Das Ergebnis liegt unter artifacts\BizTalkSuspendedInstancesCheck-deploy.

Der Gitea-Workflow .gitea/workflows/build.yml fuehrt denselben Release-Build und die Paketierung aus.

Wie Checkmk den Check ausfuehrt

Checkmk ruft unser C#-Programm nicht direkt per zentraler Checkmk-Regel auf. Der Checkmk Windows Agent startet lokale Checks auf dem BizTalk-Server automatisch aus dem lokalen Agent-Verzeichnis:

%ProgramData%\checkmk\agent\local

Dort muss eine ausfuehrbare Datei liegen. Fuer diesen Check ist das der bereits mitgelieferte Wrapper:

%ProgramData%\checkmk\agent\local\biztalk_suspended_instances.cmd

Der Wrapper startet anschliessend die eigentliche EXE:

%ProgramData%\checkmk\agent\local\BizTalkSuspendedInstancesCheck\BizTalkSuspendedInstancesCheck.exe

Zielstruktur auf dem BizTalk-Server:

%ProgramData%\checkmk\agent\local\biztalk_suspended_instances.cmd
%ProgramData%\checkmk\agent\local\BizTalkSuspendedInstancesCheck\BizTalkSuspendedInstancesCheck.exe
%ProgramData%\checkmk\agent\local\BizTalkSuspendedInstancesCheck\BizTalkSuspendedInstancesCheck.exe.config

Der Ablauf ist:

Checkmk Windows Agent startet biztalk_suspended_instances.cmd.
Die .cmd sucht die EXE im Unterordner BizTalkSuspendedInstancesCheck.
Die EXE liest BizTalk per WMI.
Die EXE schreibt Checkmk-Local-Check-Zeilen nach STDOUT.
Der Checkmk Agent liefert diese Zeilen an den Checkmk Server.
Nach Service Discovery erscheinen die Services in Checkmk.

Das Skript muss also nicht mehr neu erstellt werden. Es liegt im Repository unter deployment\checkmk\biztalk_suspended_instances.cmd und wird beim Paketieren in den Deployment-Ordner kopiert. Falls die EXE fehlt, gibt die .cmd eine gueltige UNKNOWN-Zeile aus, damit ein unvollstaendiges Deployment in Checkmk sichtbar wird.

Deployment auf BizTalk-Server

Release bauen oder aus Gitea-Artefakt laden.
Inhalt von artifacts\BizTalkSuspendedInstancesCheck-deploy nach %ProgramData%\checkmk\agent\local kopieren.
Auf dem BizTalk-Server als lokaler Administrator testen:

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

Agentenausgabe pruefen:

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

In Checkmk Service Discovery fuer den Host ausfuehren und den Service aufnehmen.

Konfiguration

Die Datei BizTalkSuspendedInstancesCheck.exe.config kann neben der EXE angepasst werden.

Wichtige Werte:

ServiceName: Checkmk-Service-Name
HostInstancesServiceName: Service-Name fuer Host-Instanzen
RuntimeArtifactsServiceName: Service-Name fuer Artefaktstatus
Server: leer oder . fuer lokalen Server
WarnResumableThreshold: Default 1
CritNonResumableThreshold: Default 1
QueryTimeoutSeconds: Default 25
MaxApplicationDetails: Anzahl Anwendungen in der Summary, Default 12
MaxRuntimeApplicationDetails: Anzahl auffaelliger Anwendungen in der Runtime-Summary, Default 10
AlertOnStoppedHostInstances: Host-Instanzen mit Status Stopped/unbekannt alarmieren, Default true
AlertOnArtifactRuntimeIssues: deaktivierte/inaktive Artefakte als WARN werten, Default false
EmitPerApplicationServices: optional zusaetzliche Services pro Anwendung fuer Suspensions, Default false

Gitea

Das Verzeichnis ist als eigenes Git-Repository mit Branch main angelegt. Fuer ein neues Gitea-Repository:

git remote add origin <gitea-url>
git add .
git commit -m "Add BizTalk Checkmk local check"
git push -u origin main

Quellen

Checkmk Local Checks: https://docs.checkmk.com/latest/de/localchecks.html
Microsoft BizTalk MSBTS_ServiceInstance: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-wmi
Microsoft BizTalk ServiceStatus: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-servicestatus-property-wmi