Schreiben von formatierten Logausgaben.

Letzte Änderung :
Plugin Version 4.1.8, in 4.1.7 als Preview

Schreiben von formatierten Logausgaben.

Das Logger Modul dient der Steuerung von Logausgaben der InDesign bzw. InDesignServer Plugins, des PDF Renderers sowie von Logausgaben aus cscript (mittels wlog oder wtlog).

Hauptziel ist

Die cscript Funktionen des Moduls werden hierfür nicht benötigt, wohl aber eine Konfigurationsdatei, um das erweiterte Logging überhaupt zu aktivieren.
Aus naheliegenden Gründen lehnt sich die interne Architektur an das SLF4J API an, die Konfiguration des Moduls erfolgt über eine XML-Datei, die direkt aus bestehenden logback XML Konfigurationen abgeleitet werden kann.

Hauptaugenmerk dieser Dokumentation liegt daher auf der Konfiguration des logger Moduls.

Eine bspw. für den PublishingServer erstellte logback-Konfiguration kann direkt auch für InDesign / InDesignServer Plugins oder den PDF Renderer verwendet werden.

Alle für logback validen Direktiven werden auch in Comet-Komponenten akzeptiert, aber nicht alle unterstützt

Namentlich

Durch Konfiguration des Loggers werden die "traditionellen" Logausgaben der InDesign Plugins bzw. des PDF Renderers deaktiviert.

Die Ausgabe formatierter Logmeldungen wird durch Anlegen einer XML-Datei namens log.xml aktiviert - sofern diese Datei mindestens eine gültige Konfiguration für das jeweilige Plugin bzw. den PDF-Renderer enthält. Nach der Datei log.xml wird (in dieser Reihenfolge) an folgenden Orten gesucht:

  1. Im Ordner werkii Ihrer Voreinstellungen ($PREFS/werkii)
  2. Im Ordner der priint:comet Plugins bzw. von comet_pdf ($COMET)
Wird die Datei log.xml nicht gefunden, ist leer oder fehlerhaft, wird das Standard-Logformat verwendet.

Zwei einfache Beispiele hierzu:

Beispiel 1: Voranstellen eines Datums an alle Logausgaben

Legen Sie eine XML-Datei namens log.xml im Installationsverzeichnis der Plugins bzw. des PDF Renderers mit folgendem Inhalt an: 

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 	<appender name="stdlog" class="RollingFileAppender">
 		<file>$LOGFILE</file>
 		<encoder>
 			<pattern>[%d{ISO8601}] %m%n</pattern>
 		</encoder>
 	</appender>
 	<root level="TRACE">
 		<appender-ref ref="stdlog" />
 	</root>
</configuration>
Starten Sie InDesign bzw. den PDF Renderer. Bis zur Initialisierung des logger-Moduls werden Logausgaben wie gewohnt geschrieben, danach in dem in der XML-Datei festgelegten Format.

Beispiel 2: Herausschreiben aller Logmeldungen des Platzhalter-Plugins in eine separate Datei

Legen Sie eine XML-Datei namens log.xml im Installationsverzeichnis der Plugins bzw. des PDF Renderers mit folgendem Inhalt an: 

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="true" scan="true" scanPeriod="60 seconds">
 	<appender name="placeholder-logs" class="RollingFileAppender">
 		<file>$LOGBASENAME.placeholders.log</file>
 		<encoder>
 			<!-- include date, unix epoch and session id in log messages -->
 			<pattern>%d, timeMillis=%R, session=%X{SESSION} %m%n</pattern>
 		</encoder>
 	</appender>
 	<logger name="com.priint.indesign.placeholders" level="TRACE">
 		<appender-ref ref="placeholder-logs" />
 	</logger>
 	<!-- all other log categories go here -->
 	<appender name="stdlog" class="RollingFileAppender">
 		<file>$LOGFILE</file>
 		<encoder>
 			<pattern>%m%n</pattern>
 		</encoder>
 	</appender>
 	<root level="ALL">
 		<appender-ref ref="stdlog" />
 	</root>
</configuration>
Starten Sie InDesign bzw. den PDF Renderer. Bis zur Initialisierung des logger-Moduls werden Logausgaben wie gewohnt geschrieben, danach in dem in der XLM-Datei festgelegten Format.

Nachrichten

Folgende Level werden unterstützt (die Zahlenwerte bezeichnen den in entsprechenden cscript-Funktionen zu verwendenden Wert):

Eine Nachricht wird ausgegeben, wenn Ihre Priorität gleich oder niedriger ist als der für den zuständigen Logger (bzw. der "Kategorie") konfigurierte Level.
Beispiel: 
<logger name="com.priint.indesign.comet" level="INFO">

