Logging

primedocs protokolliert mit NLog. Jede Server-Applikation und jede Komponente von primedocs Desktop schreibt eigene Log-Dateien. Warnungen und Fehler der Server-Applikationen lassen sich zusätzlich zentral in die Operation-Datenbank schreiben. Diese Seite beschreibt, was wo protokolliert wird und wie sich das Logging konfigurieren lässt. Wie die Dateien für eine Supportanfrage eingesammelt werden, zeigen Server Logs und Client Logs.

Übersicht

Quelle	Ablage	Datei	Protokollierte Stufen	Zeitstempel
Server-Applikationen	Installationsordner der jeweiligen Applikation	serverApp.oolog	Info und höher	UTC
Server-Applikationen, optional	Operation-Datenbank, Tabelle NLog	—	Warn und höher	UTC
primedocs Desktop	Log-Ordner des Benutzers, siehe Log-Ordner festlegen	PrimeDocs.Client.txt	alle	Lokalzeit
Office COM-Add-Ins	gleicher Ordner wie primedocs Desktop	PrimeDocs.AddIn.*.txt	alle	Lokalzeit

Connect-Aufrufe erscheinen im Log der verarbeitenden Komponente, also des Connect-Dienstes, der Web API oder von primedocs Desktop. primedocs Desktop kann zusätzlich die empfangenen Connect-Aufrufe aufzeichnen, siehe Connect-Protokoll und Connect Logs. Welche Vorlagen verwendet werden, hält nicht das technische Log fest, sondern das Nutzungsprotokoll in der Datenbank.

Server-Applikationen

Jede Server-Applikation hat in ihrem Installationsordner eine eigene NLog.config und schreibt daneben die Datei serverApp.oolog.

• Rotation: Pro Tag entsteht eine neue Datei. Ältere Tage liegen als serverApp.<n>.oolog daneben, die kleinste Nummer ist der jüngste Tag. Es bleiben höchstens sieben archivierte Dateien erhalten, ältere werden gelöscht.
• Stufen: In die Datei gelangen Meldungen der Stufen Info, Warn, Error und Fatal. Meldungen von Microsoft-Komponenten (ASP.NET Core, Entity Framework Core) erscheinen erst ab Warn.
• Zeilenformat: Zeitstempel in UTC, Rechnername, Stufe, Meldung und gegebenenfalls die vollständige Exception.

tipp

Die Zeitstempel der Server-Logs sind in UTC, die der Client-Logs in Lokalzeit. Beim Abgleich zwischen Server- und Client-Log die Zeitverschiebung berücksichtigen (in der Schweiz eine Stunde im Winter, zwei Stunden im Sommer).

Applikationen und Log-Ordner

Damit die DataSourceAdminApp die Dateien anzeigen und als ZIP herunterladen kann, steht pro Applikation unter apps in der primedocs.config das Attribut logFilePath. Ein relativer Pfad bezieht sich auf den Ordner der primedocs.config. Das Attribut legt nur fest, wo gelesen wird. Wohin geschrieben wird, bestimmt die NLog.config der Applikation.

Applikation (type)	Aufgabe	logFilePath (Standard)	Wert in der Spalte Application
App	primedocs Web, Office Web-Add-Ins	App\	Client
AdminApp	Web-Admin	Admin\	AdminApp
WebApi	Web API, darunter Admin API und Connect API	WebApi\	WebApi
Service	Synchronisation von primedocs Desktop	Service\	Service
IdentityServer	Anmeldung	IdS\	IdS
AddressService	Serverseitige Address Provider	AddressService\	AddressService
Connect	Connect-Dienst (/api/v1/Connect)	Connect\	Connect
Mcp	MCP-Server	Mcp\	Mcp
JobHost	Benutzersynchronisation und Hintergrundjobs	JobHost\	JobHost
DataSourceAdminApp	Admin Dashboard	DataSourceAdminApp\	schreibt nie in die Datenbank
HealthMonitor	Health Monitor	HealthMonitor\	schreibt nie in die Datenbank

Der IdentityServer für die Windows-Authentifizierung schreibt, sofern installiert, ebenfalls eine serverApp.oolog in seinen Installationsordner und erscheint in der Datenbank als IdSAuth. Auf Azure läuft der JobHost als WebJob aus einer temporären Kopie. Seine Log-Datei liegt dort deshalb nicht im Ordner JobHost\, seine Warnungen und Fehler lassen sich aber über das Logging in die Datenbank auswerten.

Log-Ort und Stufe anpassen

Ablageort, Aufbewahrung und Stufen lassen sich in der NLog.config der jeweiligen Applikation anpassen, zum Beispiel ein anderes minlevel in der Regel für das file-Target, um vorübergehend auch Debug-Meldungen zu schreiben. Die Syntax beschreibt die NLog-Dokumentation.

• Anderer Ablageort: Im file-Target ${basedir} durch den gewünschten Ordner ersetzen und logFilePath in der primedocs.config nachziehen. Jede Applikation braucht einen eigenen Ordner. Die Dateiendung .oolog beibehalten, denn das Admin Dashboard zeigt und lädt nur *.oolog-Dateien. Das Vorgehen für ein schreibgeschütztes Applikationsverzeichnis beschreibt Read-Only Applikationsverzeichnis.
• Updates: Das Update-Skript vergleicht jede NLog.config mit der Version im Update-Paket und fragt bei Abweichungen, ob die Datei ersetzt oder behalten werden soll, siehe primedocs Server aktualisieren.

