biztalk-suspended-instances-localcheck/Dokumentation.md

Dokumentation: BizTalk Runtime Checkmk Local Check

Ziel

Der Check beantwortet fuer den lokalen BizTalk-Server:

• Gibt es suspendierte BizTalk-Service-Instanzen?
• Sind sie resumable oder non-resumable?
• Welche BizTalk-Anwendungen sind betroffen?
• Sind BizTalk Host-Instanzen gestartet?
• Wie ist der aggregierte Laufzeitstatus wichtiger BizTalk-Artefakte?

Er ist fuer Checkmk Windows Agent Local Checks gebaut und benoetigt keine PowerShell.

Architektur

Komponenten:

• BizTalkSuspendedInstancesCheck.exe: C#/.NET-Framework-Konsolenprogramm
• BizTalkSuspendedInstancesCheck.exe.config: Konfiguration
• biztalk_suspended_instances.cmd: Checkmk-Wrapper fuer %ProgramData%\checkmk\agent\local

Laufzeitfluss:

1. Checkmk Windows Agent ruft biztalk_suspended_instances.cmd auf.
2. Der Wrapper startet die EXE.
3. Die EXE fragt root\MicrosoftBizTalkServer per WMI ab.
4. Die EXE schreibt mehrere Checkmk-konforme Local-Check-Zeilen nach STDOUT.

Die Anwendung gibt selbst bei Fehlern eine syntaktisch gueltige Checkmk-Zeile aus. Dadurch wird der Monitoring-Zustand UNKNOWN sichtbar, statt den Agenten still zu stoeren.

Ausfuehrung durch Checkmk

Der Check wird als Checkmk Local Check betrieben. Das bedeutet: Checkmk fuehrt auf dem BizTalk-Server keine zentrale Abfrage gegen BizTalk aus, sondern der Checkmk Windows Agent startet lokal abgelegte Checks und sammelt deren STDOUT ein.

Der relevante Agent-Pfad auf Windows ist:

%ProgramData%\checkmk\agent\local

In diesem Verzeichnis liegt unser mitgelieferter Wrapper:

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

Der Wrapper ruft die eigentliche C#-EXE auf:

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

Die vollstaendige Zielstruktur ist:

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

Das Aufrufskript muss nicht separat neu entwickelt werden. Es ist Bestandteil dieses Repositories:

deployment\checkmk\biztalk_suspended_instances.cmd

Beim Paketieren mit scripts\package-release.cmd wird dieses Skript in den Deployment-Ordner kopiert. Der Inhalt von artifacts\BizTalkSuspendedInstancesCheck-deploy kann komplett nach %ProgramData%\checkmk\agent\local kopiert werden.

Der technische Ablauf ist:

1. Checkmk Windows Agent startet biztalk_suspended_instances.cmd.
2. Die .cmd sucht BizTalkSuspendedInstancesCheck.exe zuerst im Unterordner BizTalkSuspendedInstancesCheck.
3. Falls die EXE dort nicht liegt, sucht die .cmd die EXE direkt neben dem Skript.
4. Falls die EXE nicht gefunden wird, erzeugt die .cmd eine gueltige Checkmk-Zeile mit Status UNKNOWN.
5. Falls die EXE gefunden wird, fragt sie BizTalk per WMI ab.
6. Die EXE schreibt die Checkmk-Services nach STDOUT.
7. Der Checkmk Agent nimmt diese Zeilen in seine Agentenausgabe auf.
8. Nach Checkmk Service Discovery koennen die Services uebernommen werden.

Manueller Test auf dem BizTalk-Server:

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

Agentenausgabe pruefen:

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

WMI-Abfragen

Primaere Abfrage:

SELECT * FROM MSBTS_ServiceInstance WHERE ServiceStatus = 4 OR ServiceStatus = 32

Statuswerte:

• 4: Suspended (resumable)
• 32: Suspended (not resumable)

Weitere Betriebsabfragen:

SELECT * FROM MSBTS_HostInstance
SELECT * FROM MSBTS_ReceiveLocation
SELECT * FROM MSBTS_SendPort
SELECT * FROM MSBTS_Orchestration

Aus Betriebssicht werden damit folgende Risiken sichtbar:

