Java Rendering Library 4.3-R34458 : Logging

Overview

By default, any log output (beside critical information, such as license order, which is written to stdout) of the pdf renderer and InDesign® Server is suppressed.

Logging can be enabled by attaching a logger (org.slf4j.Logger or better ch.qos.logback.classic.Logger ) to the Renderer instance.

The InDesign® Server extension requires a ch.qos.logback.classic.Logger implemented in the logback library. Other logger implementations will cause an InitializationException when being applied to renderers managed by the InDesignServerFactory.
We recommend using the logback library for all log output

Enabble Log Output for PDF Renderer

org.slf4j.Logger logger = org.slf4j.LoggerFactory.getLogger("my.logger.name");
try {
  // simple way: use the class / package logger for pdf renderer output
  ((Renderer) renderer).setLogger(logger, PdfRendererFactory.class);
} 
catch (RendererException e) {
  // something went wrong when attaching the logger...
}

It's as simple as that...

The logger is attached to all renderer instances. At the time it is not possible to attach a distinct logger for a particular instance, but it is possible to attach a distinct logger for all instances of a particular factory.

The LogLevel is automatically determined from the org.slf4j.Logger object provided, this LogLevel is also applied to the native renderer instance (i.e.: messages with lower severity than supported by the logger are supressed). You can

change the logger at any time. This also changes the log level for all instances
change the log level for a particular instance via Renderer Observers

Details regarding Renderer Observers can be found here.

Logging with InDesign® Server

Log output of InDesign® Server cannot just be redirected to a Java logger, but we can at least configure certain aspects of logging by aplying a ch.qos.logback.classic.Logger instnce to InDesign® Server renderers.

This requires some configuration steps

Setup logback.xml Configuration

<configuration debug="true"> 
 <appender name="IDSLOG" class="ch.qos.logback.core.FileAppender">
  <file>C:\comet\log\testlog-$INSTANCE_NAME.log</file>
  <encoder>
    <pattern>%d %p %c{1} [%t] %m</pattern>
  </encoder>
 </appender>
 <logger name="com.priint.comet.renderer.ids" level="TRACE">
 	<appender-ref ref="IDSLOG" />
 </logger>
</configuration>

Remarks

we support ch.qos.logback.core.FileAppender and ch.qos.logback.core.rolling.RollingFileAppender. Configuration of either of these appenders must be complete and correct. However, currently only the common “FileAppender” features are supported with InDesign® Server

the $INSTANCE_NAME term in the file element value is replaced by the name of the actual InDesign® Server instance. This can be set in the InDesignServerConfiguration:

InDesignServerConfiguration config = 
  new InDesignServerConfiguration("http://server.host:4711");
// name of log file in this case will be 
//    testlog-hooky.log
config.setName("hooky");

if name is not set, the port of the endpoint will be used as INSTANCE_NAME
we must define a specific logger, in this case the one named "com.priint.comet.renderer.ids", this logger must explicitly refer to the appender we defined. It is not enough to just configure root.

Implementation Details

We must create an instance of the logger configured in logback.xml and apply this to renderers as follows:

org.slf4j.Logger logger = 
  LoggerFactory.getLogger("com.priint.comet.renderer.ids");
((Renderer) renderer).setLogger(logger);

Note: We must use exactly the name ("com.priint.comet.renderer.ids") as configured in logback xml. The following will not work (because we don’t refer to exactly the configured logger):

org.slf4j.Logger logger = LoggerFactory.getLogger("com.priint.comet.renderer.ids.MyApplication");

Probably you want to apply this specific logger to InDesign® Server renderers only (other renderer engines e.g. cannot resolve the log output filename properly).

You can do so using this code:

((Renderer) renderer).setLogger(logger, InDesignServerFactory.class);

Patterns

We can use the same log pattern configuration like for "normal" Java logback loggers, but not all markers provide useful output. E.g. %t will output the process ID rather than the thread name (because InDesign® is basically a single threaded application).

At least, using the same pattern as for Java loggers, the log output of InDesign® / Comet should be syntactically compatible to the output of the Java logger.

Changing Log Level

Note: If you set the level for log messages for a particular instance e.g. to debug, but the logger only supports info level messages, the renderer will propagate debug messages to the Java Logger, but they are not written anyway. You must

configure the org.slf4j.Logger to support the minimum severity you want to be written for any instance / operation
override the log level determined from the Logger via explicit setLogLevel calls in Renderer Observer methods

This is probably harder to explain, than to understand. The following example should give you an idea:

import org.slf4j.LoggerFactory;

import com.priint.comet.renderer.EventChain;
import com.priint.comet.renderer.LogLevel;
import com.priint.comet.renderer.Renderer;
import com.priint.comet.renderer.Subject;
import com.priint.comet.renderer.exception.RendererException;

public class ConfigureLogger {
  public void configureLogger() {
    
    try {
      // we assume, defaultLogger supports up to 'trace' level:
      org.slf4j.Logger defaultLogger = LoggerFactory.getLogger("my.default.logger");
      Renderer.setLogger(defaultLogger);
      
      // initially we want the log level to be set to 'info'.
      // The CONNECT_BEFORE event is suitable for that purpose:
      Renderer.addObserver(
          (subject, instance, data) -> {
            instance.setLogLevel(LogLevel.INFO);
            return EventChain.CONTINUE;
          },
          Subject.CONNECT_BEFORE);
      
      // when running a build command, we want the log level to be set to 'trace'
      Renderer.addObserver(
          (subject, instance, data) -> {
            instance.setLogLevel(LogLevel.TRACE);
            return EventChain.CONTINUE;
          },
          Subject.BUILD_BEFORE);
      
      // ... and be reset afterwards
      Renderer.addObserver(
          (subject, instance, data) -> {
            instance.setLogLevel(LogLevel.INFO);
            return EventChain.CONTINUE;
          },
          Subject.BUILD_AFTER);
    }
    catch (RendererException e) {
      
    }
  }
}