This chapter describes the Diagnostic Image Capture component of the WebLogic Diagnostics Framework (WLDF) for WebLogic Server 12.1.3 that you can use to create a diagnostic snapshot, or dump, of a server's internal run-time 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 HotSpot, and Java Flight Recorder is enabled, the diagnostic image capture includes WebLogic Server diagnostic data that can be viewed in Java Mission Control. For information, see Using Java Flight Recorder with Oracle HotSpot.
This chapter includes the following sections:
A diagnostic image capture can be initiated by:
A configured watch notification. See Chapter 11, "Configuring Notifications."
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
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 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.
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 Online Help.
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. For details, see Medium Volume Setting. |
High |
Captures in-depth data. For details, 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.
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
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
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
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)
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 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 theconfig.xml
file directly.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 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.
Notes:
Note the following: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.
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. For more information, 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.
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 Appendix D, "WebLogic Scripting Tool Examples."