• Gestoppte oder haengende Host-Instanzen.
• Deaktivierte Receive Locations.
• Nicht gestartete Send Ports.
• Nicht gestartete oder nicht gebundene Orchestrations.
• Unbekannte WMI-Statuswerte, die auf Versions-/Schemaabweichungen oder Lesefehler hindeuten koennen.

Zur Zuordnung der Anwendung wird zuerst versucht, eine Anwendungs-Property direkt aus der Service-Instanz zu lesen. Falls BizTalk diese nicht liefert, baut der Check einen lokalen Index ueber bekannte BizTalk-Artefakte:

• MSBTS_SendPort
• MSBTS_ReceivePort
• MSBTS_ReceiveLocation
• MSBTS_Orchestration

Wenn keine Zuordnung moeglich ist, erscheint die Instanz unter (Unknown Application). Das ist absichtlich kein Fehler, weil BizTalk nicht fuer jede Instanz eine direkte Anwendungseigenschaft liefern muss.

Checkmk-Ausgabe

Der Check gibt standardmaessig drei stabile Services aus. Es werden keine dynamischen Services pro Anwendung erzeugt, damit Checkmk Service Discovery stabil bleibt.

Beispiel ohne Befund:

0 "BizTalk Suspended Instances" biztalk_suspended_total=0;;;0|biztalk_suspended_resumable=0;1;;0|biztalk_suspended_nonresumable=0;;1;0 No suspended BizTalk service instances found.
0 "BizTalk Host Instances" biztalk_host_instances_total=4;;;0|biztalk_host_instances_started=4;;;0|biztalk_host_instances_stopped=0;;;0|biztalk_host_instances_pending=0;;;0|biztalk_host_instances_unknown=0;;;0 total=4, started=4, stopped=0, pending=0, unknown=0
0 "BizTalk Runtime Artifacts" biztalk_applications=6;;;0|biztalk_receive_locations=20;;;0|biztalk_receive_locations_disabled=0;;;0|biztalk_send_ports=30;;;0|biztalk_send_ports_started=30;;;0|biztalk_send_ports_stopped=0;;;0|biztalk_send_ports_bound=0;;;0|biztalk_send_ports_unknown=0;;;0|biztalk_orchestrations=12;;;0|biztalk_orchestrations_started=12;;;0|biztalk_orchestrations_stopped=0;;;0|biztalk_orchestrations_bound=0;;;0|biztalk_orchestrations_unbound=0;;;0|biztalk_orchestrations_unknown=0;;;0 applications=6 | ReceiveLocations total=20, disabled=0 | SendPorts total=30, started=30, stopped=0, bound=0, unknown=0 | Orchestrations total=12, started=12, stopped=0, bound=0, unbound=0, unknown=0

Beispiel mit non-resumable Instanz:

2 "BizTalk Suspended Instances" biztalk_suspended_total=3;;;0|biztalk_suspended_resumable=2;1;;0|biztalk_suspended_nonresumable=1;;1;0 3 suspended BizTalk service instance(s): resumable=2, nonresumable=1, applications=2. ApplicationA R=2 NR=0; ApplicationB R=0 NR=1

Beispiel fuer Host-Instanzen:

2 "BizTalk Host Instances" biztalk_host_instances_total=4;;;0|biztalk_host_instances_started=3;;;0|biztalk_host_instances_stopped=1;;;0|biztalk_host_instances_pending=0;;;0|biztalk_host_instances_unknown=0;;;0 total=4, started=3, stopped=1, pending=0, unknown=0 | Not started: ProcessingHost@BIZTALK01=Stopped

Beispiel fuer Artefaktstatus:

0 "BizTalk Runtime Artifacts" biztalk_applications=6;;;0|biztalk_receive_locations=20;;;0|biztalk_receive_locations_disabled=1;;;0|biztalk_send_ports=30;;;0|biztalk_send_ports_started=28;;;0|biztalk_send_ports_stopped=2;;;0|biztalk_send_ports_bound=0;;;0|biztalk_send_ports_unknown=0;;;0|biztalk_orchestrations=12;;;0|biztalk_orchestrations_started=11;;;0|biztalk_orchestrations_stopped=1;;;0|biztalk_orchestrations_bound=0;;;0|biztalk_orchestrations_unbound=0;;;0|biztalk_orchestrations_unknown=0;;;0 applications=6 | ReceiveLocations total=20, disabled=1 | SendPorts total=30, started=28, stopped=2, bound=0, unknown=0 | Orchestrations total=12, started=11, stopped=1, bound=0, unbound=0, unknown=0 | Notable apps: ApplicationA RL disabled=1, SP stopped/bound/unknown=2/0/0, Orch stopped/bound/unbound/unknown=1/0/0/0

