5 Configuring and Capturing Diagnostic Images

You use the Diagnostic Image Capture component of the WebLogic Diagnostics Framework (WLDF) to create a diagnostic snapshot, or dump, of a server's internal runtime state at the time of the capture. This information helps support personnel analyze the cause of a server failure.

If WebLogic Server is configured with Oracle JRockit, and JRockit Flight Recorder is enabled, the diagnostic image capture includes WebLogic Server diagnostic data that can be viewed in JRockit Mission Control.

The following topics describe the Diagnostic Image Capture component:

How to Initiate Image Captures

A diagnostic image capture can be initiated by:

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 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

  • WLDF diagnostics volume, which determines the volume of WebLogic Server event information that is captured in the Flight Recorder file.

As with other WLDF components, you can configure Diagnostic Image Capture using the Administration Console (see "Configure and capture diagnostic images" in the Oracle WebLogic Server Administration Console Help), the WebLogic Scripting Tool (WLST), or programmatically.

Note:

It is often useful to generate a diagnostic image capture when a server fails. To do so, set a watch rule to evaluate to true when the server's state changes to FAILED; then associate an image notification with the watch.

The watch rule is as follows:

(${[weblogic.management.runtime.ServerRuntimeMBean]//State} = 'FAILED')

For more information, see Configuring Harvester Watches and Configuring Image Notifications. Also see "Configure Watches and Notifications" in the Oracle WebLogic Server Administration Console Help.

Configuring WLDF Diagnostic Volume

If WebLogic Server is configured with Oracle JRockit, and the JRockit Flight Recorder is enabled, JRockit Flight Recorder data is automatically also captured in the diagnostic image capture. This data can be extracted from the diagnostic image capture and viewed in JRockit Mission Control. If JRockit Flight Recorder is not enabled, or if WebLogic Server is configured with a different JVM, the Flight Recorder data is not captured in the diagnostics image capture.

The volume of Flight Recorder data that is captured can be configured from the WebLogic Server Administration Console, which allows you to specify the following settings:

  • Off — No data is captured in the Flight Recorder diagnostic image.

    Note:

    The default setting for the WLDF diagnostic volume is Off; however, that could change in a future release of WebLogic Server. For information about changes to default settings, see What's New in Oracle WebLogic Server.

  • Low — Basic information is captured when messages with the "emergency", "alert", or "critical" levels are recorded.

  • Medium — Additional information is captured when messages with the "error" level and above are recorded.

  • High — In-depth information is captured when messages with the "error" level and above are recorded.

For information about how to set the volume of data that is captured, see "Configure WLDF diagnostics volume" in the Oracle WebLogic Server Administration Console Help.

WLST Commands for Generating an Image Capture

Example 5-1 shows an example of WLST commands for generating an image capture.

Example 5-1 Sample WLST Commands for Generating a Diagnostic Image

url='t3://localhost:7001'
username='system'
password='gumby1234'
server='myserver'
timeout=120
connect(username, password, url)
serverRuntime()
cd('WLDFRuntime/WLDFRuntime/WLDFImageRuntime/Image')
argTypes = jarray.array(['java.lang.Integer'],java.lang.String)
argValues = jarray.array([timeout],java.lang.Object)
invoke('captureImage', argValues, argTypes)

How Diagnostic Image Capture Is Persisted in the Server's Configuration

The configuration for Diagnostic Image Capture is persisted in the config.xml file for a domain, under the <server-diagnostic-config> sub-element of the <server> element for the server, as shown in Example 5-2:

Example 5-2 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>

Note:

Oracle recommends that you do not edit the config.xml file directly.

Content of the Captured Image File

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

  • Most recent harvested data

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

If WebLogic Server is configured with Oracle JRockit, and JRockit Flight Recorder is enabled, the diagnostic image capture includes a JRockit Flight Recorder image, JRockitFlightRecorder.jfr, that can be viewed in JRockit Mission Control. The contents of the JRockit Flight Recorder image contains all available data from the Flight Recorder, and the volume of data produced by WLDF depends on the diagnostics volume setting. When JRockit Flight Recorder is enabled, data is always provided by Oracle JRockit, and optionally includes data provided by WebLogic Server. Data from additional Oracle components, such as Oracle Dynamic Monitoring System (DMS), may be included in the Flight Recorder image as well.

Notes:

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

  2. If a non-WebLogic event producer in the WebLogic Server environment, such as DMS, has configured JRockit Flight Recorder to record data, the WLDF diagnostic image capture includes a Flight Recorder image file with the recorded data even if the WLDF diagnostics volume is set to Off.

Data Included in the Diagnostics Image Capture File

Each image is captured as a single file for the entire server. The default location is SERVER\logs\diagnostic_images. Each image instance has a unique name, as follows:

    diagnostic_image_DOMAIN_SERVER_YYYY_MM_DD_HH_MM_SS.zip

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

If WLDF is configured with Oracle JRockit as described in Configuring Diagnostic Image Capture for JRockit Flight Recorder, the image also contains the JRockit Flight Recorder (JFR) file, JRockitFlightRecorder.jfr. The JFR file can be extracted as described in WLST Online Commands for Downloading Diagnostics Image Captures, and viewed in JRockit Mission Control. For more information, see Oracle JRockit Flight Recorder Run Time Guide.

Figure 5-1 shows the contents of an image file. You can open most of the files in this ZIP file with a text editor to examine the contents.

Figure 5-1 An Image File

Description of Figure 5-1 follows
Description of "Figure 5-1 An Image File"

WLST Online Commands for Downloading Diagnostics Image Captures

WLST online provides the following commands for downloading diagnostic image captures from the server to which WLST is connected:

  • getAvailableCapturedImages — Returns a list of diagnostic images that have been created in the image destination directory configured on the server.

  • saveDiagnosticImageCaptureFile — Downloads a specified diagnostic image capture file.

  • saveDiagnosticImageCaptureEntryFile — Downloads a specific entry within a diagnostic image capture. This command is particularly useful for obtaining the Flight Recorder diagnostics data for viewing in JRockit Mission Control.

For information about these commands, and examples of using them, see WebLogic Scripting Tool Command Reference. For examples of WLST scripts that return a list of diagnostic images and retrieve JFR files in them, see Appendix D, "WebLogic Scripting Tool Examples."