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:

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

In diesem Verzeichnis liegt unser mitgelieferter Wrapper:

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

Der Wrapper ruft die eigentliche C#-EXE auf:

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

Die vollstaendige Zielstruktur ist:

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

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

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

Agentenausgabe pruefen:

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

## WMI-Abfragen

Primaere Abfrage:

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

Statuswerte:

- `4`: Suspended (resumable)
- `32`: Suspended (not resumable)

Weitere Betriebsabfragen:

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

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

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

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

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

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