Customized log output.

Version :
Plugin Version 4.1.8, preview in 4.1.7

Customized log output.

The logger module allows configuring of log outputs written by InDesign, InDesignServer, PDF Renderer or Illustrator Plugins.
Main target is:

The cscript functions of the logger module are not required for this, mainly the extended logging support is activated via a XML configuration file.
The internal architecture is based on the SLF4J API, the configuration adopts the format of the XML configuration files for the logback SLF4J implementation.
This allows, to use configuration setup for the PublishingServer more or less without changes for InDesign / Comet configuration.

This documentation concentrates on configuration issues.

A logback configuration setup for PublishingServer can directly be used to configure InDesign / InDesignServer, PDF Renderer or Illustrator log configuration.

All configuration directives valid for logback are accepted in the Comet-Context, but not all are supported

Main restrictions

Writing of formatted log messages is activated by ceating a file names log.xml in the installation folder of the InDesign / Illustrator Plugins resp. PDF Renderer - if this file contains at least one valid configuration for the appropriate Plugin or Renderer.

Two short examples:

Example 1: add date prefix to each log message

Create a file named log.xml in the installation folder of InDesign / Illustrator Plugins with content as follows:

<?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>
Restart InDesign and verify log messages written after log initialization.

Example 2: Output log messages of the placeholder Plugin into a separate file

Create a XML file named log.xml in the installation folder of the InDesign / Illustrator Plugins with content as follows:

<?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>
Restart InDesign and verify log messages written after log initialization.

Log messages

The following log levels are supported (the numbers refer to level values in cscript):

A message is written, if it's priority is less or equal than the priority of the appropriate logger.
Example:
  <logger name="com.priint.indesign.comet" level="INFO">

A couple of categories are predefined for the priint:comet Plug-Ins and PDF rennderer.

The actual name of the category depends on the host application, the version and the platform (server or desktop). However, we use a "normalized" name to determine the appropriate configuration, so loggers can be configured independent of the host application, version etc.

In the following, Instead of "hostapp", you can use the name and version of the actual application, e.g. "indesigncc2018" or "indesign2020server" - as long, as you respect the schema "com.priint.<host-application>.<pluginname>".

The following categories are defined:

A configuration defined for com.priint.hostapp.pluginname is also valid for com.priint.hostapp, if no configuration is available for the higher level category..
The same applies for com.priint.hostapp.pluginname.submodule.

If no configuration is available for the category of a log message, the configuration of the nearest higher level category is used.
By definition, the top level category is "root". This configuration is used for all messages, unless a more specific configuration is defined for their category. Example:

<!--  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");

We use a PatternLayout to format log messages before printing, that means: the output format can be determined using a pattern.
The pattern can contain string literals and various markers, which are replaced by the message context. Furthermore, string escaping can be set for all content (except for string literals) being printed.

As obvious, the format of the log output can be specified using a pattern.
A pattern is a sequence of arbitrary markers and / or string literals. Each log message is formatted according to this pattern.
Markers are decorated with the percent sign '%'. The terminating marker of a pattern should be %n, otherwise subsequent log output is coninued in the same line.
The following markers are supported:
Specifier Name Description Example
- / . [0-9] Format Modifier All markers can be preceeded by a format modifier. This allows padding or truncation of the output.
Valid definitions are:
  • %[0-9]+marker: left pad with white spaces, if output is shorter than n characters
  • %-[0-9]+marker: right pad with white spaces, if output is shorter than n characters
  • %.[0-9]+marker: truncate from left to n
  • %[0-9]+.[0-9]+marker: left pad to n characters, if output is shorter or truncate from left, if output is longer than m characters
  • %-[0-9]+.[0-9]+marker: right pad to n characters, if output is shorter or truncate from right, if output is longer than m characters
  • %-.[0-9]+marker: truncate from right to n characters
%-12.20logger
%m %msg %message Message The actual message %m
%.80message
%n Line Break sic %n
%c %lo %logger Logger Name of the logger / of the category Module: %lo
%p %le %level Log Level / Priority Priority of the message, i.e. ERROR, WARNING, INFO, DEBUG or TRACE level=[%-7level]
%r %relative Relative Time in milliseconds since initialisation of this logger time since startup=%r
%R %absolute Absolute Unix epoch time since 1970-01-01 timeMillis=%R
%rr Difference Time in milliseconds since the last event was sent by the same logger. since last event=%rr
%d %date Date / Timestamp Timestamp when the message was generated, if not specified other in ISO8601 format.
The output format can be specified in the syntax valid for the Java SimpleDateFormat class. Internally, this is translated to (C) strftime, so not all SimpleDateFormat markers are supported.
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 Calling context. The actual property must be specified in curly brackets.
The following properties are supported:
  • USER: System user
  • HOST: Host name
  • SESSION: current session ID (only available, when connected to a SOAP service)
  • CONNECTION: Label of the current connection
  • PROJECT: Name of the Comet project
  • LOGIN: Database or SOAP login name
  • CACHE: Current cache folder
  • COMET: Installation path of the Comet plugins
  • PLUGINS: Plugin folder
  • XML: current XML folder (only available, when connected to a XML folder)
  • ENV:<property>: Environment variable
