Darum!

Bei der Erstellung ernsthafter Anwendungen kommt man um das Erstellen von Logdateien selten herum. Nicht immer kann man einem Nutzer eine Fehlermeldung präsentieren, nicht immer ist der interne Zustand der Anwendung nach Außen interessant. Ja manchmal, etwa bei Windows-Diensten, Serveranwendungen und Programmen für die Kommandozeile, gibt es keinen Nutzer, der auf Irgendetwas reagieren könnte.

Die Lösung liegt da auf der Hand, man verwendet dann Dateien, in denen man alles Wichtige speichert - Logdateien (siehe auch Wikipedia).

In verschiedenen Fällen ist einfaches Logging in Dateien nicht mehr ausreichend. Man stelle sich nur eine Anwendung vor, welche auf vielen hundert Client-Rechnern verteilt ist, etwa in Callcentern, und deren Logs nur in lokale Dateien geschrieben werden. Wie kommt man dann an die Logs?

An jeden Rechner einzeln setzen oder per Remote-Session eine Kopie der richtigen Logdateien ziehen und fast immer an einem Entwicklerrechner auswerten. Das ist aufwendig und unnötig, bei einer solchen Infrastruktur wäre es effektiv, wenn man die Logs nicht erst kopieren müsste, sondern diese bereits an einer zentralen Stelle gesammelt würden. Genau für diesen Zweck gibt es LogServer, diese sammeln aktiv Lognachrichten oder warten auf die Übermittlung derer von Clients.

Das Framework für das Erstellen von Logs "nxLogging" für Delphi ab Version 2009 ist frei mit Source verfügbar. Die einzige Datei, aus der es besteht, ist "nxLogging.pas", es soll einfach zu nutzen, nicht zu komplex und dennoch mit allen wichtigen Funktionalitäten ausgestattet sein.

Download des Frameworks:

Sie können nxLogging als vollständigen Installationssatz oder als Zip-Datei, welche nur die Quellen ohne Tools und Programme beinhaltet, auf der Navimatix-Seite herunterladen. (nxLogging-Download)

Einbinden in Delphi:

Neues Package erstellen

nxLogging.pas hinzufügen

Nach der Installation steht Ihnen die Datei nxLogging.pas zur Verfügung. Binden Sie diese nun in die Infrastruktur Ihrer Delphi-Komponenten ein, dabei kann die Datei für erste Tests natürlich auch direkt zu der Anwendung kopiert werden, für den echten Einsatz jedoch empfehlen wir die Erstellung eines Packages und dessen Nutzung in Ihren Programmen.

1. Erstellen Sie ein neues Delphi-Package (Datei->Neu->Package Delphi)

2. Speichern Sie dieses unter einem aussagekräftigen Namen, etwa "nxLoggingComponents"

3. Fügen Sie die Datei "nxLogging.pas", welche mit der Installation auf Ihr System gelangt ist, oder per Source-Download, dem Package hinzu (Rechte Maustaste auf "Enthält" in der Projektverwaltung).

4. Compilieren Sie das Package (Projekt->[Packagename] compilieren)

5. Fügen Sie die Quellen des Packages gegebenenfalls dem Bibliothekspfad hinzu (Tools->Optionen-->Bibliothek - Win32/64->Bibliothekspfad). Nur benötigt, wenn nxLogging mit dem Projekt kompiliert werden soll.

Initialisierung in Ihrer Anwendung:

Nach erfolgreicher Einbindung in Ihre Entwicklungsumgebung, können Sie in Ihren Programmen unter uses die Unit "nxLogging" hinzufügen und die Klassen, Typen und Funktionen daraus benutzen. In einer Anwendung, welche dieses Framework nutzen soll, empfiehlt es sich die notwendige Initialisierung des Frameworks möglichst früh, etwa im Konstruktor des Hauptfensters, im Loaded(), oder bereits vor dem Erstellen von grafischen Elementen zu erledigen.

Ein Logger in nxLogging besitzt zur einfachen Initialisierung des File-loggings eine spezielle Methode "initializeFileLogging()":

Einfache Initialisierung für Datei-logging

// Initialisierung des Standardloggers...
nxLogging.Logger.initializeFileLogging(
    'myAppName',  // Der Name der Anwendung, wird in das Log-File aufgenommen.
    '.\log\',      // Das Verzeichnis, in dem die Log-Dateien geschrieben werden sollen.
                  // hier Unterordner "log" relativ zur ausführbaren Datei (exe).
    'myAppName'   // Basisname, mit dem alle Log-Dateien beginnen.
);