Für die comet Plugins bzw. den PDF Renderer sind eine Reihe von Kategorien vorgegeben.

Die genaue Bezeichnung der Kategorie hägt von der jeweiligen InDesign / Illustrator Version und Plattform (Desktop / Server) ab. Jedoch wird für die Ermittlung der passenden Konfiguration ein "normalisierter" Name verwendet, so dass Konfigurationen unabhängig von der Version der jeweiligen Host-Applikation verwendet werden können.

Statt "hostapp" kann im Folgenden ebenso "indesigncc2018" oder "indesign2020server" oder auch einfach "whatever" eingetragen werden - wichtig ist die Einhaltung des Schemas "com.priint.<host-application>.<pluginname>".

Folgende Kategorien sind definiert:

Eine für com.priint.hostapp.pluginname hinterlegte Konfiguration ist auch für com.priint.hostapp gültig, sofern nicht für diese übergeordnete Kategorie eine andere Konfiguration hinterlegt ist.
Sinngemäß gilt dies auch für com.priint.hostapp.pluginname.submodul etc.

Sofern für eine Kategorie einer Lognachricht keine Konfiguration vorliegt, wird die Konfiguration der jeweilig übergeordneten Kategorie verwendet.
Oberste Kategorie ist "root" - diese Konfiguration wird für alle Nachrichten verwendet, für die keine spezifische Konfiguration verfügbar ist. Beispiel: 

<!--  log xml: -->
<logger name="com.priint.indesigncc2017" level="TRACE">
<root level="WARNING">
// cscript:
//
logger::info ("com.priint.indesign.my-custom-module", "Important info");
logger::info ("com.my-company.project.xy", "Another important info");

Zur Ausgabe der Lognachrichten wird ein PatternLayout verwendet, d.h.: das Ausgabeformat kann über ein Muster festgelegt werden.
Das Muster kann String-Literale und eine Reihe unterstützter Marker, die bei Ausgabe aus dem jeweiligen Nachruchten-Kontext mit Inhalt gefüllt werden, enthalten. Zudem kann die Maskierung sämtlicher Nachrichteninhalte (also nicht der String-Literale) festgelegt werden.

Unterstützte Marker

Wie aus den obigen Beispielen ersichtlich, kann das Format der Ausgabe durch ein pattern festgelegt werden.
Ein Pattern ist eine Aneinanderreihung von Markern und / oder String literalen, jede auszugebende Nachricht wird anhand dieser Vorlage formatiert.
Marker werden mit dem Prozenzeichen '%' ausgezeichnet. Als abschließender Marker eines Patterns sollte immer %n (= Leerzeile) angegeben werden, ansonsten wird die folgende Logausgabe in derselben Zeile fortgesetzt.
Folgende Marker werden unterstützt:
Specifier Bezeichnung Beschreibung Beispiel
- / . [0-9] Format Modifier Allen Marker kann ein Format Modifier vorangestellt werden. Damit kann die Ausgabe auf eine bestimmte Länge beschränkt oder erweitert werden.
Mögliche Angaben sind:
  • %[0-9]+marker: n Leerzeichen links anfügen, sofern die Ausgabe kürzer ist
  • %-[0-9]+marker: n Leerzeichen rechts anfügen, sofern die Ausgabe kürzer ist
  • %.[0-9]+marker: Ausgabe auf n Zeichen begrenzen, von links abschneiden
  • %[0-9]+.[0-9]+marker: Mindestens n, aber maximal m Zeichen ausgeben, links anfügen und links abschneiden
  • %-[0-9]+.[0-9]+marker: Mindestens n, aber maximal m Zeichen ausgeben, rechts anfügen und links abschneiden
  • %-.[0-9]+marker: Ausgabe auf n Zeichen begrenzen, von rechts abschneiden
 %-12.20logger
