Expand BizTalk operational metrics

2026-07-30 16:15:20 +02:00
parent d15bb6539b
commit 826d87fef7
17 changed files with 859 additions and 239 deletions
@@ -12,7 +12,7 @@ Verbindliche Randbedingungen:

 - Der Checkmk Windows Agent bleibt `LocalSystem`.
 - `LocalSystem` erhaelt keine BizTalk-/SQL-Gruppenmitgliedschaft.
- Ein separates Dienstkonto oder bevorzugt gMSA sammelt minuetlich.
+- Ein normales dediziertes AD-Servicekonto sammelt minuetlich.
 - Der Agentpfad fuehrt niemals WMI- oder SQL-Abfragen aus.
 - Fehler muessen als gueltige Checkmk-`UNKNOWN`-Services sichtbar werden.
 - Schreiben und Lesen duerfen nie einen halben Snapshot exponieren.
@@ -46,7 +46,7 @@ Konto.
                       Privilegierte Zone
 ┌──────────────────────────────────────────────────────────────┐
 │ Task Scheduler: "BizTalk Checkmk Pulse Provider"             │
-│ Konto: DOMAIN\svc_biztalk_cmk$ (gMSA empfohlen)              │
+│ Konto: DOMAIN\svc_biztalk_cmk (RunLevel Limited)             │
 │ Intervall: 1 Minute, IgnoreNew, Laufzeitlimit 5 Minuten       │
 │                                                              │
 │ BizTalkCheckmkPulse.exe --collect                             │
@@ -89,7 +89,7 @@ Ablauf:
 2. Tageslogs gemaess `LogRetentionDays` bereinigen.
 3. exklusives Handle auf `<SnapshotPath>.provider.lock` halten.
 4. WMI-, SQL- und Event-Log-Probes ausfuehren.
-5. sechs stabile und optionale dynamische Checkmk-Zeilen formatieren.
+5. acht stabile und optionale dynamische Checkmk-Zeilen formatieren.
 6. Snapshot in einer eindeutigen Temporaerdatei desselben Verzeichnisses
   schreiben.
 7. `Flush(true)` ausfuehren und Temporaerdatei atomar publizieren.
@@ -132,19 +132,19 @@ Der Consumer:
 - gibt bei Erfolg ausschliesslich den validierten Payload aus.

 Er gibt immer Exitcode `0` zurueck, damit ein Fehler die komplette
-Checkmk-Agentsektion nicht zerstoert. Jede Ablehnung erzeugt sechs
+Checkmk-Agentsektion nicht zerstoert. Jede Ablehnung erzeugt acht
 `UNKNOWN`-Zeilen und einen Eintrag im Consumer-Log.

 ## 4. Snapshot-Vertrag

