FieldLog

Schnelles und umfassendes Logging-Werkzeug für .NET-Anwendungen. Für hohe Performance, geringen Speicherplatzbedarf und ständig aktiviertes Logging konzipiert und mit nützlicher Log-Betrachter-Anwendung.

Bring bitte etwa 8 Minuten mit, um diese Seite in Ruhe zu lesen.

tl;dr: Die Vorteile und Funktionen im Überblick:

  • Ablaufverfolgung, Daten- und Fehlerprotokollierung für .NET-Anwendungen
  • Sehr einfache Verwendung, keine Konfiguration notwendig
  • Hohe zeitliche Auflösung und Timer-Unterstützung, auch für Performancemessung geeignet
  • Log-Viewer mit hilfreichen Visualisierungen, Detailansicht, Filter und Live-Beobachtung
  • Protokolliert automatisch unbehandelte Exceptions
  • Vollständige Drop-In-Lösung zum sorgenfreien Protokollieren für selbstständige Entwickler und kleine Unternehmen (frei, Open-Source)
  • Log-Methoden für hohe Performance und Multi-Threading optimiert
  • Löscht alte Logeinträge abhängig von Priorität und konfigurierbarer Vorhaltezeit
  • Speichereffizientes Dateiformat, vermeidet String-Wiederholung, nutzt NTFS-Komprimierung
  • Quelltext-Lookup in Stack-Traces, ohne .pdb-Dateien auszuliefern
  • Deobfuscation von Stack-Traces mithilfe einer Obfuscator-Map-Datei
  • WPF TraceSource (z. B. DataBinding), leichter lesbar als in Visual Studio
  • Erstellt Screenshots des Fensters oder Bildschirms im Fehlerfall
  • Log-Konfiguration mit optionaler robuster Textdatei
  • Übertragungsprogramm das den Benutzer durch das Senden von Logs leitet

FieldLog ist ein schnelles und umfassendes Logging-Werkzeug für .NET-Anwendungen. Es ermöglicht Anwendungen, Ereignisse, Daten und Fehler in verwaltete und effiziente Logdateien zu schreiben. Die Log-Methoden sind für sehr geringe Verzögerung und Multi-Threading-Umgebungen optimiert und ein einzelner Aufruf einer Log-Methode benötigt auf aktuellen Rechnern gerade einmal eine halbe Mikrosekunde. Das ist kein Vergleich zu OutputDebugString, Debug.WriteLine oder jedes Mal an eine Datei anzufügen! Diese Protokollierung kann in geschwindigkeitskritischen Schleifen verwendet werden, ohne die Anwendung spürbar zu verlangsamen.

Kompatibilität: .NET Ab Version 2.0

Ständig aktivierte Protokollierung

Der Sinn der Sache ist es, die Debug-Protokollierung immer aktiv zu lassen, um sie im Fall eines Anwendungsfehlers auswerten zu können. Traditionelle Logsysteme können nur neue Einträge schreiben, löschen alte Daten aber nie. Dadurch steigt die Protokollgröße bei aktiviertem Debug-Logging stetig an. FieldLog kann seine Logdateien verwalten und Einträge einzelner Prioritätsstufen für eine bestimmte Zeit vorhalten und sie danach löschen, um Speicherplatz zu sparen und unnötige Daten zu entfernen. Die geringe Verzögerung und gute Speichereffizienz erlauben es, die Protokollierung aktiv zu lassen. Wenn ein Fehler auftritt, sind alle relevanten Informationen bereits verfügbar und können ausgewertet werden.

Du brauchst deinen Benutzern nicht erklären, wie sie versteckte XML-Dateien bearbeiten müssen, um die Protokollierung zu aktivieren, und dass sie warten müssen, bis der Fehler nochmal auftritt. Stattdessen wird der Benutzer durch das Sammeln der relevanten Protokolle geführt und kann sie direkt an den Entwickler senden.

Dateikomprimierung

Die Logeinträge werden in einem Binärformat geschrieben, das den Bedarf an Bytes pro Information minimiert und für mehr Speichereffizienz vorherige Text-Zeichenketten wiederverwendet. Wenn der selbe Meldungstext immer und immer wieder protokolliert wird, wächst die Log-Größe kaum an. Die Dateien werden nach Log-Priorität getrennt und nach einer bestimmten Dateigröße oder Zeit wird eine neue Datei begonnen. Falls verfügbar wird die NTFS-Komprimierung verwendet und bei Dateigrößenentscheidungen berücksichtigt. Alte Logdateien werden automatisch gelöscht. Die maximale Protokollgröße und Vorhaltezeit kann mit einer leicht verständlichen und robusten Textdatei im Anwendungsverzeichnis konfiguriert werden.

