Instana

Log message tracing in Instana

Instana automatically collects error and warning messages for the supported runtime, such as Java, Node.js etc. When you need to diagnose the application failure, this is quite useful to understand what is happening in real time. But this log trace capability is provided only for well-known log libraries, such java.util.Logging and Log4J. For example, you can see the list of the supported log libraries for Java here.
Modern applications basically uses these well-known libraries and that's ok. But in real world, your client might still maintain some legacy Enterprise application, and it might use custom-built log libraries or legacy application framework log libraries which are not supported in Instana.
In this blog, I guide you how to collect messages from such custom log libraries in Java, without changing the application itself.

Configuration based tracing SDK

Instana provides the custom tracing SDK to adopt libraries which Instana itself does not support. This is useful to capture activities in custom frameworks or niche but important libraries in your application.
What is good for this tracing SDK is that you can trace activities by just declaring the class and methods to capture in the configuration.yaml. You don't need to include Instana library into your application nor to ask for the developers to implement some Instana specific code into your application.
This SDK is provided for Java and .NET, you can read details here.

Settings in the configuration.yaml

In this blog, we trace the log messages from WACs framework. WACs (Web Application Components) framework is an IBM Consulting asset web framework widely adopted in major IBM Japan clients and still used in mission critical applications in Japan.
WACs Log Framework provides several log methods but in this example we trace the messages from the 2 methods.
com.ibm.jp.wacs.log.WACsLogHandler.warn(String arg0, String arg1, String arg2)
com.ibm.jp.wacs.log.WACsLogHandler.error(String arg0, String arg1, String arg2)

Log message ID is provided as arg1, and Log message itself as arg2 like bellow.

loghandler.info(methodname, "MSG001I", "method invoked")
loghandler.warn(methodname, "MSG002W", "method invoked - warning") 
loghandler.error(methodname, "MSG003E", "method invoked - error")

To capture the message from warn() and error() methods, you need to add bellow snippets into your configuraiton.yaml of Instana.

As "match" parameter, you need to specify class and method to capture.
As "span" parameter, type should be "EXIT" and add two tag named "log.level" and "log.message".
Set "error" or "warn" for the value of "log.level" and specify the argument index of the method to be captured as "log.message". For "log.message", luckily you can choose which argument to be collected. If your client is nervous to collect log message itself because it might have PII(Personally Identifiable Information), you may send only message ID by choosing right argument.

Custom log tracing result

After you set this tracing setting in your Instana agent , the log messages are collected automatically similar to other log libraries.
The messages are displayed in the "Log Message" tab of the application dashboard. 

You can find messages in "Unbounded Analytics" like bellow. 

If you choose one call, the warning and error messages are displayed in the call analytics page.

By using this capability, Instana can collect log messages for the custom log libraries in Java.
This will be quite helpful for diagnosing your enterprise applications and to identify the root cause of its failure.
I hope this guide help your application monitoring.