# BizTalk Checkmk Pulse

`BizTalk Checkmk Pulse` ist ein lokaler Checkmk-Check fuer Microsoft BizTalk Server 2020 auf Windows. Er liest BizTalk-Betriebsdaten ueber WMI aus `root\MicrosoftBizTalkServer`, erzeugt Checkmk-Local-Check-Ausgaben und kann dadurch ohne serverseitigen Python-Check in Checkmk 2.4 integriert werden.

Der Ansatz ist fuer Umgebungen wie `ACC`, `DEV`, `TST` und `PRD` gedacht, in denen pro Umgebung ein BizTalk Server 2020 und ein SQL Server betrieben werden. SQL Server bleibt beim mitgelieferten Checkmk-MSSQL-Plugin; dieses Projekt ergaenzt die BizTalk-spezifische Sicht.

## Warum Local Check statt serverseitigem Check-Plugin?

Checkmk 2.4 kann Windows-Agent-Plugins und Local Checks direkt ausfuehren. Fuer diese Umgebung ist ein C#/.NET-Framework-Programm mit `.cmd`-Wrapper die robusteste Variante:

- keine PowerShell-Ausfuehrung erforderlich
- keine BizTalk-ExplorerOM/OperationsOM-DLL als Build-Abhaengigkeit
- keine Python-Check-API-Abhaengigkeit auf der Checkmk-Site
- einfache Verteilung auf die BizTalk-Maschinen per Dateiablage, Softwareverteilung oder Agent Bakery
- automatische Service Discovery in Checkmk

## Erzeugte Checkmk-Services

Standardmaessig entstehen diese stabilen Services:

- `BizTalk Platform`
- `BizTalk Suspended Instances`
- `BizTalk Host Instances`
- `BizTalk Runtime Artifacts`
- `BizTalk Event Log`

Wenn `EnvironmentName=ACC`, `DEV`, `TST` oder `PRD` gesetzt wird, wird der Name vor den Suffix gesetzt, z.B. `BizTalk PRD Suspended Instances`. Das ist praktisch, wenn die Umgebung bereits im Hostnamen oder Ordner abgebildet ist, aber nicht zwingend noetig.

Details zu Statuslogik und Metriken stehen in [docs/CheckmkServices.md](docs/CheckmkServices.md).
Beispielausgaben stehen in [docs/ExampleOutput.md](docs/ExampleOutput.md).

## Build

Voraussetzungen auf einem Windows-Build-Host:

- Visual Studio 2022 Build Tools oder Visual Studio
- MSBuild im `PATH`
- .NET Framework 4.7.2 Developer Pack

Build:

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

Deployment-Paket erstellen:

```cmd
scripts\package-release.cmd
```

Ergebnis:

```text
artifacts\BizTalkCheckmkPulse-deploy\
  biztalk_checkmk_pulse.cmd
  BizTalkCheckmkPulse\
    BizTalkCheckmkPulse.exe
    BizTalkCheckmkPulse.exe.config
```

Validierung nach dem Build:

```cmd
artifacts\BizTalkCheckmkPulse-deploy\biztalk_checkmk_pulse.cmd --self-test
```

## Installation auf dem BizTalk-Server

Kopiere den Inhalt von `artifacts\BizTalkCheckmkPulse-deploy` nach:

```text
%ProgramData%\checkmk\agent\local
```

Zielstruktur:

```text
%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config
```

Manueller Test auf dem BizTalk-Server:

```cmd
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd" --self-test
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"
```

Agent-Ausgabe wie Checkmk sie sieht:

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

Danach in Checkmk fuer den BizTalk-Host eine Service Discovery ausfuehren, die neuen Services aufnehmen und Changes aktivieren.

## Konfiguration

Die Konfiguration liegt neben der EXE:

```text
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config
```

Wichtige Werte:

| Key | Default | Bedeutung |
| --- | --- | --- |
| `Server` | `.` | Lokaler BizTalk-Server. Remote-WMI ist moeglich, aber nicht empfohlen. |
| `ServicePrefix` | `BizTalk` | Prefix fuer alle Checkmk-Services. |
| `EnvironmentName` | leer | Optional `ACC`, `DEV`, `TST` oder `PRD`. |
| `QueryTimeoutSeconds` | `25` | WMI-Timeout pro Query. |
| `WarnResumableThreshold` | `1` | WARN ab n resumable suspended instances. |
| `CritNonResumableThreshold` | `1` | CRIT ab n non-resumable suspended instances. |
| `AlertOnArtifactRuntimeIssues` | `false` | Wenn `true`, werden deaktivierte Receive Locations und inaktive Ports/Orchestrations als WARN gewertet. |
| `EmitPerApplicationSuspensionServices` | `false` | Erzeugt zusaetzliche Services pro Anwendung mit Suspensions. |
| `ProbeEventLog` | `true` | Liest das Windows Application Log nach BizTalk-bezogenen Sources. |
| `EventLogLookbackMinutes` | `60` | Zeitraum fuer Event-Log-Auswertung. |
| `EventLogWarnThreshold` | `1` | WARN ab n Errors oder Warnings. |
| `EventLogCritThreshold` | `10` | CRIT ab n Errors. |

Empfehlung:

- In `DEV`, `TST`, `ACC`: `AlertOnArtifactRuntimeIssues=false`, damit bewusst gestoppte Artefakte nicht rauschen.
- In `PRD`: erst zwei Wochen beobachten; danach nur aktivieren, wenn die Runtime-Artefakte wirklich als Betriebsstandard immer aktiv sein muessen.
- `EmitPerApplicationSuspensionServices=true` nur verwenden, wenn Anwendungsteams eigene Services benoetigen. Sonst bleibt die Discovery schlanker.

## Integration in Checkmk Managed Services Edition 2.4

Manuelle Integration:

1. Dateien auf dem BizTalk-Server nach `%ProgramData%\checkmk\agent\local` kopieren.
2. Optional `BizTalkCheckmkPulse.exe.config` je Umgebung anpassen.
3. Agent-Dump pruefen.
4. Service Discovery auf dem BizTalk-Host ausfuehren.
5. Services in ein BizTalk-Dashboard aufnehmen.

Integration ueber Agent Bakery:

1. Deployment-Dateien in der Checkmk-Site als Custom-Agent-Dateien bereitstellen.
2. Windows-Agent-Regel fuer die BizTalk-Hosts erstellen.
3. Agent backen und auf ACC/DEV/TST/PRD-BizTalk-Hosts ausrollen.
4. Discovery und Dashboard-Aufnahme durchfuehren.

Die Checkmk-Dokumentation nennt fuer Windows Local Checks `%ProgramData%\checkmk\agent\local` und fuer Windows Agent Plugins `%ProgramData%\checkmk\agent\plugins`. Dieses Projekt nutzt bewusst `local`, weil der Zustand direkt vom Host berechnet und sofort als Checkmk-Service geliefert wird.

## Quellen

- Checkmk Local Checks: https://docs.checkmk.com/latest/en/localchecks.html
- Checkmk Windows Agent und Plugin-Pfade: https://docs.checkmk.com/latest/en/agent_windows.html
- Checkmk Agent-Based Plugin-Entwicklung: https://docs.checkmk.com/latest/en/devel_check_plugins.html
- Checkmk Bakery API: https://docs.checkmk.com/latest/en/bakery_api.html
- Checkmk MKP-Pakete: https://docs.checkmk.com/latest/en/mkps.html
- Microsoft BizTalk WMI `MSBTS_ServiceInstance`: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-wmi
- Microsoft BizTalk WMI `ServiceStatus`: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-servicestatus-property-wmi