Customized log output.

Customized log output.

• formatting of existing log messages for easier parsing and analysis
• prioritisation and filtering of log messages
• redirection of log mesages to other files / channels

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

• log output is always written to a (regular) file determined by a file path
• output of stacktrace or code markers are not supported
• some features like replace, coloring, adding own conversion specifiers are also not supported

The output of formatted log messages is activated by creating an XML file called log.xml - provided this file contains at least one valid configuration for the respective plugin or comet_pdf. The log.xml file is searched for in the following locations (in this order):

1. in the folder werkii of your preferences ($PREFS/werkii)
2. In the folder of the priint:comet plug-ins resp. of comet_pdf ($COMET)

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>

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>

Log messages

• have a certain priority. In the configuration, this is set by the level attribute.
• are assigned to a certain category. In the configuration, this is the name of the logger.

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

• ERROR (100)
• WARNING (200)
• INFO (300)
• DEBUG (400)
• TRACE (500)

  <logger name="com.priint.indesign.comet" level="INFO">

• for category com.priint.indesign.comet, messages with priority WARNING are written, because WARNING (200) <= INFO (300)
• for category com.priint.indesign.comet, messages with priority DEBUG are suppressed, because DEBUG (400) >= INFO (300)

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:

• com.priint.hostapp.coreservice (coreservlett, coreservicedatabase, ...)
• com.priint.hostapp.datafiles
• com.priint.hostapp.documents
• com.priint.hostapp.embeddedlink
• com.priint.hostapp.framelink
• com.priint.hostapp.framerules
• com.priint.hostapp.pageadaptermodel
• com.priint.hostapp.pageadapter
• com.priint.hostapp.pagetemplatesmodel
• com.priint.hostapp.pagetemplates
• com.priint.hostapp.pageitems
• com.priint.hostapp.placeholdervalues
• com.priint.hostapp.previews
• com.priint.hostapp.placeholder
• com.priint.hostapp.products
• com.priint.hostapp.todolistmodel
• com.priint.hostapp.todolist
• com.priint.hostapp.urllink
• com.priint.hostapp.comettests

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

• "Important Info" is written, because the priority for com.priint.hostapp and all sub-categories is set to "TRACE".
• "Another important info" is not written, because we fall-back to the root configuration, which supports messages with priority WARNING and ERROR only.

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.

In addition, the following rules apply:

• String literals in the log output don't have to be escaped or masked. Everything not recognized as "marker" is treated as a string literal.
• This also applies for characters immediately following a valid marker. timeMillis=%Rms therefore outputs timeMillis=1593672057303ms
• A literal percent sign must be notated as %%

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>

• JSON oder C: escape according to JSON / C string specification
• XML: escape characters reserved in XML (.e. <, >, " and &&)
• URL
• BASE64
• NONE (default): no esacaping

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:

• logger::reload_config: reset and reload all configuration from the log.xml file
• logger::get_level: get the priority of a certain category
• logger::set_level: set the priority of a certain category
• logger::get_path: get the output path of a certain category
• logger::set_path: set the output path of a certain category
• logger::get_pattern: get the pattern of a certain category
• logger::set_pattern: set the pattern of a certain category
• logger::get_escaping: get escaping of a certain category
• logger::set_escaping: set escaping of a certain category