# Dokumentation: BizTalk Checkmk Pulse

## Zielbild

Ziel ist ein wartbares Monitoring fuer BizTalk Server 2020 in den Umgebungen `ACC`, `DEV`, `TST` und `PRD`. Jede Umgebung besitzt einen BizTalk Server 2020 und einen SQL Server. SQL Server wird mit dem Checkmk-eigenen MSSQL-Plugin ueberwacht; fuer BizTalk liefert dieses Projekt die fehlende fachliche und technische Laufzeitsicht.

Das Monitoring soll:

- auf jeder BizTalk-Maschine lokal laufen
- ohne PowerShell-Abhaengigkeit funktionieren
- keine BizTalk-DLLs im Build erzwingen
- Checkmk-2.4-kompatible Services und Metriken erzeugen
- service-discovery-freundlich und dashboard-tauglich sein
- bei Fehlern gueltige `UNKNOWN`-Services statt kaputter Agent-Ausgaben liefern

## Technische Bewertung

### Option A: Checkmk Local Check mit C#/.NET Framework

Bewertung: empfohlen und umgesetzt.

Vorteile:

- Checkmk 2.4 unterstuetzt Local Checks direkt.
- Windows Server mit BizTalk 2020 bringt .NET Framework in der Regel passend mit.
- `System.Management` kann BizTalk-WMI lesen.
- Keine PowerShell Execution Policy, keine Script-Signing-Frage.
- Kein serverseitiges Checkmk-Python-Plugin notwendig.
- Rollout ist eine einfache Dateiablage unter `%ProgramData%\checkmk\agent\local`.

Nachteile:

- Schwellwerte sind in der `.exe.config`, nicht als Checkmk-Regelsatz in WATO.
- Eigene Graphing-Definitionen sind nicht enthalten; Checkmk zeigt Local-Check-Metriken trotzdem als Performance-Daten und Graphen.

### Option B: Agent Plugin plus serverseitiges Checkmk-Plugin

Bewertung: technisch elegant, aber fuer den ersten produktiven Schritt schwerer.

Vorteile:

- Checkmk-Regeln, Discovery und Metrikdefinitionen koennen sauber zentral modelliert werden.
- Bessere langfristige Erweiterbarkeit als MKP.

Nachteile:

- Checkmk-Check-API-Versionen muessen enger gepflegt werden.
- Server-seitige Installation in jeder Site erforderlich.
- Mehr Aufwand fuer Managed-Services-Betrieb und Updates.

Empfehlung: als Version 2 dieses Projekts denkbar, wenn die Local-Check-Variante stabil in PRD laeuft und zentrale Regelsaetze wirklich benoetigt werden.

### Option C: PowerShell Local Check

Bewertung: nicht empfohlen fuer diese Umgebung.

Vorteile:

- Schnell zu schreiben.
- WMI/CIM-Zugriff ist komfortabel.

Nachteile:

- PowerShell ist in vielen Serverumgebungen eingeschraenkt oder signaturpflichtig.
- Ausfuehrungsverhalten im Checkmk-Agent-Kontext ist haeufiger fehleranfaellig.

### Option D: BizTalk ExplorerOM/OperationsOM

Bewertung: fachlich stark, deployseitig unnoetig schwer.

Vorteile:

- Hoehere BizTalk-Abstraktion als rohe WMI-Klassen.

Nachteile:

- BizTalk-DLL-Versionen muessen beim Build und teilweise zur Laufzeit passen.
- Build-Agenten brauchen BizTalk-Komponenten oder SDK-Dateien.
- Fuer die benoetigten Zustandsdaten reicht WMI aus.

## Architektur

```text
Checkmk Windows Agent
  |
  | startet lokale Checks aus %ProgramData%\checkmk\agent\local
  v
biztalk_checkmk_pulse.cmd
  |
  | startet
  v
BizTalkCheckmkPulse.exe
  |
  | liest lokal
  +-- WMI root\MicrosoftBizTalkServer
  +-- Windows Application Event Log
  |
  v
Checkmk Local Check Zeilen nach STDOUT
```

Der `.cmd`-Wrapper liefert auch dann eine gueltige `UNKNOWN`-Zeile, wenn die EXE fehlt. Die EXE selbst faengt Laufzeitfehler ab und schreibt fuer alle stabilen Services `UNKNOWN`, damit unvollstaendige Deployments oder WMI-Probleme in Checkmk sichtbar bleiben.

## Datenquellen

### BizTalk WMI Namespace

Namespace:

```text
root\MicrosoftBizTalkServer
```

Genutzte Klassen:

| Klasse | Zweck |
| --- | --- |
| `MSBTS_GroupSetting` | BizTalk-Gruppe und Management-DB-Hinweise. |
| `MSBTS_MessageBoxSetting` | MessageBox-DB-Hinweise. |
| `MSBTS_HostInstance` | Host-Instance-Zustand. |
| `MSBTS_ServiceInstance` | Suspended service instances. |
| `MSBTS_ReceiveLocation` | Receive-Location-Zustand. |
| `MSBTS_SendPort` | Send-Port-Zustand. |
| `MSBTS_Orchestration` | Orchestration-Zustand. |
| `MSBTS_ReceivePort` | Application-Mapping fuer Details. |

### Windows Application Event Log

Der Check liest standardmaessig das lokale Application Log fuer die letzten 60 Minuten und filtert auf Quellen wie:

- `BizTalk Server`
- `XLANG/s`
- `ENTSSO`
- `BizTalk Server Application`
- `BizTalk Server EDI`

Die Liste ist ueber `EventLogSources` konfigurierbar.