Logbetrachter

Die Logbetrachter-Anwendung, FieldLogViewer, lädt eine Gruppe von zusammengehörigen Logdateien und zeigt die Logeinträge in einer Liste an. Der Benutzer kann jeden Eintrag auswählen, um alle Details wie die Thread-ID, zusätzliche Exception-Daten, Stacktraces oder Angaben zur Systemumgebung zu der Zeit anzuzeigen. Die Einträge sind farblich nach ihrer Priorität gekennzeichnet und Symbole zeigen die Art des Ereignisses.

Ein leistungsfähiger Filter-Editor erlaubt es, schnell die interessanten Ereignisse zu finden, um sich auf das Wesentliche zu konzentrieren. Der Viewer kann sogar am Ende der Dateien weiterlesen und neue Einträge anzeigen, sobald sie von der laufenden Anwendung geschrieben werden. Das erlaubt dem Entwickler, seine Anwendung in Echtzeit zu beobachten. Der eingestellte Filter bleibt dabei aktiv.

FieldLogViewer ist auch als DebugOutputString-Monitor nutzbar (wie Sysinternals Dbgview), um begrenzte Debugausgaben von anderen Prozessen zu lesen.

Übertragungswerkzeug

Ein einfach zu bedienendes Werkzeug zur Übertragung von Logdateien und Screenshots führt den Benutzer durch den Prozess, die relevanten Logdateien auszuwählen, sie für den Transport zu verpacken und eine geeignete Transportmethode zu wählen. Die Übertragungsarten umfassen derzeit einen HTTP-Webservice-Upload, das Senden per E-Mail und das Kopieren des Pakets in ein lokales Verzeichnis wie z. B. einen USB-Stick. Später sind noch die Nutzung eines FTP-Servers und das Senden an Bluetooth-Geräte vorgesehen. Dieses Programm kann als Reaktion auf einen unbehandelten oder unbehebbaren Anwendungsfehler gestartet werden (Fehlerberichterstattung), so dass dem Benutzer die richtigen Informationen angezeigt werden und er die Protokolldateien absenden kann, solange sie vorliegen.

Beispiel

Im folgenden C#-Beispiel werden mehrere Anwendungsmöglichkeiten von FieldLog gezeigt.

using Unclassified.FieldLog;

class Program
{
    static void Main(string[] args)
    {
        // Indicate that we're not waiting for a custom log path to be configured.
        // If one is provided by the Program.flconfig file, it will be used first.
        // Otherwise, the default path strategy is applied.
        FL.AcceptLogFileBasePath();
       
        // Write out a first trace message that tells what's about to happen in the
        // application.
        FL.Trace("Initialising database");
        // Do the actual initialisation for the application
        try
        {
            InitializeApp();
        }
        catch (IOException ex)
        {
            // An Error event means that something has severely failed but the
            // situation could be handled.
            FL.Error(ex, "App initialisation");
        }
        if (!Initialized())
        {
            // A Critical event is when the application cannot continue to work.
            FL.Critical("Application was not initialised");
            return;
        }
        // A Checkpoint is a more important Trace message.
        FL.Checkpoint("Initialisation complete");

        // Another way to log messages
        FL.Text(FieldLogPriority.Notice, "A notice message");

        // Main application logic here...

        // Measure how long a function takes, averaging multiple iterations
        foreach (var record in GetRecords())
        {
            PrepareSomething();
            // ...
           
            using (FL.Timer("Long operation"))
            {
                LongOperation();
            }
        }
       
        // Some bonus features:
        // Information about the application (reading assembly attributes)
        Console.WriteLine("I am " + FL.AppName + " version " + FL.AppVersion);
        // Current time using high-precision timer
        Console.WriteLine("Now it's precisely " + FL.UtcNow + " (UTC)");
        // App uptime using high-precision timer
        Console.WriteLine("App is running for " + FL.AppUptime);
        // System information: Windows version and edition
        Console.WriteLine(OSInfo.Version + " " + OSInfo.Edition);
        // System information: Windows installed language
        Console.WriteLine(OSInfo.Language);
        // System information: User is administrator (does not show UAC dialog)
        if (OSInfo.IsCurrentUserLocalAdministrator())
        {
            // Write something to the system settings
        }
    }
   