Nutzung in Ihrer Anwendung:

Nach der Initialisierung des Loggers kann dieser sofort genutzt werden. Nutzen Sie dafür die verschiedenen Überladungen der Methode log(), oder die speziellen Methoden trace(), debug(), info(), warn(), error(), fatal(). Hier eine kleine Auswahl von möglichen Log-Statements:

// Trace-Nachricht loggen...
// Module: Gibt an, in welchem Modul die Nachricht erzeugt wurde
// Message: Der Nachrichtentext
// Category: Gibt die Kategorie der Nachricht an.
// de: Sprache, in der die Nachricht verfasst wurde, ISO 639-1
Logger.log(NXLL_TRACE, 'Module', 'Log-Message (Zur Nachverfolgung)', 'Category', 'de', nil);

// Eine Debug-Nachricht loggen, Module=Komponentenname...
Logger.debug(self.Name, 'Zu Debug-Zwecken');

// Eine Info-Nachricht loggen, Module=Komponentenname...
Logger.info(self.Name, 'F.Y.I.');

// Eine Warnung loggen, Module=Komponentenname...
Logger.warn(self.Name, 'Eine Warnung');

// Eine Error-Nachricht loggen, Module=Komponentenname, mit Stacktrace...
try
  // eventuell eine Exception...
  raise Exception.Create('Ein Fehler!');
except
  on e : exception do
  begin
    Logger.error(self.Name, 'Fehler?: '+e.Message, NXLCAT_OPTIONS, e);
  end;
end;

// Eine Fatal-Nachricht loggen, Module=Komponentenname...
Logger.fatal(self.Name, 'Ein FATALER Fehler!');

Beim Ausführen dieser Anweisungsfolge entsteht eine entsprechende Log-Datei namens "myAppName_2013.07.15.nxlog". Standard ist, dass der Logger erst ab einem Level von "info" Nachrichten erzeugt, also sieht die Datei wie folgt aus:

myAppName|2013.07.15 20:16:41.423|info.Form1|F.Y.I.|7276|matthias|||2096
myAppName|2013.07.15 20:16:41.429|warn.Form1|Eine Warnung|7276|matthias|||2096
myAppName|2013.07.15 20:16:42.367|error.Form1|Fehler?: Ein Fehler!|7276|matthias|||2096
myAppName|2013.07.15 20:16:42.371|fatal.Form1|Ein FATALER Fehler!|7276|matthias|||2096

Die Spalten sind jeweils mit dem Zeichen "|" getrennt, die Log-Nachrichten selbst durch . Die Reihenfolge ist:

Ausgabe im nxTail

nxTail per Remote-Logging am
LogServer verbunden

Sie können diese Log-Datei mit einem Tail-Programm Ihrer Wahl, oder mit nxTail direkt betrachten. Das Tool "nxTail" ist speziell für nxlog-Dateien konzipiert.

Zum automatischen Übermitteln der Log-Nachrichten an einen Navimatix LogServer muss lediglich eine weitere Initialisierungsmethode am Logger aufgerufen werden.

// Initialisierung des Remote-Loggings...
Logger.initializeServerTCPLogging('myAppName', 'nxgate02.navimatix.net', 8077);

Von nun an werden die Log-Nachrichten per TCP direkt an einen LogServer gesendet. Dort werden diese in einer Datenbank gespeichert, stehen dann für Statistiken und zur Überwachung zur Verfügung.

Auch die an einem zentralen LogServer eingehenden Nachrichten kann man sich mit nxTail direkt live ansehen. Dazu muss man sich lediglich mit dem entsprechenden Server verbinden und schon ist das Remote-Logging komplett.

Bei Fragen zu nxLogging wenden Sie sich bitte an matthias.heunecke [at] navimatix.de

In einem verteilten Umfeld ist es sinnvoll, wenn es eine zentrale Instanz gibt, an der alle Logs zusammen laufen. Damit entfällt im Ernstfall das lästige und zeitraubende Suchen der und in der richtigen Logdatei.

Um mit diesem Tutorial zu beginnen, sollten Sie mit den Folgenden vertraut sein:

► Grundlagen zu nxLogging, Tutorial auf dieser Seite

► Grundlagen zu nxLogging, Video auf youtube

