Configuring and Capturing Diagnostic Images

6 Configuring and Capturing Diagnostic Images

You can 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. The captured information is useful for analyzing the cause of a server failure.If WebLogic Server is configured with Oracle HotSpot, and Java Flight Recorder is enabled, the diagnostic image capture includes WebLogic Server diagnostic data that can be viewed in Java Mission Control.

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.
Content of the Captured Image File
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.

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.

In the config.xml file, the image capture is described under the <server-diagnostic-config> subelement of the <server> element for the server, as shown in Example 6-1:

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

Note:

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

Parent topic: Configuring and Capturing Diagnostic Images

Content of the Captured Image File

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.

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

If WebLogic Server is configured with Oracle HotSpot, and Java Flight Recorder is enabled, the diagnostic image capture includes a Java Flight Recorder image, FlightRecording.jfr, that can be viewed in Java Mission Control. The contents of the Java Flight Recorder image contains all available data from the Java Flight Recorder, and the volume of data produced by WLDF depends on the diagnostics volume setting. When Java Flight Recorder is enabled, data is always provided by the JVM, 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 Java Flight Recorder image as well.

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 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.
If a non-WebLogic event producer in the WebLogic Server environment, such as DMS, has configured Java Flight Recorder to record data, the WLDF diagnostic image capture includes a Java Flight Recorder image file with the recorded data even if the WLDF diagnostics volume is set to Off.
When WebLogic Server is configured with HotSpot, Java Flight Recorder is not enabled by default. For information about how to enable it, see Using Java Flight Recorder with Oracle HotSpot.

Parent topic: Configuring and Capturing Diagnostic Images

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_NAME\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
WebLogic Server version including patch and build number information

If WLDF is configured with Oracle HotSpot, as described in Configuring Diagnostic Image Capture for Java Flight Recorder, the image also contains the Java Flight Recorder file, FlightRecording.jfr. The JFR file can be extracted as described in WLST Online Commands for Downloading Diagnostics Image Captures, and viewed in Java Mission Control.

Figure 6-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 6-1 Contents of an Image File

Description of "Figure 6-1 Contents of an Image File"

Parent topic: Content of the Captured 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:

Table 6-1 WLST Commands for Downloading Image Captures

Command	Summary
`captureAndSaveDiagnosticImage`	Captures a diagnostic image and downloads it locally.
`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 Java Flight Recorder diagnostics data for viewing in Java Mission Control.

For information about these commands, and examples of using them, see Diagnostics Commands in WLST Command Reference for Oracle WebLogic Server. For examples of WLST scripts that return a list of diagnostic images and retrieve JFR files in them, see WebLogic Scripting Tool Examples.

Parent topic: Content of the Captured Image File