|Maintenance Notice - PDF Generation|
|Dynamic PDF generation for web-based content is temporarily unavailable. This maintenance affects dynamic PDF files that are generated from either the HTML-based page or manual that you are viewing. Links that normally allow this functionality have been hidden, and will reappear as soon as the feature is restored.
Setting up Logging in Platform SDK
Using the Built-In Logging Implementation
The Platform SDK Commons library provides adapters for the following implementations:
- com.genesyslab.platform.commons.log.SimpleLoggerFactoryImpl - redirect Platform SDK logs to System.out;
- com.genesyslab.platform.commons.log.JavaUtilLoggerFactoryImpl - redirect Platform SDK logs to Java common java.util.logging logging system;
- com.genesyslab.platform.commons.log.Log4JLoggerFactoryImpl - redirect Platform SDK logs to underlying Log4j 1.x;
- com.genesyslab.platform.commons.log.Log4J2LoggerFactoryImpl - redirect Platform SDK logs to underlying Log4J 2;
- com.genesyslab.platform.commons.log.Slf4JLoggerFactoryImpl - redirect Platform SDK logs to underlying Slf4j.
|Note: Prior to release 8.5.102.02, the only log adapter available was for log4j v1.x and short names were not available.|
By default, these log implementations are switched off but you can enable logging by using one of the methods described below.
1. In Your Application Code
The easiest way to set up Platform SDK logging in Java is in your code, by creating a factory instance for the log adapter of your choice and set it as the global logger factory for Platform SDK at the beginning of your program. An example using the log4j 1.x adapter is show here:
2. Using a Java System Variable
Using a Java system variable, by setting com.genesyslab.platform.commons.log.loggerFactory to the fully qualified name of the ILoggerFactory implementation class. For example, to set up log4j as the logging implementation you can start your application using the following command:
java -Dcom.genesyslab.platform.commons.log.loggerFactory=<log_type> <MyMainClass>
Where <log_type> is either a full-defined class names with packages, or one of the following short names:
- console - for SimpleLoggerFactoryImpl (to System.out);
- jul - for JavaUtilLoggerFactoryImpl;
- log4j - for the Log4J 1.x adaptor;
- log4j2 - for the Log4J 2 adaptor;
- slf4j - for the Slf4j adaptor;
- auto - with this value, Platform SDK Commons logging tries to detect available the logging system from the list of ['Log4j2', 'Slf4j', 'Log4j']; if no log system from the list is detected then the JavaUtilLoggerFactoryImpl adapter will be used.
3. Configuration in the Class Path
You can also configure logging using a PlatformSDK.xml Java properties file that is specified in your class path:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <entry key="com.genesyslab.platform.commons.log.loggerFactory">com.genesyslab.platform.commons.log.Log4JLoggerFactoryImpl</entry> </properties>
For more information, refer to details about the PsdkCustomization class in the API Reference Guide.
Providing a Custom Logging Implementation
If log4j does not fit your needs, it is also possible to provide your own implementation of logging.
In order to do that, you will need to complete the following steps:
- Implement the ILogger interface, which contains the methods that the Platform SDK uses for logging messages, by extending the AbstractLogger class.
- Implement the ILoggerFactory interface, which should create instances of your ILogger implementation.
- Finally, set up your ILoggerFactory implementation as the global Platform SDK LoggerFactory, as described above.
Setting Up Internal Logging for Platform SDK
To use internal logging in Platform SDK, you have to set a logger implementation in Log class before making any other call to Platform SDK. There are two ways to accomplish this:
- Set the com.genesyslab.platform.commons.log.loggerFactory system property to the fully qualified name of the factory class
- Use the Log.setLoggerFactory(...) method
One of the log factories available in Platform SDK itself is com.genesyslab.platform.commons.log.Log4JLoggerFactoryImpl which uses log4j. You will have to setup log4j according to your needs, but a simple log4j configuration file is shown below as an example.
log4j.logger.com.genesyslab.platform=DEBUG, A1 log4j.appender.A1=org.apache.log4j.FileAppender log4j.appender.A1.file=psdk.log log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %-25.25c %x - %m%n
The easiest way to set system property is to use -D switch when starting your application:
Logging with AIL
In Interaction SDK (AIL) and Genesys Desktop applications, you can enable the Platform SDK logs by setting the option log/psdk-debug = true.
At startup, AIL calls: Log.setLoggerFactory(new Log4JLoggerFactoryImpl());
The default level of the logger com.genesyslab.platform is WARN (otherwise, applications would literally be overloaded with logs). The option is dynamically taken into account; it turns the logger level to DEBUG when set to true, and back to WARN when set to false.
Platform SDK has several specialized loggers:
Dedicated ADDP Logger
ADDP logs can be enabled using common Platform SDK log configuration.
log4j.logger.com.genesyslab.platform=INFO, A1 log4j.appender.A1=org.apache.log4j.FileAppender log4j.appender.A1.file=psdk.log log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %-25.25c %x - %m%n
In addition, the com.genesyslab.platform.ADDP logger is controlled by the addp-trace option. If ADDP log is not required on INFO level, it can be disabled using the following option:
PropertyConfiguration config = new PropertyConfiguration(); config.setAddpTraceMode(AddpTraceMode.None);
The addp-trace option has no effect when DEBUG level is set. ADDP logs will be printed regardless of the option value.
Instead of using second ADDP logger to print logs to another file, it is possible to specify additional appender.
A sample configuration is provided below:
log4j.logger.com.genesyslab.platform=WARN, A1 log4j.appender.A1=org.apache.log4j.ConsoleAppender log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%-d [%t] %-5p %-25.25c %x - %m%n log4j.appender.A1.Threshold=WARN //additional log file with addp traces. log4j.logger.com.genesyslab.platform.ADDP=INFO, A2 log4j.appender.A2=org.apache.log4j.FileAppender log4j.appender.A2.file=addp.log log4j.appender.A2.append=false log4j.appender.A2.layout=org.apache.log4j.PatternLayout log4j.appender.A2.layout.ConversionPattern=%-d [%t] %-5p %-25.25c %x - %m%n
Dedicated Request and Receive Loggers
A sample Log4j configuration is shown here:
log4j.logger.com.genesyslab.platformmessage.request=DEBUG, A1 log4j.logger.com.genesyslab.platformmessage.receive=DEBUG, A1
These loggers allow printing complete message attribute values. By default, large attribute logs are truncated to avoid application performance impact:
'EventInfo' (2) attributes: VOID_DELTA_VALUE [bstr] = 0x00 0x01 0xFF 0xFF 0x00 0x05 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x09 0x00 0x00 0x00 0x05 0x00 0x00 0x00 0x00 0x00 ... [output truncated, 362 bytes left out of 512]
However, in some cases a full data dump may be required in logs. There are three possible ways to do this, as shown below:
1. Activate using system properties:
-Dcom.genesyslab.platform.trace-messages=true //for all protocols -Dcom.genesyslab.platform.Reporting.StatServer.trace-messages=true //only for stat protocol
2. Activate from code:
//for all protocols PsdkCustomization.setOption(PsdkOption.PsdkLoggerTraceMessages, "false"); //only for stat protocol String protocolName = StatServerProtocolFactory.PROTOCOL_DESCRIPTION.toString(); PsdkCustomization.setOption(PsdkOption.PsdkLoggerTraceMessages, protocolName, "true");
These static options should be set once at the beginning of the program, before opening Platform SDK protocols.
3. Activate from PlatformSDK.xml:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <entry key="com.genesyslab.platform.trace-messages">true</entry> </properties>
For details about the PsdkCustomization class, refer to the API Reference Guide.
Setting up Logging
For .NET development, the EnableLogging method allows logging to be easily set up for any classes that implement the ILogEnabled interface. This includes:
- All protocol classes: TServerProtocol, StatServerProtocol, etc.
- The WarmStandbyService class of the Warm Standby Application Block.
Providing a Custom Logging Implementation
You can provide your custom logging functionality by implementing the ILogger interface. Samples of how to do this are provided in the following section.
You can download some samples of classes that implement the ILogger interface:
- AbstractLogger: This class can make it easier to implement a custom logger, by providing a default implementation of ILogger methods.
- TraceSourceLogger: A logger that uses the .NET TraceSource framework. It adapts the Platform SDK logger hierarchy to the non-hierarchical TraceSource configuration.
- Log4netLogger: A logger that uses the log4net libraries.