Configuring and Using the WebLogic Diagnostic Framework

Configuring and Capturing Diagnostic Images

The Diagnostic Image Capture component of the WebLogic Diagnostic Framework (WLDF) can be used to create a diagnostic snapshot, or dump, of a server's internal runtime state at the time of the capture. This information can be particularly useful for support personnel analyzing what might have contributed to a server failure.

The following topics tell how to configure and use the Diagnostic Image Capture component:

How to Initiate Image Captures

A diagnostic image capture can be initiated by:

A "first failure" detection. See About First Failure Detection and Notification.
A configured watch notification. See Configuring Notifications.
A request initiated by a user in the Administration Console (and, potentially, requests initiated from third-party diagnostic tools). See Configure and capture diagnostic images in the Administration Console Online Help.
A direct API call, using JMX.
WLST command

About First Failure Detection and Notification

The Diagnostic Image Capture component includes a first failure notification feature. When a server makes the transition into a failed state, this feature automatically triggers an image creation notification. That notification triggers the creation and capture of a diagnostic image. The first-failure notification feature ensures that the state of a server when it failed is preserved.

You can configure an image lockout period for first failure notifications. The image lockout time limits the number of diagnostic images that are captured in a specified time period. When a server fails and recovers multiple times in a short period of time—such as may happen due to storm-related power failures—the image-lockout period prevents the server from repeatedly capturing and persisting diagnostic images that are very similar in content and that unnecessarily use up system resources, such as disk space.

Configuring Diagnostic Image Captures

Because the diagnostic image capture is meant primarily as a post-failure analysis tool, there is little control over what information is captured. Available configuration options are:

The default destination for the image
For a specific capture, a destination that is different from the default destination
A lockout, or timeout, period, to control how often an image is taken during a sequence of server failures and recoveries

Diagnostic Image Capture is configured in the config.xml file for a domain, under the <server> element for the server, as shown in Listing 3-1:

Listing 3-1 Sample Diagnostic Image Capture Configuration

<domain>
  <!-- Other domain configuration elements -->
  <server>
    <name>myserver</name>
    <server-diagnostic-config>
      <image-dir>logs\diagnostic_images</image-dir>
      <image-timeout>2</image-timeout>
    </server-diagnostic-config>
    <!-- Other configuration details for this server -->
  </server>
  <!-- Other server configurations in this domain-->
</domain>

What Information Is Captured

The most common sources of a server state are captured in a diagnostic image capture, including:

Configuration
Log cache state
Java Virtual Machine (JVM)
Work manager state
JNDI state
Harvestable data.

The Diagnostic Image Capture component captures and combines the images produced by the different server subsystems into a single server image file. In addition to capturing the most common sources of server state, this component captures images from all the server subsystems including, for example, images produced by the JMS, JDBC, EJB, and JNDI subsystems.

Note: A diagnostic image is a heavyweight artifact meant to serve as a server-level state dump for the purpose of diagnosing significant failures. It provides the capability to capture a significant amount of important data in a structured format and then to provide that data to support personnel for analysis.

About the Captured Image File

An image is captured as a single file for the entire server. Each image has a unique name, as follows:

    diagnostic_image_domain_server_yyyy_MM_dd_HH_mm_ss

The contents of the file include at least the following information:

Creation date and time of the image
Source of the capture request
Name of each image source included in the image and the time spent processing each of those image sources
JVM and OS information, if available
Command line arguments, if available
WLS version including patch and build number information