Building VersionOne Integrations with Java (Part 3: Logging)

In this part of the series, we’re going to discuss how to make logging an integral part of your integrations. Here’s where we are in this series:

• Part 1: Introduction
• Part 2: Handling Configurations
• Part 3: Logging (YOU ARE HERE)
• Part 4: Parsing Data
• Part 5: Using a HTTP Client
• Part 6: Getting Data
• Part 7: Submitting Data
• Part 8: Executing Operations
• Part 9: Authenticating with OAuth
• Part 10: Conclusion

As part of a functioning integration, logging can serve many purposes. The most common is that it provides a mechanism for diagnosing and troubleshooting problems. However, logging can also be used to keep a historical record or audit trail, and to provide feedback to users on the integration’s state of execution. When it comes to adding logging to an integration developed in Java, there are a number of options. One is to use the java.util.logging class that is part of the Java API. Another is to use one of the many open source libraries that are available, and a popular and useful one is Apache’s Logging Services, namely the service called log4j. Adding log4j to your application code is fairly straightforward. First you need to add the log4j configurations to your properties file, then you instantiate the logger object in your code to do the logging. Based on the configurations that you are using for the logger, the logging output can be sent to the console window or a file on disk. Here’s an example of log4j settings in a properties file:

# Logger settings.
log4j.rootLogger=ALL, file, stdout

# Log file message settings.
log4j.appender.file=org.apache.log4j.FileAppender
log4j.appender.file.File=./logs/test.log
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{yyyy/MM/dd HH:mm:ss} %/5p %c{1}:%L / %m%n

# Log console message settings.
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{yyyy/MM/dd HH:mm:ss} %/5p %c{1}:%L / %m%n

There are a few things going on here. The first is setting the rootLogger, which controls which types of messages actually get logged, and it also specifies the appenders that are used to do the logging. The next two sections describe the appenders and how they are used. Of particular interest is the ConversionPattern property that controls the format of the messages that are logged. Once you have the logger setup within your properties file, using it in code is a matter of instantiating the logger at the class level like so:

static Logger logger = Logger.getLogger(YourClass.class);

Notice that you pass the name of your class to the getLogger method. Next you need to tell the logger where to find its configurations, which in this example is the properties contained in the properties file. You do that like this:

PropertyConfigurator.configure("config.properties");

Once you have that done, you simply call the logger when you have something that you want logged like this:

logger.info("Application started...");

The logger supports different types of log types such as TRACE, DEBUG, INFO, WARN, and ERROR, and it is up to you to decide which type to use and when. But what about integrations? Is there anything specific that you should think about logging? The answer is absolutely. Some example of the types of things that you may want to log include:

• Application initialization
• User authentication
• System state when the integration was launched
• API authorization success/failure
• API call information such as URLs and query parameters
• API call responses with status codes
• And of course, exceptions

Something that you’ll want to spend some time considering is how verbose you want your logging to be, and this is where the different log types can be useful. In the integrations that I have done, I’ll use the INFO type for general process logging, and try to keep them to a minimum. For the next level of logging, I’ll use the DEBUG type to help with basic troubleshooting. For integrations where I will not be able to debug directly on a system, I’ll use the TRACE type to provide a high level of verbosity that customers can turn on, then send me the log file. In the next article, I’ll talk about another basic building block of integrations, and that is data parsing. Data parsing is used when processing the response returned when making call to the VersionOne API, the format of which can be XML or JSON. As always, stay agile my friend…