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,226 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user