Schwellwerte

Default:

• Resumable ab 1: WARN
• Non-resumable ab 1: CRIT
• Host-Instanz Stopped oder unbekannt: CRIT
• Host-Instanz StartPending oder StopPending: WARN
• Artefakte mit unbekanntem Status: CRIT
• Deaktivierte/inaktive Artefakte: nur Anzeige, optional WARN mit AlertOnArtifactRuntimeIssues=true

Begruendung:

• Resumable Suspensions sind stoerungsrelevant, aber potentiell wiederaufnehmbar.
• Non-resumable Suspensions verlangen normalerweise manuelle Bereinigung oder fachliche Analyse und werden daher kritisch bewertet.
• Gestoppte Host-Instanzen wirken direkt auf die Verarbeitung und werden daher kritisch bewertet.
• Deaktivierte Receive Locations, gestoppte Send Ports und gestoppte Orchestrations koennen gewollt sein; deshalb werden sie zuerst als Betriebsinformation ausgegeben.

Betrieb

Empfohlener Installationspfad:

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

Der Wrapper sucht die EXE zuerst im Unterordner BizTalkSuspendedInstancesCheck und danach direkt neben der .cmd. Damit funktioniert sowohl eine saubere Unterordner-Installation als auch ein flaches Deployment.

Nach Aenderungen an den Service-Namen muss in Checkmk eine erneute Service Discovery erfolgen. Reine Schwellwert- oder Anzeigeaenderungen brauchen keine neue Discovery.

Rechte

Der Check muss unter dem Konto des Checkmk Windows Agent auf dem BizTalk-Server WMI-Leserechte fuer root\MicrosoftBizTalkServer haben. In der Praxis ist das meist LocalSystem oder ein dediziertes Agent-Servicekonto mit lokalen Rechten.

Resilienz

• Keine PowerShell-Abhaengigkeit.
• Keine BizTalk-Assembly-Abhaengigkeit im Build.
• UTF-8-Ausgabe wird in der EXE gesetzt.
• WMI-Timeout ist konfigurierbar.
• Fehler erzeugen UNKNOWN statt leerer Ausgabe.
• Artefakt-Index ist best effort; fehlende Anwendungszuordnung verhindert den Status nicht.
• Ein stabiler Checkmk-Service vermeidet Service-Discovery-Flapping bei wechselnden Anwendungsnamen.
• Runtime-Artefakte werden aggregiert und begrenzt ausgegeben, damit Checkmk-Summaries lesbar bleiben.

Konfiguration

Wichtige appSettings:

• ServiceName: Service fuer suspendierte Instanzen.
• HostInstancesServiceName: Service fuer Host-Instanzen.
• RuntimeArtifactsServiceName: Service fuer Artefaktstatus.
• MaxApplicationDetails: maximale Anzahl Anwendungen in der Suspensions-Summary.
• MaxRuntimeApplicationDetails: maximale Anzahl auffaelliger Anwendungen in der Runtime-Summary.
• AlertOnStoppedHostInstances: Host-Instanz-Abweichungen alarmieren.
• AlertOnArtifactRuntimeIssues: deaktivierte/inaktive Artefakte als WARN werten.
• EmitPerApplicationServices: zusaetzliche Suspensions-Services pro Anwendung erzeugen. Nur verwenden, wenn dynamische Services in Checkmk gewuenscht sind.

Gitea

Das Repository enthaelt .gitea/workflows/build.yml. Der Workflow erwartet einen Windows Runner mit Visual Studio Build Tools und .NET Framework 4.6.1 Developer Pack.

Wenn euer Gitea Runner anders gelabelt ist, runs-on in .gitea/workflows/build.yml anpassen.