%m %msg %message Nachricht Die eigentliche Nachricht. %m
%.80message
%n Zeilenumbruch Zeilenumbruch %n
%c %lo %logger Logger Name des Loggers / der Kategorie Modul: %lo
%p %le %level Loglevel / Priorität Priorität der Nachricht, also ERROR, WARNING, INFO, DEBUG oder TRACE level=[%-7level]
%r %relative Relative Zeit in Millisekunden seit Initialisierung dieses Loggers time since startup=%r
%R %absolute Absolute Zeit in Millisekunden seit 01.01.1970 timeMillis=%R
%rr Difference Zeit in Millisekunden seit dem letzten Event dieses Loggers since last event=%rr
%d %date Datum / Timestamp Zeitpunkt der Nachricht, sofern nicht anders angegeben in ISO8601 Format.
Für das Ausgabeformat kann die für die Java Klasse SimpleDateFormat gültige Notation verwendet werden. Intern wird dies in einen strftime Format-String übersetzt, daher sind nicht alle Angaben möglich. Unterstützt werden:
Marker strftime Beschreibung
y %y %Y Year
Y %g %G Week year
M %m %b %B Month in year (context sensitive)
L %m %b %B Month in year (standalone form)
w %W Week in year
D %j Day in year
d %d Day in month
E %a %A Day name in week
u %u Day number of week (1 = Monday, ..., 7 = Sunday)
a %p Am/pm marker
H %H Hour in day (0-23)
h %I Hour in am/pm (1-12)
m %M Minute in hour
s %S Second in minute
S emulated Millisecond
z %Z General time zone
X 'abc'>%z ISO 8601 time zone
'abc' String literal String literale in Formatstrings müssen mit Hochkommata (') maskiert werden
%date{YYYY-MM-dd'T'HH:mm:ss.SSSz}
%mdc %X Context Aufruf-Kontext. Die auszugebende Eigenschaft muss in geschweiften Klammern angegeben werden.
Unterstützt werden:
  • USER: System-Benutzer
  • HOST: Host-Name des ausführenden Rechners
  • SESSION: ID der aktuellen Session (nur bei aktiver SOAP Verbindung)
  • CONNECTION: Label der aktuellen Verbindung
  • PROJECT: Name des Comet Projekts
  • LOGIN: Datenbank / SOAP Login
  • CACHE: aktueller Cache-Ordner
  • COMET: Installationspfad der Comet Plugins
  • PLUGINS: Ordner der Plugins
  • XML: aktueller XML-Ordner (nur bei XML Offline Verbindungen)
  • ENV:<property>: Umgebungs-Variable
Andere Schlüsselworte führen zur Ausgabe "Unknown property" 		Session=%X{SESSION}
%property Umgebungsvariable Ausgabe einer beliebigen Umgebungsvariable executable path=%property{PATH}
%t %thread Thread Entgegen der Java-Implementierung wird hier immer die ID des aktuellen System-Prozesses ausgegeben pid=%t
%method
%M
%marker
%class
%C
%cn
%caller
%replace
%rEx
%rootException
%throwable
%xEx
%xEception
%xThrowable
%exception
%ex
%nopex
%nopexception
%line
%L
%file
%F 		Nicht unterstützt Diese Marker werden bei der Ausgabe einfach übersprungen.
Andere als die definierten Marker führen zur Ausgabe "[Undefined %s{%s}]" 		 

Weiterhin gilt:

Je nach Ausgabeformat kann es erforderlich sein, bestimmte Zeichen der Nachrichteninhalte zu maskieren. Dies kann durch das Element stringEscaping angegeben werden: 

<encoder>
 	<pattern>...</pattern>
 	<stringEscaping>JSON</pattern>
</encoder>
Mögliche Angaben sind:

Beispiel 1: Ausgabe der Lognachrichten als XML Fragmente 

<encoder>
 	<pattern>
&lt;message&gt;
&lt;date&gt;%d{ISO8601}&lt;/date&gt;
&lt;content&gt;%m&lt;/content&gt;
&lt/message&gt;%n
 	</pattern>
 	<stringEscaping>XML</pattern>
</encoder>

Beispiel 2: Ausgabe der Lognachrichten als JSON Objekte 

<encoder>
 	<pattern>{ "date": "%d{ISO8601}", "content": "%m" }%n</pattern>
 	lt;stringEscaping>JSON</pattern>
</encoder>

In cscript können Logmeldungen durch Aufruf der Funktionen wlog bzw. wtlog oder eine der u.g. Funktionen des logger-Moduls ausgegeben werden.
Die logger-Funktionen erfordern die Angabe einer Kategorie, Ausgaben der wlog Funktionen werden standardmäßig der Kategorie com.priint.hostapp.comet<variant>.cscript zugeordnet.
In der Konfiguration kann dies geändert werden: 

<configuration >
 	<scriptLogger="com.priint.indesign.wlog-messages" />
  ...

Die Priorität der mit wlog bzw. wtlog ausgegegeben Nachrichten kann mit dem Attribut scriptLevel festgelegt werden: 

<configuration >
 	<comet scriptLevel="DEBUG" />
  ...

Bestimmte Eigenschaften der Logger können zur Laufzeit in cscript beeinflusst werden. Die änderungen beziehen sich immer auf eine bestimmte Kategorie. Voraussetzung ist, dass für diese Kategorie oder eine gültige übergeordnete Kategorie eine Konfiguration in der Datei log.xml vorliegt.

Folgende Eigenschaften / Funktionen werden unterstützt:

Auf diese Weise kann skriptgesteuert z.B. die Priorität für die Ausgaben eines bestimmten Platzhalters geändert werden.

Eine vollständige, kommentierte XML Konfigurationsdatei finden Sie hier

static int logger::log(
  int priority,
  char* category,
  char* format,
  ...)

Gib eine Logmeldung mit der angegebenen Priorität und Kategorie aus.

Für die Kategorie muss eine geeignete Konfiguration vorliegen (siehe allgemeine Hinweise zum Modul). Ist die Kategorie leer, wird die Standard-Kategorie des Plugins verwendet (z.B. com.priint.indesigncc2020.comet).
Der Format-String kann Markierungen für weitere Werte enthalten, für diese müssen entsprechend weitere Parameter angegeben werden.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
priority int - Log level, 100 (= error), 200 (= warning), 300 (= info), 400 (= debug) oder 500 (= trace)
category char * oder String - Name des Loggers / der Kategorie
format char * oder String - Format string
... - - Weitere Parameter entsprechend der Marker im Format String

4.1.8 R27286
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.log

static int logger::error(
  char* category,
  char* format,
  ...)

Gib eine Logmeldung mit der Priorität error für die angegebene Kategorie aus.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
format char * oder String - Format string
... - - Weitere Parameter entsprechend der Marker im Format String

4.1.8 R27286
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.error

static int logger::warning(
  char* category,
  char* format,
  ...)

Gib eine Logmeldung mit der Priorität warning für die angegebene Kategorie aus.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
format char * oder String - Format string
... - - Weitere Parameter entsprechend der Marker im Format String

4.1.8 R27286
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.warning

static int logger::info(
  char* category,
  char* format,
  ...)

Gib eine Logmeldung mit der Priorität info für die angegebene Kategorie aus.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
format char * oder String - Format string
... - - Weitere Parameter entsprechend der Marker im Format String

4.1.8 R27286
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.info

static int logger::debug(
  char* category,
  char* format,
  ...)

Gib eine Logmeldung mit der Priorität debug für die angegebene Kategorie aus.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
format char * oder String - Format string
... - - Weitere Parameter entsprechend der Marker im Format String

4.1.8 R27286
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.debug

static int logger::trace(
  char* category,
  char* format,
  ...)

Gib eine Logmeldung mit der Priorität trace für die angegebene Kategorie aus.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
format char * oder String - Format string
... - - Weitere Parameter entsprechend der Marker im Format String

4.1.8 R27286
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.trace

static int logger::set_pattern(char* category, char* pattern)

Setze das Ausgabeformat einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
pattern char * oder String - Neuer Pattern string

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.setPattern

static char* logger::get_pattern(char* category)

Ermittle das Ausgabeformat einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return char *   Pattern string dieser Kaegorie
category char * oder String - Name des Loggers / der Kategorie

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.getPattern

static int logger::set_escaping(char* category, char* pattern)

Setze die Maskierung einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
escaping char * oder String - Neue Maskierung, z.B. XML, JSON, C, NONE...

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.setEscaping

static char* logger::get_escaping(char* category)

Ermittle die Maskierung einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return char *   Maskierung dieser Kategorie, z.B. XML, JSON ...
category char * oder String - Name des Loggers / der Kategorie

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.getEscaping

static int logger::set_path(char* category, char* path)

Setze den Ausgabepfad einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
path char * oder String - Neuer Pfad der Logdatei

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.setPath

static char* logger::get_path(char* category)

Ermittle den Ausgabepfad einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return char *   Pfad der Logdateie dieser Kategorie
category char * oder String - Name des Loggers / der Kategorie

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.getPath

static int logger::set_level(char* category, int level)

Setze die Priorität einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode
category char * oder String - Name des Loggers / der Kategorie
int level - Neue Priorität der Kategorie

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.setLevel

static int logger::get_level(char* category)

Ermittle die Priorität einer Kategorie. Die Kategorie oder eine übergeordnete Kategorie müssen in der Datei log.xml konfiguriert sein.

Name Typ Default Beschreibung
Return int   Priorität dieser Kategorie
category char * oder String - Name des Loggers / der Kategorie

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.getLevel

static int logger::reload_config()

Lade alle Konfigurationen erneut aus der log.xml Datei.

Name Typ Default Beschreibung
Return int   0 oder Fehlercode

4.1.8 R27557
priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
comet.logger.reloadConfig

04.08.2025, 11:20 Uhr
Plugin Version 4.1.8, in 4.1.7 als Preview

Alphabetic index HTML hierarchy of classes or Java