    static void SectionA()
    {
        // Log the scope of this method. The method name is set automatically.
        using (FL.NewScope())
        {
            // Do interesting stuff here.
            int count = 23;
            SectionB(count);
            // ...
        }
    }
   
    static void SectionB(int count)
    {
        // Log the scope of this method. The method name is set automatically.
        using (FL.NewScope())
        {
            // Log the variable name and value with Trace priority.
            FL.TraceData("count", count);
            // ...
        }
    }
   
    static void LongOperation()
    {
        // ...
    }
}

EntwickleranleitungDie Entwickleranleitung erklärt alle Protokollierungsmethoden ausführlicher. This is the recommended starting point for those who intend to use the library.

Du kannst dir auch die im Quelltext enthaltene ConsoleDemo-Anwendung anschauen und damit spielen, um mehr über das Logging-API zu erfahren.

Screenshots

Hier sind einige Screenshots der FieldLogViewer-Anwendung:

Image
FieldLogViewer mit Exception-Details
Image
Einrückung
Image
Thread-Hervorhebung
Image
Relative Zeitangabe
Image
Filtereditor
Image
Scrollmap und Schnellfilter
Image
Anwendungsfehlerdialog
Image
Fehlerdetails
Image
Web error page

Download

Hinweis: Veröffentlichungen nach dem 9.1.2016 sind nicht mehr digital signiert, da keine kostenlosen Code-Signing-Zertifikate für Open-Source-Entwickler mehr angeboten werden. Ein kommerzielles Zertifikat ab 200 € pro Jahr lohnt sich hier nicht. Entschuldigung für die Verunsicherung beim nächsten Download.

FieldLogSetup-1.775.59_dd3ff3.exe1,0 MiBInstallationsprogramm mit FieldLogViewer, FieldLog-Assembly, Dokumentation und Code-Referenz
Version 1.775.59 vom 2017-02-14, Commit dd3ff3

FieldLogChanges.txt6,9 KiBÄnderungen der veröffentlichten Versionen

master.zipAktueller Quelltext direkt von GitHub

Vorherige Versionen

FieldLogSetup-1.525.41_5ab537.exe1,0 MiBVersion 1.525.41 vom 2016-06-09, Commit 5ab537

FieldLogSetup-1.481.54_5f3e57.exe1,0 MiBVersion 1.481.54 vom 2016-04-26, Commit 5f3e57

FieldLogSetup-1.433.85_17032a.exe1,0 MiBVersion 1.433.85 vom 2016-03-09, Commit 17032a

FieldLogSetup-1.415.87_d327d0.exe1,0 MiBVersion 1.415.87 vom 2016-02-20, Commit d327d0

FieldLogSetup-1.395.92_5af04a.exe1,0 MiBVersion 1.395.92 vom 2016-01-31, Commit 5af04a

FieldLogSetup-1.383.75_4097f2.exe1,0 MiBVersion 1.383.75 vom 2016-01-19, Commit 4097f2

FieldLogSetup-1.336.83_5cd1bb.exe1,0 MiBVersion 1.336.83 vom 2015-12-03, Commit 5cd1bb

FieldLogSetup-1.334.92_0fb50c.exe1,0 MiBVersion 1.334.92 vom 2015-12-01, Commit 0fb50c

FieldLogSetup-1.241.60_ad1f66.exe1,0 MiBVersion 1.241.60 vom 2015-08-30, Commit ad1f66

FieldLogSetup-1.208.64_6e1888.exe1,0 MiBVersion 1.208.64 vom 2015-07-28, Commit 6e1888

FieldLogSetup-1.200.38_c9395e.exe1,0 MiBVersion 1.200.38 vom 2015-07-20, Commit c9395e

FieldLogSetup-1.194.66_9ffa01.exe1,0 MiBVersion 1.194.66 vom 2015-07-14, Commit 9ffa01

FieldLogSetup-1.173.83_5e352f.exe1,0 MiBVersion 1.173.83 vom 2015-06-23, Commit 5e352f

FieldLogSetup-1.172.86_e0c86e.exe1,0 MiBVersion 1.172.86 vom 2015-06-22, Commit e0c86e

FieldLogSetup-1.171.75_b76c5b.exe1,0 MiBVersion 1.171.75 vom 2015-06-21, Commit b76c5b

FieldLogSetup-1.116.62_2c0da0.exe1,0 MiBVersion 1.116.62 vom 2015-04-27, Commit 2c0da0

