Get diagnostics output from a custom filter

Note   Some code extracts in this section are from the jabber sample that is no longer included in the code samples supplied with API Gateway.

You can configure API Gateway to output detailed diagnostic information for a specific custom filter by setting the trace level to DEBUG or DATA. To change the trace level in Policy Studio, select the Environment Configuration > Server Settings node, and click General. Select DEBUG or DATA from the Tracing level field, and click Apply Changes. For more information on tracing and logging see the API Gateway Policy Developer Guide.

When running a trace at DEBUG level, API Gateway outputs the status of every policy and filter that it processes into the trace file. The trace output for a specific filter takes the following format:

Filter name {
    Trace for the filter is indented 
    to the following point to make it clear
    to identify output from the filter
} status, in x milliseconds

The status is 0, 1, or 2, depending on whether the filter failed, succeeded, or aborted.

Add custom trace output to custom code

To add custom trace information to custom code, you can add Trace statements within your code.

For example, the following code adds Trace statements to output the thread ID associated with the chat, which corresponds to the thread field of the SMACK XMPP message, to a custom Jabber filter (see Write a custom filter using the extension kit).

…
import com.vordel.trace.Trace;
…

public class JabberProcessor extends MessageProcessor {
    …    
    public boolean invoke(Circuit c, Message message)	
      throws CircuitAbortException {         	 
        …
        try {        
            Trace.debug("Chat Thread ID is " + chat.getThreadID());
            chat.sendMessage(messageStr.substitute(message));            
        } catch (org.jivesoftware.smack.XMPPException ex) {
            Trace.error("Error Delivering block");    
    	 }         
        …          
    }
    …
}
Note   Code has been omitted for clarity.

The Chat Thread ID is output in the API Gateway trace file as follows:

DEBUG   10/Jun/2013:11:18:21.365 [01f4] run filter [Jabber] {
DEBUG   10/Jun/2013:11:18:22.880 [01f4] 	Chat Thread ID is VSx1B0
DEBUG   10/Jun/2013:11:18:23.037 [01f4] } = 1, filter [Jabber]
DEBUG   10/Jun/2013:11:18:23.037 [01f4] Filter [Jabber] completes in 672 milliseconds.

The trace level DATA can be used to provide more detailed information. To use the DATA level in the preceding example, change the Trace.debug statements to Trace.data statements.

Add custom log4j output to custom code

To output custom log4j information, perform the following steps:

  1. Update the log4j.properties file. To specify that the log4j appender sends output to the API Gateway trace file, make the following changes to your log4j.properties file. This is located in the INSTALL_DIR/apigateway/system/lib directory. For example:
  2. log4j.rootLogger=DEBUG, A1, Vordel
    log4j.appender.Vordel=com.vordel.trace.VordelTraceAppender
    
  3. Add log4j statements to your code. Log4j is already on the API Gateway CLASSPATH. The following example shows the preceding code with log4j statements instead of Trace statements:
  4. …
    import org.apache.log4j.Logger;
    …
    public class JabberProcessor extends MessageProcessor {
        static Logger log = Logger.getLogger(JabberProcessor.class.getName());  
        …    
        public boolean invoke(Circuit c, Message message)	
          throws CircuitAbortException {         	 
            …
            try {        
                log.debug("Chat Thread ID is " + chat.getThreadID());
                chat.sendMessage(messageStr.substitute(message));            
            } catch (org.jivesoftware.smack.XMPPException ex) {
                Trace.error("Error Delivering block");    
        	 }          
            …          
        }
        …
    }
    

The following is output in the API Gateway trace file:

<Date> <Time> [Thread-xx] DEBUG com.vordel.jabber.filter.JabberProcessor - Chat Thread ID is xxxxxx

Related Links