Configure tracing and logging for features in the Liberty profile

We can use the tracing and logging mechanism of the Liberty profile for Liberty features. The logging service is part of the Liberty kernel so we do not have to specify a feature in server.xml to use it.

The Liberty profile provides the following SPIs for integrating tracing and logging in the customized feature code:

com.ibm.websphere.ras

The com.ibm.websphere.ras package provides classes to log messages and trace records, as well as some extension points. In general,, feature code can use the java.util.logging package to log trace and messages, and to control the output through Liberty logging configuration, but the extended capability of the WebSphere package is sometimes useful and the trace guards are slightly more efficient when trace is disabled.

com.ibm.websphere.ras.annotations

The com.ibm.websphere.ras.annotations package provides annotations for use with classes in the other packages. For example, an @Sensitive annotation can be used to prevent the contents of the annotated variable from appearing in trace or message output.

com.ibm.ws.ffdc

The com.ibm.ws.ffdc package provides facilities to write first failure data capture (FFDC) records to assist in debugging unexpected exceptions.

com.ibm.wsspi.logging

The com.ibm.wsspi.logging package provides interception points of log and ffdc records.

The Java API documentation for each Liberty profile SPI is detailed in the Programming Interfaces (APIs) section of the information center, and is also available as a separate .zip file in one of the javadoc subdirectories of the ${wlp.install.dir}/dev directory.

The following steps show you how to configure an example Liberty feature, called myfeature, to use the tracing and logging mechanism of the Liberty profile:

1. Specify the location of the message file for the feature myfeature, and the name of the group that is required by the com.ibm.websphere.ras.TraceComponent class.

   import java.util.ResourceBundle;
   
   public class myFeatureConstants {
   
       public static final String TR_RESOURCE_BUNDLE = 
           "com.mycompany.myFeature.internal.resources.FeatureMessages";
   
       public static final String TR_GROUP = "myFeature";
   
       public static final ResourceBundle messages = ResourceBundle.getBundle(TR_RESOURCE_BUNDLE);
   
   }

2. In the implementation class of the feature service code, call the register() method of the com.ibm.websphere.ras.TraceComponent class to register the implementation class with the trace manager provided by the Liberty profile. Then, we can configure the trace manger to track the DS methods of the feature.

   ...
   import com.ibm.websphere.ras.Tr;
   import com.ibm.websphere.ras.TraceComponent;
   
   
   public class myFeatureServiceImpl {
   
       private static final TraceComponent tc = Tr.register(myFeatureServiceImpl.class);
   
   
       protected void activate(ComponentContext cc, Map<String, Object> newProps) {
           if (tc.isDebugEnabled()) {
               Tr.debug(tc, "myFeatureComponentImpl activated"); }
   ...

3. Use the TraceOptions annotation to specify the trace group name and the message bundle name.

   @TraceOptions(traceGroup = myFeatureConstants.TR_GROUP, messageBundle = 
       myFeatureConstants.TR_RESOURCE_BUNDLE)
   package com.mycompany.myFeature;
   
   import com.ibm.websphere.ras.annotation.TraceOptions;
   import com.mycompany.myfeature.internal.myFeatureConstants;
   ...

Subtopics

• Generating first failure data capture (FFDC) records
  FFDC records include the exception stack and optional additional data that is recorded when an unexpected exception is caught by your code. Methods on the com.ibm.ws.ffdc.FFDCFilter class are used to generate these records, and there are a number of methods that might cause a variety of data to be captured.

Parent topic: Liberty SPI utilities