## Resilienz

Das Plugin ist bewusst defensiv gebaut:

- WMI-Queries haben ein konfigurierbares Timeout.
- Optionale WMI-Klassen erzeugen Diagnosehinweise statt Totalabbruch.
- Fehlende Properties werden als leer/unknown behandelt.
- Local-Check-Ausgaben verwenden gueltige Checkmk-Zeilen mit genau vier Feldern.
- Fatal Errors erzeugen `UNKNOWN` fuer alle stabilen Services.
- Event-Log-Auswertung ist isoliert; ein Fehler dort bricht WMI-Monitoring nicht ab.
- Service-Namen sind stabil, damit Service Discovery nicht bei jedem Lauf neue Services erzeugt.

## Statusmodell

### BizTalk Platform

- `OK`: BizTalk-WMI erreichbar.
- `UNKNOWN`: WMI nicht erreichbar oder kompletter Programmfehler.

Dieser Service ist der Integrationsindikator. Wenn er `UNKNOWN` ist, sind Berechtigungen, BizTalk-Installation oder WMI-Repository zu pruefen.

### BizTalk Suspended Instances

- `OK`: keine suspendierten Instanzen.
- `WARN`: mindestens `WarnResumableThreshold` resumable suspended instances.
- `CRIT`: mindestens `CritNonResumableThreshold` non-resumable suspended instances.
- `UNKNOWN`: Datenquelle nicht lesbar.

### BizTalk Host Instances

- `OK`: alle Host-Instanzen sind started.
- `WARN`: mindestens eine Host-Instanz ist pending.
- `CRIT`: mindestens eine Host-Instanz ist stopped oder unknown.
- `UNKNOWN`: keine Host-Instanzen gefunden oder Datenquelle nicht lesbar.

### BizTalk Runtime Artifacts

- `OK`: Artefakte lesbar, keine unbekannten Statuswerte.
- `WARN`: nur wenn `AlertOnArtifactRuntimeIssues=true` und deaktivierte/inaktive Artefakte vorhanden sind.
- `CRIT`: unbekannte Send-Port- oder Orchestration-Statuswerte.

Deaktivierte Receive Locations und gestoppte Ports koennen in BizTalk fachlich korrekt sein. Deshalb ist die Alarmierung hier standardmaessig informativ.

### BizTalk Event Log

- `OK`: keine relevanten Fehler/Warnungen ueber Schwellwert.
- `WARN`: Fehler oder Warnungen ab `EventLogWarnThreshold`.
- `CRIT`: Fehler ab `EventLogCritThreshold`.
- `UNKNOWN`: Event Log nicht lesbar.

## Dashboard-Empfehlung

Pro Umgebung sollte der BizTalk-Host in einem eigenen Host-Ordner oder Host-Tag fuer `ACC`, `DEV`, `TST`, `PRD` liegen. Im Dashboard eignen sich:

- Service State Widgets fuer die fuenf BizTalk-Services
- Graphen fuer `biztalk_suspended_total`, `biztalk_host_instances_stopped`, `biztalk_eventlog_errors`
- Hostgruppe/Ordner pro Umgebung
- Optional eine View gefiltert auf `Service starts with BizTalk`

Empfohlene Reihenfolge im Dashboard:

1. `BizTalk Platform`
2. `BizTalk Suspended Instances`
3. `BizTalk Host Instances`
4. `BizTalk Event Log`
5. `BizTalk Runtime Artifacts`
6. SQL-Server-Services aus dem Checkmk-MSSQL-Plugin

## Rollout-Vorgehen

1. Build-Paket erzeugen.
2. In `DEV` auf dem BizTalk-Server installieren.
3. `--self-test` und normalen Lauf ausfuehren.
4. Agent-Dump pruefen.
5. Checkmk Discovery durchfuehren.
6. Eine Woche Messwerte und false positives beobachten.
7. Nach `TST` und `ACC` uebernehmen.
8. In `PRD` mit `AlertOnArtifactRuntimeIssues=false` starten.
9. Nach Betriebsfreigabe Schwellwerte feinjustieren.

## Troubleshooting

### Service bleibt UNKNOWN

Pruefen:

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

Wenn WMI nicht erreichbar ist:

```cmd
wmic /namespace:\\root\MicrosoftBizTalkServer path MSBTS_HostInstance get HostName,RunningServer,ServiceState
```

Der Checkmk Windows Agent laeuft normalerweise als LocalSystem. Daher immer auch den Agent-Dump verwenden:

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

### Keine Services in Discovery

Pruefen:

- Liegt `biztalk_checkmk_pulse.cmd` direkt unter `%ProgramData%\checkmk\agent\local`?
- Gibt der Wrapper direkt eine Zeile im Format `0 "Service" metric=value Details` aus?
- Wurde der Checkmk-Agent nach Policy-/Bakery-Aenderungen neu ausgerollt?

### Runtime Artifacts zeigt deaktivierte Artefakte

Das ist standardmaessig `OK`, damit gewollt deaktivierte BizTalk-Artefakte nicht alarmieren. Fuer strengere PRD-Standards:

```xml
<add key="AlertOnArtifactRuntimeIssues" value="true" />
```

## Weiterentwicklung

Sinnvolle naechste Ausbaustufen:

- MKP mit Agent-Bakery-Regel fuer zentrale Konfiguration.
- Optionales serverseitiges Check-Plugin nach Checkmk Check API V2.
- Custom Dashboard/View als Checkmk GUI Extension.
- Ergaenzung um MessageBox-Spool/Tracking-Daten, falls operativ benoetigt.