FieldLogSetup-1.113.77_6e7f5d.exe1,0 MiBVersion 1.113.77 vom 2015-04-24, Commit 6e7f5d

FieldLogSetup-1.38.77_06b662.exe0,9 MiBVersion 1.38.77 vom 2015-02-08, Commit 06b662

FieldLogSetup-1.38.51_031fd0.exe911 KiBVersion 1.38.51 vom 2015-02-08, Commit 031fd0

FieldLogSetup-17yn.5da7e5.exe916 KiBVersion 17yn vom 2015-01-27, Commit 5da7e5

FieldLogSetup-1775.7541b5.exe910 KiBVersion 1775 vom 2015-01-19, Commit 7541b5

FieldLogSetup-0v66.4f5b47.exe889 KiBVersion 0v66 vom 2014-09-21, Commit 4f5b47

FieldLogSetup-0rq7.71cdec.exe879 KiBVersion 0rq7 vom 2014-09-05, Commit 71cdec

FieldLogSetup-0hcn.9d63ee.exe1,0 MiBVersion 0hcn vom 2014-06-17, Commit 9d63ee

Du kannst dir auch frühere Versionen bei GitHub herunterladen oder in die Aufgabenliste schauen:

FieldLog-Repository bei GitHub

Dieses Paket ist auch über NuGet verfügbar. Auf diesem Weg kann es besonders schnell in ein Visual-Studio-Projekt eingebunden und später aktualisiert werden. Hier ist nur das FieldLog-Assembly für verschiedene .NET-Versionen enthalten. Um den FieldLogViewer zu installieren, muss das oben genannte Setup-Programm heruntergeladen werden.

Unclassified.FieldLog-Paket bei NuGet

Aktueller Entwicklungsstand

FieldLog and the log file format are stable but could use some more testing. There are plans for future additional features that may change the API and file format. The file format is versioned so it is possible to continue reading old files, even in the same log file set.

FieldLogViewer is pretty stable by now. There are still lots of features and improvements planned and this is where the most changes happen now. See the Git change log for details.

The log submit tool is usable but still new and does not support all planned transport methods yet. If you need to translate it to more languages, please send me the dictionary file so I can include it. You can also keep it to yourself and use a private build.

The documentation is currently limited to the FieldLog code documentation and the developer guide page (German only). The source code reference is not ready for the public yet, use the inline comments through IntelliSense instead (original source code or .xml file as included in the NuGet package).

Änderungen

2017Feb14
Version 1.775.59 (Commit dd3ff31)
  • FieldLog: Don't log WPF "Cannot find governing FrameworkElement" messages
  • FieldLog: High-resolution system time using the GetSystemTimePreciseAsFileTime method (Windows 8 or later)
  • FieldLog: README file in the log directory explains that all files are necessary when copying
  • FieldLogViewer: Improved 200% high DPI image scaling (like Visual Studio once did)
  • FieldLogViewer: Added Windows 10 theme (incomplete) besides Windows 8 theme
  • FieldLogViewer: Make use of WPF 4.6 high-DPI layout improvements (App.config)
  • FieldLogViewer: Fixed: Prevent windows stuck invisible on now disconnected monitors
  • LogSubmit: Finds log files directly in the current directory
  • LogSubmit: Validates e-mail address if provided
  • LogSubmit: Saves last entered user e-mail address for the next report

2016Jun9
Version 1.525.41 (Commit 5ab5375)
  • FieldLog: Simplified exception message formatting (without namespace, not for obfuscated names)

2016Apr26
Version 1.481.54 (Commit 5f3e577)
  • AppErrorDialog: Increased height for localised titles

2016Mrz9
Version 1.433.85 (Commit 17032ad)
  • AppErrorDialog supports High DPI screens

2016Mrz7
Version 1.431.86 (Commit 31333d8)
  • Entity Framework: EntityValidationErrors logging support
  • FieldLogViewer: Fixed problems around filter exceptions
  • FieldLogViewer: Fixed display of underscores in menu with recently loaded files
  • Don't log time recalibration if there was no log item recently

2016Feb1
Version 1.395.92 (Commit 5af04ac)
  • Fixed: Dynamic methods have no metadata token, so FieldLogStackFrame can't retrieve it
  • FieldLogViewer: Little UI enhancements (added details indicator, new enter/leave images)

