First Failure Data Capture for your enterprise application with WebSphere Application Server

WebSphere Serviceability Development, SWG

© 2009 IBM Corporation

First Failure Data Capture Getting Started Guide

Authors:

Michael Casile

Stefan Derdak


© 2009 IBM Corporation2

Agenda

What is FFDC

Key Concepts

Usage Sample

Flow Example (resulting from the usage)

Advanced usage samples

Advanced Topics

Summary



What is FFDC First Failure Data Capture (FFDC) is used to capture

diagnostic data when a problem occurs in code.

Different from logging

– Called only when exceptions have occurred

– More snapshot/dump than a history

– Executes only once (so performance less of an issue)

– Includes functionality and extensibility to capture more data and renders more information

– Goal is to capture enough context information when a problem occurs, that there is no need to reCreate the problem

Highly extensible in OSGi and J2SE

Exists as a jar/bundle with no dependencies (JDK)

Tracks summary information on all incidents



Key Concepts

Simple to use (Ffdc.log)

Unique incident “file” created for first execution of any Ffdc.log

isLoggable ffdc guard

Data Collectors – dynamic event listener based on stack frames

Formatters – Part of special rendering framework for objects

IncidentForwarder – Listener called at completion of any incident creation

Provider – Custom FFDC implementation (dynamically pluggable)

Summary Report/Table – View of info on incidents that have occurred



Usage Sample

try {

// Application code here

} catch (Exception e) {

Ffdc.log(e, myClass, myClassNm+myMethodNm, “lineNumber”, cde1, cde2, …) ;

}

Args: Exception, reporting class, “sourceId”, “probeId”, context data elements

where sourceId and probeId are any strings, but this pattern is common



Flow Example (how is that call handled)

1. Determines if this incident has already occurred (stops if it has)

2. Checks for registered Data Collectors (does any registered DC want to be called on anything in stack). DC’s capture additional captured data elements (CDEs)

3. Creates incident stream and writes header/exception

4. Render each CDE from call or from Data collectors

1. Looks to format each cde with registered formatter, or formattable, or reflection.

2. @FFDC_OMIT to skip certain discovered cdes.

5. Renders the incident to the output location (file/dir)

6. Updates the summary

7. Notifies registered incidentForwarders



Flow Example (Diagram)

Client Code

Log API call

RegisteredDataCollectors

RegisteredFormatters

RegisteredIncident

Forwarders

FFDCInfrastructure

Incident

IncidentStream

SummaryTable

SummaryReport

1

7

4b

4a

2a

32b

5 6



Advanced Usage Topics (Simple, with isLoggable sample)package howto_ffdc._1_simple;

import static com.ibm.ffdc.Manager.Ffdc;

// import com.ibm.ffdc.Ffdc; // Used if alternate call is done below

