Schreiben von formatierten Logausgaben.
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).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:
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):
<logger name="com.priint.indesign.comet" level="INFO">
com.priint.indesign.comet
werden Nachrichten mit der Priorität WARNING
ausgegeben, da WARNING (200) <= INFO (300)com.priint.indesign.comet
werden Nachrichten mit der Priorität DEBUG
nicht ausgegeben, da DEBUG (400) >= INFO (300)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:
|
%-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:
|
%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:
|
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:
timeMillis=%Rms
zur Ausgabe timeMillis=1593672057303ms%%
notiert werdenJe 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:
JSON
oder C
: Maskierung als gültige JSON / C-Strings (bspw. werden Anführungszeichen, Steuerzeichen und das Backslash-Zeichen maskiert)XML
: Maskierung aller XML Sonderzeichen (also <, >, " und &&)URL
BASE64
NONE
(default): keine MaskierungBeispiel 1: Ausgabe der Lognachrichten als XML Fragmente
<encoder> <pattern> <message> <date>%d{ISO8601}</date> <content>%m</content> </message>%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:
logger::reload_config
: Erneutes Laden aller Konfigurationen aus der Datei log.xmllogger::get_level
: Ermitteln der Priorität einer bestimmten Kategorielogger::set_level
: Setzen der Priorität für eine bestimmte Kategorielogger::get_path
: Ermitteln des Ausgabe-Pfads einer bestimmten Kategorielogger::set_path
: Setzen des Ausgabe-Pfads für eine bestimmte Kategorielogger::get_pattern
: Ermitteln des Ausgabe-Musters einer bestimmten Kategorielogger::set_pattern
: Setzen des Ausgabe-Musters für eine bestimmte Kategorielogger::get_escaping
: Ermitteln der Maskierung einer bestimmten Kategorielogger::set_escaping
: Setzen des Maskierung für eine bestimmte Kategoriestatic 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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... |
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 |
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 |
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 |
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 |
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 |
static int logger::reload_config()
Lade alle Konfigurationen erneut aus der log.xml Datei.
Name | Typ | Default | Beschreibung |
Return | int | 0 oder Fehlercode |
Alphabetic index HTML hierarchy of classes or Java