-Version 1:
+Version 2:

 ```text
-BIZTALK_CHECKMK_PULSE_SNAPSHOT_V1
+BIZTALK_CHECKMK_PULSE_SNAPSHOT_V2
 generatedUtc=2026-07-30T12:34:56.1234567Z
 machineBase64=QVYyM0FHUFdCSU8x
 identityBase64=QkVXXHN2Y19iaXp0YWxrX2NtayQ=
-payloadLines=6
+payloadLines=8
 payloadSha256=<64 hex characters>

 0 "BizTalk Platform" - ...
@@ -202,7 +202,37 @@ Pflichtklassen:
 Hostnamen werden clientseitig verglichen. Sonderzeichen und FQDN-/Kurzname
 gelangen nicht in dynamisch erzeugte WQL-Filter.

-### 5.2 SQL-Zugriffsprobe
+`MSBTS_ServiceInstance` wird fuer `ServiceStatus=4` (resumable),
+`ServiceStatus=32` (non-resumable) und `ServiceClass=64` abgefragt.
+`ServiceClass=64` kennzeichnet Routing Failure Reports. Sie werden als eigene
+Metrik ausgewiesen und zugleich in `suspended_nonresumable` mitgezaehlt.
+
+### 5.2 Kompaktes Checkmk-Servicebild
+
+Die alte Sammelzeile `BizTalk Runtime Artifacts` wurde durch drei kurze
+Services ersetzt. Insgesamt entstehen acht stabile Services:
+
+1. `BizTalk Platform`
+2. `BizTalk SQL Access`
+3. `BizTalk Suspended Instances`
+4. `BizTalk Host Instances`
+5. `BizTalk Receive Locations`
+6. `BizTalk Send Ports`
+7. `BizTalk Orchestrations`
+8. `BizTalk Event Log`
+
+Receive Locations und Send Ports alarmieren nur fuer unerwartete
+Aus-Zustaende. Fachlich bewusst deaktivierte Namen werden exakt, ohne
+Wildcards, in `ExpectedDisabledReceiveLocations` beziehungsweise
+`ExpectedInactiveSendPorts` hinterlegt. Ein Eintrag ist entweder nur der Name
+oder `Anwendung\Name`.
+
+Pro Summary werden maximal `MaxSummaryItems` Treffer angezeigt. Weitere
+Artefakte werden als `(+n more)` zusammengefasst. `MaxDetailCharacters`
+begrenzt jede Detailausgabe, damit Checkmk-Ansichten kompakt bleiben, waehrend
+alle numerischen Metriken vollstaendig erhalten bleiben.
+
+### 5.3 SQL-Zugriffsprobe

 Der Provider oeffnet fuer Management- und Master-MessageBox-Datenbank eine
 kurze `System.Data.SqlClient`-Verbindung mit integrierter
@@ -213,7 +243,7 @@ Die Ausgabe `execution_identity=` zeigt deshalb das Provider-Konto, nicht mehr
 `NT AUTHORITY\SYSTEM`. Der Check beweist, dass genau das Scheduled-Task-Konto
 die Ziele erreichen kann.

-### 5.3 Event Log
+### 5.4 Event Log

 Der Provider liest das lokale Application Log im konfigurierten Zeitfenster
 und filtert Quellen wie `BizTalk Server`, `XLANG/s`, `ENTSSO`,
@@ -286,14 +316,17 @@ Sollkonfiguration:
 | Programm | `%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe` |
 | Argument | `--collect` |
 | Arbeitsverzeichnis | `%ProgramFiles%\BizTalkCheckmkPulse` |
-| Benutzer | dediziertes Dienstkonto oder gMSA |
+| Benutzer | normales dediziertes AD-Servicekonto |
+| Run level | `Limited`; keine lokale Administratorrolle erforderlich |
 | Mehrfachinstanzen | `IgnoreNew` |
 | Laufzeitlimit | 5 Minuten |
 | StartWhenAvailable | aktiv |
 | Restart | zweimal im Minutenabstand |

-Der Task wird mit gespeichertem Dienstkontokennwort beziehungsweise gMSA
-ausgefuehrt, also unabhaengig von einer interaktiven Anmeldung.
+Der Task wird mit gespeichertem Dienstkontokennwort ausgefuehrt, also
+unabhaengig von einer interaktiven Anmeldung. Bei Kennwortwechsel oder
+-ablauf muss das Task-Kennwort aktualisiert werden. Ein gMSA ist weiterhin
+optional unterstuetzt, aber nicht die produktive Standardannahme.

 ## 8. Installation

@@ -304,25 +337,7 @@ scripts\test-release.cmd
 scripts\package-release.cmd
 ```

