biztalk-suspended-instances-localcheck/README.md

# BizTalk Runtime Checkmk Local Check

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:

```cmd
scripts\build-release.cmd
```

Deployment-Ordner erzeugen:

```cmd
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:

```cmd
%ProgramData%\checkmk\agent\local
```

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

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

Der Wrapper startet anschliessend die eigentliche EXE:

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

Zielstruktur auf dem BizTalk-Server:

```text
%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:

1. Checkmk Windows Agent startet `biztalk_suspended_instances.cmd`.
2. Die `.cmd` sucht die EXE im Unterordner `BizTalkSuspendedInstancesCheck`.
3. Die EXE liest BizTalk per WMI.
4. Die EXE schreibt Checkmk-Local-Check-Zeilen nach STDOUT.
5. Der Checkmk Agent liefert diese Zeilen an den Checkmk Server.
6. 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

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

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

4. Agentenausgabe pruefen:

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

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

```cmd
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