warnung

Ausführliche Stufen wie Debug oder Trace erzeugen grosse Dateien und können Inhalte aus Dokumenten und Datenquellen protokollieren. Nur zur Fehlersuche aktivieren und danach wieder zurückstellen.

Logging in die Datenbank

Ist auf dem Wurzelelement der primedocs.config databaseLoggingEnabled="true" gesetzt, schreiben die Server-Applikationen Warnungen, Fehler und schwere Fehler zusätzlich in die Tabelle NLog der Operation-Datenbank (operationDbConnectionString). Die Log-Dateien entstehen weiterhin. DataSourceAdminApp und Health Monitor schreiben nie in die Datenbank.

<primedocs operationDbConnectionString="..."
           databaseLoggingEnabled="true">
  ...
</primedocs>

Jeder Eintrag enthält Rechnername, Applikation (Spalte Application, siehe Tabelle oben), Zeitpunkt in UTC, Stufe, Meldung, Logger, Aufrufstelle und Exception. Voraussetzung ist, dass das Target Database in der NLog.config unverändert vorhanden ist.

Die Einträge werden an zwei Stellen ausgewertet:

• Admin Dashboard: Der Reiter LOGGING auf der Startseite erscheint nur bei aktiviertem Datenbank-Logging. Er zeigt die neuesten 1000 Einträge, filtert auf die Stufe Error (Show only Errors), markiert einzelne Einträge als gelesen (Mark as Read) und löscht alle Einträge (Delete All Logs).
• Health Monitor: Ungelesene Einträge der Stufen Warn und Error aus den letzten 24 Stunden fliessen in den Status ein. Als gelesen markierte Einträge zählen nicht mehr, siehe Anwendungsprotokoll.

Aufbewahrung

Der JobHost löscht bei jedem Lauf ohne Parameter alle Einträge der Tabelle NLog, die älter als 14 Tage sind, sofern das Datenbank-Logging aktiviert ist. Einzeln lässt sich die Bereinigung mit primedocs.JobHost.exe RemoveOldLogEntries starten. Die Frist ist fest und nicht konfigurierbar.

primedocs Desktop und Office COM-Add-Ins

primedocs Desktop und die Office COM-Add-Ins schreiben pro Benutzer in einen gemeinsamen Log-Ordner. Pro Komponente gibt es eine Datei:

Datei	Komponente
PrimeDocs.Client.txt	primedocs Desktop, inklusive clientseitiger Connect-Verarbeitung
PrimeDocs.AddIn.Word.txt	Word-Add-In für klassische Vorlagen
PrimeDocs.AddIn.Common.Word.txt	Word-Add-In für die neuen Vorlagentypen und Snippets
PrimeDocs.AddIn.Common.Excel.txt	Excel-Add-In
PrimeDocs.AddIn.Common.PowerPoint.txt	PowerPoint-Add-In
PrimeDocs.AddIn.Outlook.txt	Outlook-Add-In

• Rotation: Wie auf dem Server eine Datei pro Tag mit höchstens sieben archivierten Dateien (PrimeDocs.Client.<n>.txt usw.).
• Stufen: Es wird alles protokolliert, auch Trace und Debug.
• Zeilenformat: Zeitstempel in Lokalzeit, Logger, Windows-Benutzer, Rechnername, Prozess-ID und Meldung. Die Add-Ins für die neuen Vorlagentypen schreiben zusätzlich die Stufe.
• Öffnen: In primedocs Desktop unter primedocs › Hilfe › Log-Verzeichnis öffnen, siehe Client Logs.

Log-Ordner festlegen

Der Log-Ordner wird bei der Installation festgelegt, siehe Installation primedocs Desktop:

• Interaktive Installation: Der Log-Ordner folgt der Wahl des Cache-Ordners im Installationsdialog. Bei der Vorauswahl Local directory ist es %LOCALAPPDATA%\primedocs\Logs, bei Roaming directory %APPDATA%\primedocs\Logs und bei Custom <Cache-Ordner>\primedocs\Logs.
• Installation ohne Dialoge: Die MSI-Eigenschaft LOGFOLDER bestimmt den Ordner. Sie versteht NLog-Platzhalter wie ${specialfolder:LocalApplicationData}. Ohne Angabe gilt ${specialfolder:ApplicationData}/primedocs/Logs, also %APPDATA%\primedocs\Logs.
• Update: Der Installer übernimmt den Ordner aus der NLog.config von primedocs Desktop und schreibt ihn in die Konfiguration von primedocs Desktop und aller Office COM-Add-Ins. Ein beim Update übergebenes LOGFOLDER wird dabei nicht berücksichtigt.

Connect-Protokoll

Zur Analyse von Connect-Aufrufen kann primedocs Desktop jeden empfangenen Connect-Aufruf als eigene Datei speichern. Die Aufzeichnung wird unter primedocs › Optionen › primedocs Connect mit Protokollierung aktivieren eingeschaltet und endet aus Datenschutzgründen 24 Stunden nach der Aktivierung automatisch.

• Ablage: %TEMP%\primedocsConnectLogger, eine Datei pro Aufruf mit dem Zeitpunkt in UTC als Namen (yyyyMMdd_HHmmss_fff.txt).
• Inhalt: Das empfangene Connect-XML. Es kann Personendaten enthalten.
• Öffnen: Mit Connect-Protokollordner öffnen im selben Bereich.