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. See Using Java Flight Recorder with Oracle HotSpot.

How to Initiate Image Captures

The Diagnostic Image Capture component gathers the most common sources of key server state used in diagnosing problems, and packages that state into a single file or diagnostic image. You can initiate the image capture of a server using the WebLogic Administration Console or WLST command.

A diagnostic image capture can be initiated by:

  • A configured policy. See Configuring Actions.

  • A request initiated by a user in the WebLogic Server Administration Console (and requests initiated from third-party diagnostic tools). See Configure and capture diagnostic images in the Oracle WebLogic Server Administration Console Online Help.

  • A direct API call, using JMX. See Example 6-1.

  • WLST command

Configuring Diagnostic Image Captures

When you initiate the capture of diagnostic image, you can configure the capture details such as the destination location of the image capture, WLDF diagnostic volume, and how often an image must be captured during failures.

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 failures and recoveries.

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

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

The following example shows a simple policy expression that returns true when the value of HeapFreePercent attribute of JVMRuntimeMBean is less than 20:

wls.runtime.serverRuntime.JVMRuntime.heapFreePercent < 20

See Configuring Scheduled Policies and Configuring Image Actions. Also, see Configure Policies and Actions in the Oracle WebLogic Server Administration Console Online Help.

Configuring WLDF Diagnostic Volume

If WebLogic Server is configured with Oracle HotSpot, and the Java Flight Recorder is enabled, the Java 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 Java Mission Control. If Java Flight Recorder is not enabled, or if WebLogic Server is configured with a different JVM, the Java Flight Recorder data is not captured in the diagnostics image capture.

Note:

When WebLogic Server is configured with HotSpot, by default Java Flight Recorder is disabled. For information about how to enable it, see Using Java Flight Recorder with Oracle HotSpot.

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

Volume Setting Description

Off

Disables the collection of data in the Java Flight Recorder diagnostic image.

Low

Enabled by default. For information about data that is collected, see Low Volume Setting.

Medium

Captures a moderate amount of data. See Medium Volume Setting.

High

Captures in-depth data. See High Volume Setting.

Note:

The specific set of events for which diagnostic data is collected using the diagnostic volume settings is subject to change in future releases of WebLogic Server.

For information about how to set the diagnostic volume, see Configure WLDF diagnostics volume in the Oracle WebLogic Server Administration Console Online Help. For an example using WLST, see Example: Setting the WLDF Diagnostic Volume.

Low Volume Setting

The Low diagnostic volume setting is enabled by default. With this setting, basic information is generated and captured, and log messages with the "emergency", "alert", or "critical" levels are recorded.

In the current release of WebLogic Server, the following events are captured at the Low setting:

ThrottleInformation
WLDF Logging Snapshot
WLDF LogRecord Snapshot
WLDF WLLogRecord Snapshot
Connector Activate Endpoint
Connector Deactivate Endpoint
Connector Inbound Transaction Rollback
Connector Outbound Connection Closed
Connector Outbound Connection Error
Connector Outbound Destroy Connection
Connector Outbound Register Resource
Connector Outbound Release Connection
Connector Outbound Reserve Connection
Connector Outbound Transaction Rollback
Connector Outbound Unregister Resource
Deployment Complete 
Deployment Do Cancel
Deployment Do Prepare
Deployment Operation
EJB Business Method Invoke
EJB Business Method Post Invoke
EJB Business Method Pre Invoke
JDBC Connection Rollback
JDBC Statement Execute
JDBC Statement Execute Begin
JDBC Transaction Rollback
Servlet Invocation
Servlet Request Run
Servlet Request Run Begin
Web Application Load
Web Application Unload
Webservices JAXRPC Client Request
Webservices JAXRPC Client Response
Webservices JAXRPC Dispatch
Webservices JAXRPC Request
Webservices JAXRPC Response
Webservices JAXWS Endpoint
Webservices JAXWS Request
Webservices JAXWS Resource
Medium Volume Setting

With the Medium diagnostic volume setting, additional information is captured, and messages with the "error" level and above are recorded. For example, User IDs are captured by the Medium and High volume settings (capturing them imposes a performance overhead not appropriate for the Low setting).

In the current release of WebLogic Server, the following events are captured at the Medium setting, in addition to those captured at the Low setting:

Connector Inbound Transaction Commit
Connector Inbound Transaction Start
Connector Outbound Transaction Commit
Connector Outbound Transaction Start
EJB Home Create
EJB Home Remove
EJB PoolManager Create
EJB Pool Manager Post Invoke
EJB Pool Manager Pre Invoke
JDBC Connection Close
JDBC Connection Commit
JDBC Connection Create Statement
JDBC Connection Get Vendor Connection
JDBC Connection Prepare
JDBC Connection Release
JDBC Connection Reserve
JDBC Data Source Get Connection
JDBC Driver Connect
JDBC Statement Creation
Servlet Execute
Servlet Request Dispatch
Servlet Request
Servlet Filter
Servlet Async Action
Servlet Context Execute
Servlet Response Write Headers
Servlet Response Send
Servlet Stale Resource
Servlet Check Access
JMS BE Consumer Log
High Volume Setting

With the High diagnostic volume setting, in-depth information is captured, and messages with the "error" level and above are recorded. Stack traces are also captured with the High setting, but only for events for which a stack trace add value (for example, stack traces where application code would normally be visible are generated, but stack traces that only show internal code and that do not vary at all are not generated).

In the current release of WebLogic Server, the following events are captured at the High setting in addition to those captured at the Medium setting:

EJB Database Access
EJB Business Method Post Invoke Cleanup
EJB Pool Manager Remove
EJB Replicated Session Manager
EJB Timer Manager
JDBC Transaction Commit
JDBC Transaction End
JDBC Transaction Get XA Resource
JDBC Transaction Is Same RM
JDBC Transaction Prepare
JDBC Transaction Start
JTA Transaction Commit
JTA Transaction End
JTA Transaction Prepared
JTA Transaction Prepare
JTA Transaction Start
Servlet Request Overload
Servlet Request Cancel
Servlet Context Handle Throwable

WLST Commands for Generating an Image Capture

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

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

url='t3://localhost:7001'
username='system'
password='password'
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.

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

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

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. See Analyzing Java Flight Recorder Data.

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 follows
Description of "Figure 6-1 Contents of 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:

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