Systemüberwachung

Hintergrund

Bisher erfolgte eine Protokollierung nur in der Systemdatenbank.

Mit der Version 4.1.7 ist ein erweitertes Monitoring implementiert, welches umfangreiche Informationen zum zentralen Logserver senden kann.

Da wir für unsere eigenen Hosting Lösungen seit einiger Zeit Grafana als Überwachungssystem verwenden, ist eine Implementierung für diese Systemlandschaft erfolgt. Intern kann der Logger aber gegen andere ähnlich funktionierende Systeme ausgetauscht werden.

Sprechen Sie uns bei Bedarf dazu an. Sie finden am Ende dieser Seite eine Kurzanleitung zur Loki+Grafana Installation

Protokollierte Ereignisse

Übermittelt werden z.Z. folgende Ereignisse:

• Erfolgreiche Anmeldungen.
• Fehlgeschlagene Anmeldeversuche.
• Alle Fehlermeldungen, unterschieden nach Fehlern aus Ajax-Requests und anderen.
• Konfigurierbare Aktionen anhand von Schwellwerten für Ajax-Aktionen, abhängig von der Ausführungsdauer.
• Informationen über den Start der Web-Anwendung.
• Einträge, die via Cardo4.Env.ReportHandledError von Anwendungen erstellt werden.
• cardo4 Anwendungen, für die ein SQL Update erforderlich ist (wird einmalig beim Start von cardo ermittelt)

Übermittelte Daten

Die folgenden Beschreibung bezieht sich auf die Übermittlung an Grafana Loki.

Es werden folgende "Label" statisch erstellt:

• app: Der Name der Website, wie im IIS konfiguriert

• machineName: Der Host-Name des generierenden Servers

• level: Einer der Werte: trace, error, debug, info, warning

Alle weiteren vom System übergebenen Werte werden als JSON Objekt als Log-Line übergeben.

Die Eigenschaften des JSON Objektes sind dabei von der Art des Ereignisses abhängig.

Immer enthalten sind:

• t: Der Text der Meldung, hier sind i.d.R. keine dynamischen Werte enthalten, so dass eine Gruppierung nach dem Label möglich ist

• user: Der Anmeldename des ausführenden Nutzers

• remoteAddr: Die (evtl. geforwardete) IP Adresse des Aufrufers

Bei Ereignissen vom Typ Fehler: (Ajax und andere):

• type: .Net Typename der Exception

• stackTrace: Der Stacktrace des Fehlers

Bei Ereignissen vom Typ Anmeldungen (Erfolgreich oder Fehler):

• type: "login"

  Der Label level ist dann entweder error oder info.

Bei allen Ajax-Request (Fehler und bei definierten Schwellwerten):

• ajaxMethode: Name der Methode

• ajaxClass: Name der Klasse

  Bei Schwellwerten zusätzlich:

  • durationMs: Dauer der Aktion in Millisekunden.

Bei allen via Cardo4.Env.ReportHandledError geschriebenen:

• type: "handledError"
• affectedItem: - wie übergeben -

Ist die Option Monitoring.StoreAjaxParameters aktiviert, dann werden für die Ajax-Request ab Level "warning" auch die Argumente mit protokolliert.

Die Argumentnamen werden dabei mit prefix "p_", gefolgt von dem Namen, wie in der Methode, deklariert generiert.

Sicherheitshinweis: Alle Parameter oder Objekteigenschaften vom Typ IduIT.GeoLib.Net.EncryptedString oder Parameter oder Objekteigenschaften, die den (C#) Namen "pwd" oder "password" enthalten, werden dabei nicht mit protokolliert. Passen Sie ggf. die Argumente in Ajax-Methoden entsprechend an, damit im Protokoll keine sicherheitskritischen Daten enthalten sind.

Z.Z. gibt es hier teilweise Probleme, dass Werte in der Ausgabe vom Grafana in bestimmten Konstellationen nicht ausgegeben werden, wir hoffen auf Besserung :)