-### 8.2 gMSA
-
-Voraussetzungen:
-
-1. gMSA in AD erstellen und Abrufrecht auf den BizTalk-Server begrenzen.
-2. Konto lokal installieren und mit `Test-ADServiceAccount` pruefen.
-3. gMSA in die exakt konfigurierte BizTalk-Read-Only-Gruppe aufnehmen.
-4. AD-Replikation abwarten.
-
-Installation:
-
-```powershell
-.\Install-BizTalkCheckmkPulse.ps1 `
-    -CollectorAccount 'BEW\svc_biztalk_cmk$' `
-    -Gmsa `
-    -EnvironmentName ACC
-```
-
-### 8.3 regulaeres Dienstkonto
+### 8.2 Normales Servicekonto

 ```powershell
 .\Install-BizTalkCheckmkPulse.ps1 `
@@ -333,6 +348,19 @@ Installation:
 Der Installer muss als lokaler Administrator laufen. Er vergibt keine
 AD-/BizTalk-/SQL-Rechte; diese bleiben getrennte administrative Freigaben.

+Der installierte Task selbst laeuft mit `RunLevel Limited`. Der Installer fragt
+das Kennwort mit `Get-Credential` ab; es wird nicht in Config oder Log
+geschrieben. Das Konto benoetigt `Log on as a batch job`.
+
+### 8.3 Optionales gMSA
+
+```powershell
+.\Install-BizTalkCheckmkPulse.ps1 `
+    -CollectorAccount 'BEW\svc_biztalk_cmk$' `
+    -Gmsa `
+    -EnvironmentName ACC
+```
+
 ### 8.4 Checkmk

 Der installierte Wrapper liegt unter:
@@ -350,7 +378,8 @@ Snapshot nicht zusaetzlich verzoegert.
 Nach dem Agent-Dump:

 1. Service Discovery fuer den BizTalk-Host ausfuehren.
-2. sechs stabile Services aufnehmen.
+2. acht stabile Services aufnehmen; den alten Service
+   `BizTalk Runtime Artifacts` nach erfolgreicher Discovery entfernen.
 3. Changes aktivieren.
 4. Views/Benachrichtigungen nach Umgebung konfigurieren.

@@ -368,6 +397,12 @@ einzeilige Nachricht. Provider-Erfolge werden pro Lauf geloggt; der Consumer
 loggt nur abgelehnte Snapshots. Exceptions werden mit Typ, Nachricht,
 HRESULT-/Providerdetails und Stacktrace einzeilig gespeichert.

+Der erfolgreiche Abschluss nennt Suspensions, Routing Failure Reports,
+Receive-Location-/Send-Port-Zahlen und Laufzeit. Jede strukturierte
+WMI-/SQL-/Event-Log-Diagnose wird zusaetzlich als eigene `WARN`-Zeile
+protokolliert und bleibt damit auch ausserhalb der gekuerzten Checkmk-Summary
+vollstaendig nachvollziehbar.
+
 Logging ist best effort: Ein blockiertes Log darf Checkmk-Ausgabe oder
 Snapshot-Publikation nicht zerstoeren. Der Provider entfernt beim Start Dateien
 aelter als `LogRetentionDays`.
@@ -391,7 +426,7 @@ Pruefen:
 1. Task existiert und ist aktiviert.
 2. `LastTaskResult` und Provider-Log.
 3. Dienstkonto kann sich als Batch anmelden.
-4. gMSA ist lokal installiert und abrufbar.
+4. gespeichertes Task-Kennwort ist nach Rotation/Ablauf noch gueltig.
 5. Provider besitzt Modify auf `data` und `logs`.
 6. EXE/Config sind ausfuehrbar.

@@ -468,7 +503,13 @@ Alarmierung:
 | --- | --- |
 | `WarnResumableThreshold` | `1` |
 | `CritNonResumableThreshold` | `1` |
-| `AlertOnArtifactRuntimeIssues` | `false` |
+| `CritRoutingFailureThreshold` | `1` |
+| `AlertOnArtifactRuntimeIssues` | `true` |
+| `ExpectedDisabledReceiveLocations` | leer; exakte Pipe-Liste |
+| `ExpectedInactiveSendPorts` | leer; exakte Pipe-Liste |
+| `AlertOnInactiveOrchestrations` | `false` |
+| `MaxSummaryItems` | `5` |
+| `MaxDetailCharacters` | `1600` |
 | `EmitPerApplicationSuspensionServices` | `false` |
 | `EventLogWarnThreshold` | `1` |
 | `EventLogCritThreshold` | `10` |
