Initial commit for the biztalk suspended isntances local check
build / build (push) Has been cancelled
build / build (push) Has been cancelled
This commit is contained in:
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user