cardo Konfiguration

Per Default ist das Monitoring deaktiviert und kann in den App-Settings der web.config von cardo4 aktiviert und konfiguriert werden. Die Vorlage "web.config.template" die in den Updates ausgeliefert wird, enthält entsprechende Hinweise.

Der Platzhalter {PROJEKTNAME} ist optional, wenn nicht angegeben, dann gilt dieser für alle cardo Instanzen des Servers, der Punkt "." ist dann wegzulassen.

Als Endpunkt ist z.Z. nur Loki verfügbar. Hinterlegen Sie zur Aktivierung des Monitorings hier die Url zu der API ihrer Loki-Installation. Für den Zugriff ist z.Z. keine Proxyeinstellung vorgesehen. Wir gehen davon aus, dass der Server per Direktzugriff erreichbar ist.

<add key="{PROJEKTNAME}.Monitoring.GrafanaLoki.ApiEndpoint" value="http://MeinLokiServer:3100/loki/api/v1/push" />

Alle weiteren Argumente sind ohne Wirkung, wenn kein API Endpunkt eingestellt ist.

Um die Ausgabe der Argumente von Ajax-Methoden zu aktivieren, muss StoreAjaxParameters angegeben werden. Der Standardwert ist "false".

<add key="{PROJEKTNAME}.Monitoring.StoreAjaxParameters" value="false"/>

Neben Fehlern kann es auch sinnvoll sein, bei Überschreitung bestimmter Ausführungsdauer einen Protokolleintrag erstellen zu lassen. Dazu können Schwellwerte bestimmt werden, die bei Ajax-Methoden einen Protokolleintrag erzwingen.

Jeder Schwellwert wird dabei über eine Protokoll-Stufe und den Zeitbereich in Millisekunden, wann dieser zutrifft, definiert. Es wird dabei in der angegebenen Reihenfolge der erste Eintrag ermittelt, der zu der aktuellen Ausführungsdauer der Funktion passt. Wird keiner gefunden, wird keine Protokollierung ausgelöst.

Beachte: Ab der Stufe Warning werden, wenn auch StoreAjaxParameters mit true angegeben ist, die Argumente des Methodenaufrufs mit protokolliert.

<add key="{PROJEKTNAME}.Monitoring.Thresholds" value="warning:2000-3000;error:3000-" />

Jeder Eintrag besteht entspricht dem Format:

<TraceLevel>:<Untergrenze in Millisekunden>-<Obergrenze in Millisekunden>

Zwischen den Einträgen muss ein Semikolon als Trennzeichen angegeben werden.

Die im Beispiel angegebene Definition bedeutet dabei:

"Alle Ajax-Aufrufe die zwischen 2...3 Sekunden dauern als Warnung protokollieren, die Aufrufe die über 3 Sekunden dauern als Fehler protokollieren, alle anderen nicht protokollieren."

Oder, um alle Anfragen zu protokollieren (nicht empfohlen!):

<add key="{PROJEKTNAME}.Monitoring.Thresholds" value="warning:2000-3000;error:3000-;default:0-2000" />

Grafana - Einrichtung des Logpanels

In Grafana kann ein Log-Panel eingerichtet werden. Wählen Sie als Datenquelle den eingestellten Loki Server aus.

Folgende Abfrage bietet sich für die Ausgabe an:

{app !=""} | json | line_format "{{.app}}@{{.machineName}} : {{.t}} IP:{{.remoteAddr}}"

Ergibt dann eine Ausgabe folgender Art:

Loki und Grafana Installation

Dies ist keine vollumfängliche Beschreibung - bitte für weitere Informationen die Grafana Homepage konsultieren.

Die folgende Installationsbeschreibung ist für Windows (Server) gedacht. Installiert wird dabei:

• "GrafanaLoki" (Windows-Dienst, http-Endpunkt 3100, grpc 9096)