Other key words will cause the output "Unknown property"
Session=%X{SESSION}
%property Environment Variable Output of an arbitrary environment variable executable path=%property{PATH}
%t %thread Thread Outputs the ID of the running process pid=%t
%method
%M
%marker
%class
%C
%cn
%caller
%replace
%rEx
%rootException
%throwable
%xEx
%xEception
%xThrowable
%exception
%ex
%nopex
%nopexception
%line
%L
%file
%F
Not Supported These markers are simply skipped, when generating the log output.
Markers other than defined, will cause the output "[Undefined %s{%s}]"
 

In addition, the following rules apply:

Depending on the output format, it may be necessary to escape string contents. This can be defined via the stringEscaping element:

<encoder>
 	<pattern>...</pattern>
 	<stringEscaping>JSON</pattern>
</encoder>
Possible values are:

Example 1: print messages as XML fragments

<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>

Example 2: print messages as serialized JSON objects

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

In cscript, log messages can be written using the wlog or wtlog function.
The default category for these messages is com.priint.hostapp.comet<variant>.cscript. This category can be changed as follows:

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

The priority of wlog resp. wtlog messages can be set via the scriptLevel atttribute:

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

Some logger properties can be changed on runtime in cscript. These changes refer to a certain category, which must be configured in the log.xml configuration file.
If no configuration exists for this category, the chnages are applied to the nearest higher level category, which is configured in the log.xml file.

The following properties / functions are supported:

With these functions, the priority or verbosity of log messages can be changed e.g. for particular placeholders.

A complete and documented XML configuration file can be found here

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

Print a log message with the given priority to the logger specified by category.

A suitable configuration must exist for this category or any of it's ancestors, otherwise nothing is printed (see general configuration hints for this module above).
If category is empty, the standard category (e.g. com.priint.indesigncc2020.comet) is used. The format string can contain markers for further values. For these values suitable parameters must be provided.

Name Type Default Description
Return int   0 or error codes
priority int - Log level, 100 (= error), 200 (= warning), 300 (= info), 400 (= debug) oder 500 (= trace)
category char * or String - Name of the logger / category
format char * or String - Format string
... - - Further parameters according to markers in format string

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

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

Print a log message with the priority error to the logger specified by category.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
format char * or String - Format string
... - - Further parameters according to markers in format string

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

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

Print a log message with the priority warning to the logger specified by category.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
format char * or String - Format string
... - - Further parameters according to markers in format string

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

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

Print a log message with the priority info to the logger specified by category.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
format char * or String - Format string
... - - Further parameters according to markers in format string

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

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

Print a log message with the priority debug to the logger specified by category.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
format char * or String - Format string
... - - Further parameters according to markers in format string

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

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

Print a log message with the priority trace to the logger specified by category.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
format char * or String - Format string
... - - Further parameters according to markers in format string

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

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

Set the pattern of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
pattern char * oder String - New pattern string

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

static char* get_pattern(char* category)

Get the pattern of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return char *   Pattern string of this category
category char * or String - Name of the logger / category

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

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

Set escaping of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
escaping char * or String - New escaping, e.g. XML, JSON, NONE...

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

static char* get_escaping(char* category)

Get escaping of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return char *   Escaping of this category, e.g. JSON, XML ...
category char * or String - Name of the logger / category

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

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

Set log path of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
path char * or String - New path of log file

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

static char* get_path(char* category)

Get log path of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return char *   Path of log file of this category
category char * or String - Name of the logger / category

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

static int set_level(char* category, int level)

Set log level of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return int   0 or error codes
category char * or String - Name of the logger / category
level int - New log level of category

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

static int get_level(char* category)

Get log level of a category. The category or any of it's ancestors must be configured in the log.xml file.

Name Type Default Description
Return int   Log level of this category
category char * or String - Name of the logger / category

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

static int reload_config()

Reload all configurations from log.xml.

Name Type Default Description
Return int   0 oder error codes

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

Plugin Version 4.1.8, preview in 4.1.7
12.03.2024, 15:56 Uhr

Alphabetic index HTML hierarchy of classes or Java