Post on 14-Dec-2014
description
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation
First Failure Data Capture Getting Started Guide
Authors:
Michael Casile
Stefan Derdak
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation2
Agenda
What is FFDC
Key Concepts
Usage Sample
Flow Example (resulting from the usage)
Advanced usage samples
Advanced Topics
Summary
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation3
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation4
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation5
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation6
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation7
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation8
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
} catch (Exception e) {
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) ;
*/
}
}
}
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation9
Advanced Usage Topics (Formatter part 1)import com.ibm.ffdc.config.FfdcConfigurator;
import com.ibm.ffdc.Ffdc;
import static com.ibm.ffdc.Manager.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");
} catch (Exception e) {
Ffdc ffdc = Ffdc.getFfdc(e, this,"24");
if (ffdc.isLoggable()) {
String ctx = "expensive to retrieve context data";
ffdc.log(customer, ctx);
}
}
}
}
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation10
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);
}
}
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation11
Advanced Usage Topics (DataCollector part 1)import com.ibm.ffdc.config.FfdcConfigurator;
import static com.ibm.ffdc.Manager.Ffdc;
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”) ;
} catch (Exception e) {
Ffdc.log(e, this, DataCollectorTest.class.getName()+"testDC", "01") ;
}
}
}
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation12
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"
};
}
}
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation13
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation14
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>
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation15
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());
}
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation16
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
WebSphere Serviceability Development, SWG
© 2009 IBM Corporation17
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)