• "Grafana" (Windows-Dienst, http-Endpunkt 3000)

  In dem Script wird eine angepasste Konfiguration für Loki verwendet (siehe C:\Program Files\GrafanaLabs\Loki\loki-local-config.yaml). Dort ist eine Retention von 31 Tagen eingestellt, der Speicherort der Daten ist %ProgramData%\GrafanaLabs\lokiData Zudem ist das Analytics-Reporting deaktiviert.

1. Starten Sie auf dem Ziel-Rechner eine powershell-Sitzung mit Administrationsrechten

2. Verschaffen Sie sich einen Überblick der folgenden Power-Shell Befehle

• Bitte den Pfad $targetFolder nicht anpassen!

• Passen Sie aber evtl. die Version der Download-Urls ($lokiUrl und $grafanaUrl) an (Stand: Juni 2025)

  • Loki: siehe https://github.com/grafana/loki/releases/
  • Grafana siehe https://grafana.com/grafana/download/

  Führen Sie dann die unten stehenden Befehle aus. Ggf. empfiehlt sich das "blockweise" ausführen. Es sind keine Fehlerbehandlungen hier enthalten. Z.B. kann der Download auf Grund von Proxy-Problemen fehlschlagen. In dem Fall diesen Schritt manuell ausführen.

  
   $lokiUrl = "https://github.com/grafana/loki/releases/download/v3.4.4/loki-windows-amd64.exe.zip"
   $grafanaUrl = "https://dl.grafana.com/oss/release/grafana-12.0.2.windows-amd64.msi"
  
   $lokiVers = $lokiUrl.split('/')[-2]
   $yamlUrl = "https://raw.githubusercontent.com/grafana/loki/"+$lokiVers+"/cmd/loki/loki-local-config.yaml"
  
   $targetFolder = $Env:Programfiles+"\GrafanaLabs\Loki\"
  
   mkdir $targetFolder
  
   cd $targetFolder
  
  
   $srvAnyUrl = "https://www.cardogis.com/downloads/LokiSrvAny.zip"
  
   Invoke-WebRequest $lokiUrl -OutFile "loki.zip"
   Expand-Archive -LiteralPath $tmpFolder"loki.zip" -DestinationPath $targetFolder
  
   Invoke-WebRequest $yamlUrl -OutFile "unused-loki-local-config.yaml"
  
   Invoke-WebRequest $srvAnyUrl -OutFile "LokiSrvAny.zip"
   Expand-Archive -LiteralPath $targetFolder"LokiSrvAny.zip" -DestinationPath $targetFolder
  
   reg import $targetFolder"LokiAsService.reg"
  
   Remove-Item *.zip
  
   sc.exe create GrafanaLoki binPath= $targetFolder"srvany.exe" start= "auto"
   net start grafanaloki
  
   cd ..
   $msi = $grafanaUrl.Substring($grafanaUrl.LastIndexOf("/") + 1)
   Invoke-WebRequest $grafanaUrl -OutFile $msi
  
   start $msi /passive
  
   start "http://localhost:3000"
  

3. Es sollte sich jetzt ein Browser geöffnet haben, in dem zu http://localhost:3000 navigiert wurde.

   Melden Sie sich jetzt mit "admin" / "admin" an. Sie werden dann aufgefordert ein neues Kennwort zu vergeben (Bitte merken!!)

4. Passen Sie die web.config (cardoSystem\CoreWeb4\web.config) auf dem cardo Server an, suchen Sie nach "Monitoring" (am besten einen Editor mit Syntax-Highlight verwenden, dann den Block "Einkommentieren").

   Wenn es nicht der gleiche Server ist, dann ggf. den Port 3100 auf dem Grafana Server in der Firewall öffnen.

5. Gehen Sie wieder in den Browser aus Schritt (3), fügen Sie eine neue Datenquelle in Grafana hinzu: Data sources => Add data source => Typ Loki (alle Vorgabewerte übernehmen)

6. Erstellen Sie ein Dashboard (durch das Anpassen der web.config in Schritt 4 sollte bereits Werte aus cardo dort enthalten sein).