@@ -478,16 +519,20 @@ Alarmierung:
 Automatisiert:

 - Release-Build .NET Framework 4.7.2,
- exakt sechs Self-Test-Services,
+- exakt acht Self-Test-Services,
 - unbekannte Quellen werden `UNKNOWN`,
 - dynamische Anwendungsservices nur bei bekannter Anwendung,
 - WMI-Queryvertrag nutzt dokumentierte Properties,
 - eingebetteter SQL-Loginfehler wird `Permission`,
 - abgewiesener Principal wird extrahiert,
+- Routing Failure Reports werden separat und als non-resumable gezaehlt,
+- Receive-/Send-Allowlisten trennen bewusste von unerwarteten Aus-Zustaenden,
+- ein fehlender `IsDisabled`-Wert wird `UNKNOWN` statt still als enabled,
+- betroffene Namen und Gesamtlaenge der Summary bleiben begrenzt,
 - Snapshot-Roundtrip und Ersatz,
 - SHA-256-Manipulation wird verworfen,
 - Stale-Snapshot wird verworfen,
- Consumer-Fallback enthaelt sechs `UNKNOWN`-Services.
+- Consumer-Fallback enthaelt acht `UNKNOWN`-Services.

 Windows-/ACC-Abnahme:

@@ -497,10 +542,16 @@ Windows-/ACC-Abnahme:
 4. `BizTalk Platform` zeigt `read_only_group=`.
 5. `BizTalk SQL Access`: `targets=2`, `available=2`.
 6. keine Permission-`UNKNOWN`s.
-7. ACL-Test: `LocalSystem` kann Snapshot lesen, nicht schreiben.
-8. Task deaktivieren: nach 180 Sekunden sechs stale-`UNKNOWN`s.
-9. Task wieder aktivieren: naechster Snapshot stellt Echtzustand her.
-10. Agent-Dump und Checkmk Service Discovery erfolgreich.
+7. Suspensionsmetriken mit der BizTalk Group Hub Page plausibilisieren,
+   einschliesslich Routing Failure Reports.
+8. Eine bewusst deaktivierte Receive Location und einen inaktiven Send Port
+   ueber die exakten Allowlisten als expected bestaetigen.
+9. Einen Testnamen aus der Allowlist entfernen und den erwarteten CRIT mit
+   kurzem `affected=`-Detail pruefen.
+10. ACL-Test: `LocalSystem` kann Snapshot lesen, nicht schreiben.
+11. Task deaktivieren: nach 180 Sekunden acht stale-`UNKNOWN`s.
+12. Task wieder aktivieren: naechster Snapshot stellt Echtzustand her.
+13. Agent-Dump und Checkmk Service Discovery erfolgreich.

 Erst nach ACC-Abnahme erfolgt der gestufte Rollout nach DEV/TST/PRD.

@@ -537,6 +588,10 @@ ZIP und Base64 werden erst nach dem Git-Commit aus genau diesem Commit erzeugt.
 - https://learn.microsoft.com/en-us/biztalk/core/windows-groups-and-user-accounts-in-biztalk-server
 - https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-biztalkreadonlyusergroup-property-wmi
 - https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-wmi
+- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-serviceclass-property-wmi
+- https://learn.microsoft.com/en-us/biztalk/core/types-of-message-failures
+- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-receivelocation-isdisabled-property-wmi
+- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-sendport-status-property-wmi
 - https://docs.checkmk.com/latest/en/agent_windows.html
 - https://docs.checkmk.com/latest/en/localchecks.html
 - https://docs.checkmk.com/latest/en/spool_directory.html