Um das automatische Übermitteln von Lognachrichten an einen Navimatix LogServer zu aktivieren muss die Methode "initializeServerTCPLogging()" mit den nötigen Parametern aufgerufen werden. Diese Methode besitzt jeder Logger, also auch der Standardlogger in nxLogging, da hier eine einfache und unkomplizierte Einrichtung des Remote Loggings möglich sein soll.

procedure TForm1.FormCreate(Sender: TObject);
begin
  // logging in Dateien initialisieren...
  Logger.initializeFileLogging('nxLDM', '.\log\', 'nxLDM');

  // logging an einen LogServer per TCP initialisieren...
  Logger.initializeServerTCPLogging('nxLDM', 'nxgate02.navimatix.net', 8077);
end;

In diesem Beispiel und mit den 3 übergebenen Parametern wird ein einfaches Logging an den Server aktiviert. Dabei werden keine Zugangsdaten angegeben und kein eigenes MachineIdent übergeben. Daher kann so nur an Server geloggt werden, die für das Übermitteln der Nachrichten keine Zugangsdaten fordern (Konfigurationssache). Für einen LogServer ist es wichtig die einzelnen Rechner/Maschinen, von denen Logs eintreffen, unterscheiden zu können. nxLogging bietet hier 2 Möglichkeiten:

► Sie geben als MachineIdent einen leeren String an und es wird automatisch der Rechnername (Windowsname) als Identifikation genutzt.

► Sie geben einen selbst definierten Namen als Identifikation an. Hier muss der Entwickler selbst für sinnvolle und eindeutige Bezeichnungen sorgen, Maximallänge ist 255 Zeichen.

Da in diesem Beispiel auch keine Angaben zum Loglevel gemacht wurden, werden auch hier die Defaults genutzt: alles ab warn bis fatal.

Das folgende Beispiel zeigt eine vollständige Initialisierung mit allen möglichen Parametern.

// logging an einen LogServer per TCP ERWEITERT initialisieren...
  Logger.initializeServerTCPLogging(
      'nxLDM',                     // ApplicationIdent
      'nxgate02.navimatix.net',    // Host oder IP des Logservers
      8077,                        // Port des Logservers
      'myIdent985',                // MachineIdent, selbst vergeben
      10,                          // RetryCount
      'MyUsername',                // Nutzername für den Logserver
      'MyPassword',                // Passwort für den Logserver
      [NXLL_TRACE, NXLL_DEBUG,
       NXLL_INFO, NXLL_WARN,
       NXLL_ERROR, NXLL_FATAL]     // Loglevel-Maske, hier alle...
      );

Nach der Initialisierung des Remote Loggings werden bei jedem normalen "Trace", "Info", "Error", etc... die Lognachrichten automatisch an den Server gesendet, eine spezielle Behandlung von Lognachrichten muss nicht stattfinden.

procedure TForm1.Button2Click(Sender: TObject);
begin
  // Je nach Initialisierung: loggen in Dateien und/oder Server
  Logger.trace('trace');
  Logger.debug('debug');
  Logger.info('info');
  Logger.warn('warn');
  Logger.error('error');
  Logger.fatal('fatal');
end;

Mit dem Tool "nxTail" kann man sich mit einem Navimatix LogServer verbinden, um direkt und in Echtzeit die am Server eintreffenden Logs zu betrachten. Dazu müssen die entsprechenden Zugangsdaten und Verbindungsdaten angegeben werden. Per Klick auf den Button "Neuen Server verbinden" gelangen Sie zum Eingabedialog für die Serverdaten:

nxTail mit Logserver verbinden

In der Rubrik Filter auf diesem Dialog können verschiedene Filter gesetzt werden. Sie können etwa ein MachineIdent angeben, um nur Lognachrichten zu erhalten, welche von einem bestimmten LogClient/Rechner kommen, oder Sie definieren ein ApplicationIdent, um Ihre Sicht auf eine bestimmte Anwendung einzuschränken.

Zusätzlich kann noch ein "enthält"-Filter für Modul und Nachrichtentext angegeben werden.

Führt man das Beispielprogramm aus dem Grundlagen Tutorial mit entsprechender Logserver-Initialisierung aus, so ergibt sich bei einem verbundenen nxTail das folgende Bild:

nxTail beim Remote Logging

Im Logserver stehen dann die Lognachrichten zur Ansicht und für Statistiken zur Verfügung (Webanwendung):

Bei Fragen zu nxLogging wenden Sie sich bitte an matthias.heunecke [at] navimatix.de

Viel Erfolg bei Ihren Projekten.