2016Jan19
Version 1.383.75 (Commit 4097f29)
  • Fixed exception logging (and source resolving, deobfuscation) with dynamic or unknown modules and global functions
  • Fixed AppErrorDialog message showing horizontal scrollbar when not necessary
  • FieldLogViewer: Fixed loading of compressed obfuscation map file
  • FieldLogViewer: Optional separator line between log items that represents the time passed between two items
  • FieldLogViewer: Limited MRU items list to 15 log base paths
  • FieldLogViewer: Do not add temporary log files to the MRU list
  • Ignore more WPF trace messages about CanFreeze. These are a WPF bug and not interesting at all.
  • Shared code and build script update

2015Dez3
Version 1.336.83 (Commit 5cd1bb6)
  • Add new .mapz extension for compressed obfuscation map files
  • Improved PdbConvert /optimize performance through parallelisation
  • Fixed NullReferenceException when creating a screenshot for no window

2015Dez2
Version 1.334.92 (Commit 0fb50ca)
  • FieldLogViewer: Improved error handling for stack frame module names
  • Don't write log files until something relevant happens
  • Never try to write log files to a protected service account directory
  • Updated build script for Git for Windows 2.x
  • Obfuscation compatibility

2015Aug30
Version 1.241.60 (Commit ad1f66c)
  • FieldLogViewer: Fixed unhandled ArgumentException at Path.GetFileNameWithoutExtension
  • FieldLog: Added TextRetainedAppend method

Ältere Versionen sind in der Änderungsdatei enthalten. Alle Änderungen lassen sich detailliert in der Commit-History des Git-Repositorys nachlesen.

Was noch kommt…

Dies ist eine unsortierte Liste der Dinge auf meiner Aufgabenliste. Es gibt keinen Zeitplan, aber ich möchte alles davon sobald wie möglich umsetzen.

  • Lokalisierung des Log-Betrachters
  • Konfigurations-API, um die Log-Konfiguration aus den Anwendungseinstellungen heraus zu ermöglichen
  • Farb-Hervorhebung von Log-Einträgen im Log-Viewer, ähnlich wie Filter
  • Statistische Informationen anzeigen, wenn mehrere Log-Einträge ausgewählt sind
  • Scope folding im Log-Viewer
  • Lesezeichen im Log-Viewer
  • Diagramme aus nummerischen Daten-Einträgen zeichnen
  • Statistische Nutzungsdaten sammeln (noch ohne Konzept, evtl. als separates Projekt)

Der Name

Der Name „FieldLog“ sollte ursprünglich auf das „out in the field logging“ (draußen im Feld protokollieren) Bezug nehmen, dort wo deine Anwendungen laufen. Es tut alles, um sich da draußen selbst zu erhalten und dem Entwickler alle relevanten Informationen über Probleme bereitzustellen, die auftreten könnten. Der Entwickler muss nicht dorthin gehen, wo seine Anwendung läuft, wenn die Benutzer über eine ausreichende Internetverbindung verfügen und Logdateien übertragen und Aktualisierungen installieren können.

Eine andere Interpretation könnte sich auf die strukturierten Logeinträge beziehen, die FieldLog von einfachen Textdateien unterscheiden, welche wirklich nur eine einzelne Zeile unformatierten Texts zu jedem Ereignis speichern. Der Zugriff und das Verständnis jedes einzelnen Datenstücks ermöglicht eine Filterung der Datenmassen, um die interessanten Stellen auch tatsächlich zu sehen.

Das Logo vereint die Großbuchstaben F und L in eine kombinierte Form (die zufällig wie ein E aussieht), mit verschiedenen Farben für die separaten und den gemeinsamen Teil. Die horizontalen Balken bilden auch „gute Zeilen“ und „Fehler“ in einer Logliste ab, was im Grunde das ist, was FieldLog anzeigt.

Lizenz und Nutzungsbedingungen

Die FieldLog-Bibliothek, die in Anwendungen verwendet wird, wird unter den Bedingungen der GNU-LGPL-Lizenz Version 3 veröffentlicht. Die anderen Projekte (FieldLogViewer, Demos und Werkzeuge) werden unter den Bedingungen der GNU-GPL-Lizenz Version 3 veröffentlicht. Die genauen Lizenzbedingungen befinden sich im Download oder auf der GNU-Website (LGPL, GPL).

Statistische Daten

  • Erstellt am 2013-06-30, aktualisiert am 2017-02-14.
  • Ca. 27 000 Codezeilen, geschätzte Ent­wick­lungs­kos­ten: 27 000 - 110 000 €