public class SimpleTest extends TestCase {

protected void setUp() throws Exception {

System.setProperty("com.ibm.ffdc.log", “/opt/IBM/WebSphere/logs/ffdc/");

}

public void testWithoutFormatter(){

try {

// ... do work


Ffdc.log(e, this, getClass().getName(),"24", customer);

/*alternate if generating the parms for the call can be expensive

* Ffdc ffdc = Ffdc.getFfdc(e, this, getClass().getName(),"24") ;

* if (ffdc.isLoggable())

* MyData myData = expensiveCallToGetData() ;

* ffdc.log(customer, myData) ;

*/

}

}

}



Advanced Usage Topics (Formatter part 1)import com.ibm.ffdc.config.FfdcConfigurator;

import com.ibm.ffdc.Ffdc;


/**

* This example shows how to register a formatter at program startup, and illustrates the usage.

*/

public class FormatterTest extends TestCase {

protected void setUp() throws Exception {

System.setProperty("com.ibm.ffdc.log", "System.err");

/* Construct and register the formatter. */

CustomerFormatter customerFormatter = new CustomerFormatter();

FfdcConfigurator.register(customerFormatter);

}

public void testFormatter(){

Customer customer = null;

try {

// ... do work

customer = new Customer(1001, "Jane", "Dow");


Ffdc ffdc = Ffdc.getFfdc(e, this,"24");

if (ffdc.isLoggable()) {

String ctx = "expensive to retrieve context data";

ffdc.log(customer, ctx);

}

}

}

}



Advanced Usage Topics (Formatter part 2)import com.ibm.ffdc.config.Formatter;

import com.ibm.ffdc.config.IncidentStream;

public class CustomerFormatter implements Formatter {

public void formatTo(Object objectToFormat, IncidentStream is) throws IllegalArgumentException {

formatTo((Customer)objectToFormat, is);

}

public void formatTo(Customer customer, IncidentStream is) throws IllegalArgumentException {

is.write("id", customer.id);

is.write("name", customer.name);

is.write("surname", customer.surname);

}

public String[] getSupportedTypeNames() {

return new String[] {Customer.class.getName()};

}

public boolean isSupported(Class<?> clazz) {

return Customer.class.equals(clazz);

}

}



Advanced Usage Topics (DataCollector part 1)import com.ibm.ffdc.config.FfdcConfigurator;


public class DataCollectorTest extends TestCase {

public void setUp() throws Exception {

System.setProperty("com.ibm.ffdc.log", "System.err");

FfdcConfigurator.register(new DataCollectorSimple());

}

public void testDataCollector() {

ExposedGlobals exposedGlobals = new ExposedGlobals() ;

try {

throw new Exception("Yes, had ExposedGlobals, but getting them thru DataCollector for this example”) ;


Ffdc.log(e, this, DataCollectorTest.class.getName()+"testDC", "01") ;

}

}

}



Advanced Usage Topics (DataCollector part 2)import com.ibm.ffdc.config.DataCollector;

import java.util.Collection;

import java.util.Collections;

import java.util.Properties;

class DataCollectorSimple implements DataCollector {

// Return collection of CDEs

public Collection<? extends Object> collect(Throwable ex) {

Properties propsToGather = ExposedGlobals.getInstance().getProps() ;

return Collections.singleton(propsToGather) ;

}

public String[] getSupportedTypeNames() { // What to look for in stackFrames

return new String[]{

DataCollectorTest.class.getName() + "#testDataCollector"

};

}

}



Advanced Topics: Formatter details Formatting techniques and priority

– Formatter – if a registered formatter is found for a class, it is used

– Formattable – If a class is formattable• If the formatTo method is in this class, it is used• If it is in a parent class, it is used, then the remainder of this

class is rendered via reflection

– Reflection – anything w/out a formatter or formattable is rendered with reflection. In reflection, objects annotated with @FFDC_OMIT are not rendered

Recursive dispatch

– As each object is rendered, it’s children are rendered (to 3 levels)

– When the child is rendered, the formatting technique is applied to the child. Ie: a reflected object may include a Formattable object or an object for which a Formatter has been registered



Advanced topics: OSGi registrationBest practice for registering FFDC extensions (formatters, data collectors, providers, incident forwarders) in OSGi is to use declarative services. Here is an example:

Add to the MANIFEST.MF the line:

Service-Component: OSGI-INF/CustomerFormatter.xml

and add the OSGI-INF/CustomerFormatter.xml file with the content:

<?xml version="1.0"?>

<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="CustomerFormatter">

<implementation class="howto_ffdc.domain.ffdcsupport.CustomerFormatter"/>

<service>

<provide interface="com.ibm.ffdc.config.Formatter"/>

</service>

</scr:component>



Programmatic registration in OSGiA simple way is to register an OSGi service via your bundles Activator as this sample demonstrates:

public void start(BundleContext context) throws Exception {

Formatter formatter = new CustomerFormatter();

context.registerService(Formatter.class.getName(),

formatter, new Hashtable());

System.out.println("Exported service:"+formatter.getClass().getName());

}



Advanced topics: Incident reset Dynamic extensibility is a key them of FFDC but …

– What good is dynamically adding a new dataCollector (formatter, forwarder, …) if the incident already occurred

– FFDC also provides access to the Summary table• List<Incident> incidentList = Ffdc.getIncidents();• boolean unblocked = Ffdc.unblockLogging(myIncident);

• Ffdc.unblockLogging() ;

– With these method calls, one incident or all incidents can be modified so that the next time this Ffdc.log statement executes, it will create another incident



Summary FFDC is a simple java facility to improve the serviceability of

you java software

– Low cost to implement

– Extensible, can grow w/you (Data Collectors, Formatters, Providers, and Incident Forwarders)

– Extensions do not impact core code (no change needed to Ffdc.log statements to affect improved information)

First Failure Data Capture for your enterprise application with WebSphere Application Server

Technology

Transcript of First Failure Data Capture for your enterprise application with WebSphere Application Server