This chapter describes the contents and audience for this guide—Configuring and Using the Diagnostics Framework for Oracle WebLogic Server. This guide describes the WebLogic Diagnostics Framework (WLDF), a monitoring and diagnostic framework that defines and implements a set of services that run within WebLogic Server processes and participate in the standard server life cycle. Using WLDF, you can create, collect, analyze, archive, and access diagnostic data generated by a running server and the applications deployed within its containers. This data provides insight into the runtime performance of servers and applications and enables you to isolate and diagnose faults when they occur.
This chapter includes the following sections:
The WebLogic Diagnostics Framework (WLDF) is a suite of services and APIs that provide the ability to collect and surface metrics that provide visibility into server and application performance. Independent Software Vendors (ISVs) can use these APIs, using standard interfaces such as WLST, REST, and JMX, to develop custom monitoring and diagnostic tools for integration with WLDF.
The suite of services, components, and APIs provided by WLDF for collecting and analyzing data includes the following:
Integration with Oracle HotSpot—If WebLogic Server is configured with Oracle HotSpot, WLDF can generate diagnostic information about WebLogic Server that is captured in the Java Flight Recorder file.
Built-in diagnostic system modules—A set of diagnostic modules available out-of-the-box that you can enable dynamically to capture basic performance data about the JVM, the WebLogic Server run time, and primary WebLogic Server subsystems, including JDBC data sources, messaging, and Java EE containers, such as servlets, EJBs, and resource adapters. The built-in diagnostic modules can also be cloned and modified, providing a simple way to create custom diagnostic system modules.
Monitoring Dashboard—Graphically presents the current and historical operating state of WebLogic Server and hosted applications, including information gathered by the built-in diagnostic system modules. The Monitoring Dashboard, which is accessed from the WebLogic Server Administration Console, provides a set of tools for organizing and displaying diagnostic data into views, which surface some of the more critical runtime WebLogic Server performance metrics and the change in those metrics over time.
Diagnostic Image Capture—Creates a diagnostic snapshot from the server that can be used for post-failure analysis. The diagnostic image capture includes Java Flight Recorder data, if it is available, that can be viewed in Java Mission Control.
Archive—Captures and persists data events, log records, and metrics from server instances and applications.
Instrumentation—Adds diagnostic code to WebLogic Server instances and the applications running on them to execute diagnostic actions at specified locations in the code. The Instrumentation component provides the means for associating a diagnostic context with requests so they can be tracked as they flow through the system. The WebLogic Server Administration Console includes a Request Performance page, which shows real-time and historical views of method performance information that has been captured through the WLDF instrumentation capabilities, serving as a tool that can help identify performance problems in applications.
Harvester—Captures metrics from runtime MBeans, including WebLogic Server MBeans and custom MBeans, which can be archived and later accessed for viewing historical data.
Policies and Actions—Provides the means for monitoring server and application states and sending notifications based on criteria set in the policies.
Logging services—Manage logs for monitoring server, subsystem, and application events. The WebLogic Server logging services are documented separately from the rest of the WebLogic Diagnostics Framework. See Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server.
This document describes and tells how to configure and use the monitoring and diagnostic services provided by WLDF.
WLDF provides features for monitoring and diagnosing problems in running WebLogic Server instances and clusters and in applications deployed to them. Therefore, the information in this document is directed both to system administrators and to application developers. It also contains information for third-party tool developers who want to build tools to support and extend WLDF.
It is assumed that readers are familiar with Web technologies and the operating system and platform where WebLogic Server is installed.
This document is organized as follows:
This chapter, "Introduction and Roadmap," provides an overview of WLDF components and describes the audience for this guide.
Chapter 2, "Overview of the WLDF Architecture," provides a high-level view of the WLDF architecture.
Chapter 3, "Using the Built-in Diagnostic System Modules," describes the built-in system diagnostic modules, which are provided by the WebLogic Diagnostics Framework (WLDF) as a simple and easy-to-use mechanism for performing basic health and performance monitoring of a WebLogic Server instance
Chapter 4, "Using WLDF with Java Flight Recorder," describes the WLDF integration features with Java Flight Recorder, describes basic usage scenarios, and provides a sample walkthrough of using Java Mission Control to examine WebLogic Server events captured in a Java Flight Recorder file.
Chapter 5, "Understanding WLDF Configuration," provides an overview of how WLDF features are configured for servers and applications.
Chapter 6, "Configuring and Capturing Diagnostic Images," describes how to configure and use the WLDF Diagnostic Image Capture component to capture a snapshot of significant server configuration settings and the server state.
Chapter 7, "Configuring Diagnostic Archives," describes how to configure and use the WLDF Diagnostic Archive component to persist diagnostic data to a file store or database.
Chapter 8, "Configuring the Harvester for Metric Collection," describes how to configure and use the WLDF Harvester component to harvest metrics from runtime MBeans, including WebLogic Server MBeans and custom MBeans.
Chapter 9, "Configuring Policies and Actions," provides an overview of WLDF policies and actions.
Chapter 10, "Configuring Policies," describes how to configure policies to monitor server instances and applications for specific conditions and fire actions when those conditions are met.
Chapter 11, "Configuring Actions," describes how to configure actions that can be executed by policies.
Chapter 12, "Configuring Instrumentation," describes how to add diagnostic instrumentation code to WebLogic Server classes and to the classes of applications running on the server.
Chapter 13, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts," describes how to use the DyeInjection monitor and how to use dye filtering with diagnostic monitors.
Chapter 14, "Accessing Diagnostic Data With the Data Accessor," tells how to use the WLDF Data Accessor component to retrieve diagnostic data.
Chapter 15, "Deploying WLDF Application Modules," explains how to configure and manage instrumentation for an application as a diagnostics application module.
Chapter 16, "Using the Monitoring Dashboard," explains how to graphically present the current and historical operating state of WebLogic Server and hosted applications using, in part, diagnostic data captured by WLDF.
Chapter 17, "Configuring and Using WLDF Programmatically," provides an overview of how you can use the JMX API and the WebLogic Scripting Tool (WLST) to configure and use WLDF components.
Chapter 18, "Using Debug Patches," describes how to apply debug patches dynamically, allowing you to capture diagnostic information using a patch that is activated and deactivated without requiring a server restart.
Appendix A, "Smart Rule Reference," contains a comprehensive reference of all smart rules provided in WLDF are used as policy predicates, typically for elastic scaling operations in dynamic clusters.
Appendix B, "WLDF Beans and Functions Reference," provides a reference for the beans provided by WLDF, and Java EL functions, that can be used in collected metrics policy expressions to obtain access to common WebLogic Server JMX data sources.
Appendix C, "WLDF Query Language," describes the WLDF query language (deprecated in WebLogic Server 12.2.1) that is used for constructing expressions to query diagnostic data using the Data Accessor, constructing policy expressions, and constructing policies for filtering logs.
Appendix D, "WLDF Instrumentation Library," describes the predefined diagnostic monitors and diagnostic actions that are included in the WLDF Instrumentation Library.
Appendix E, "Using Wildcards in Expressions," discusses how to use wildcards in WLDF expressions.
Appendix F, "WebLogic Scripting Tool Examples," provides examples of how to perform WLDF monitoring and diagnostic activities using the WebLogic Scripting Tool.
Appendix G, "WLDF Query Language-Based Policies," explains how to configure policies with expressions that use the deprecated WLDF query language.
"Glossary" is a glossary of terms used in WLDF.
Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server describes how to use WLDF logging services to monitor server, subsystem, and application events.
"Configure the WebLogic Diagnostic Framework" in the Oracle WebLogic Server Administration Console Online Help describes how to use the visual tools in the WebLogic Server Administration Console to configure WLDF.
"Monitoring Partitions" in Using WebLogic Server Multitenant describes how to monitor partitions in WebLogic Server Multitenant.
The WLDF system resource descriptor conforms to the
weblogic-diagnostics.xsd schema, available at
In addition to this document, we provide a variety of samples and tutorials that show WLDF configuration and use.
MedRec is an end-to-end sample Java EE application shipped with WebLogic Server that simulates an independent, centralized medical record management system. The MedRec application provides a framework for patients, doctors, and administrators to manage patient data using a variety of different clients.
MedRec demonstrates WebLogic Server and Java EE features, and highlights recommended best practices. MedRec is optionally installed in the WebLogic Server distribution and is available by selecting the Complete Installation type. By default, Medrec is configured post-installation in the
/user_projects/domains/medrec directory, where
ORACLE_HOME represents the Oracle home directory on your machine. For more information, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.
Additional WLDF samples for download can be found at
http://www.oracle.com/technetwork/indexes/samplecode/index.html. These examples are distributed as
.zip files that you can unzip into an existing WebLogic Server samples directory structure. These samples include Oracle-certified ones, as well as samples submitted by fellow developers.
WebLogic Server 12c (12.2.1) includes the following new and changed features for this document:
The terms watch and notification are replaced by policy and action, respectively. Consequently, the Watches and Notifications system has been renamed the Policies and Actions system. Although several new changes are introduced to this system, described in the following list item, the basic definition of these terms has not changed.
The Policies and Actions system has been revised to include the following new features:
The Java Expression Language (EL) is now supported as the recommended language to use in policy expressions. The WLDF query language is deprecated.
WLDFScheduleBean is now available for policies that are configured with the Harvester rule type and the Java EL expression language. These policies, called scheduled policies, use the
WLDFScheduleBean for scheduling all metric collection. Even though these policies are configured as Harvester rule types, they do not use the Harvester for metric collection or for scheduling.
A new library of prepackaged smart rules, beans, and functions, is provided for use in scheduled policy expressions. Smart rules greatly simplify the task of creating complex policy expressions by requiring you only to specify their input parameters.
For more complex policy expressions, WLDF also provides a library of beans and functions, which allow you to obtain access to common WebLogic Server JMX data sources.
These prepackaged smart rules, beans, and functions are helper tools for creating policies that can be used to support elasticity in dynamic clusters.
New action types are provided, including: the scale up and scale down actions to support elasticity in dynamic clusters; script action to run a WLST script; and enhancements to the email action that allow you to customize the message body.
For information about configuring elasticity in dynamic clusters, see Configuring Elasticity in Dynamic Clusters for Oracle WebLogic Server.
WLDF has been enhanced to support features in Oracle WebLogic Server Multitenant, such as monitoring partition scope metrics; configuring partition scope diagnostics system modules, debugging, and diagnostic image capture; and instrument partition scope applications. For information, see "Monitoring Partitions" in Using WebLogic Server Multitenant.
The following enhancements have been made to WLDF integration with Java Flight Recorder:
Improvements to execution context ID (ECID) tracing and correlation in servlet JFR events and SOAP JFR events
Support for relationship ID (RID) tracing, including within standalone WebLogic Server environments
Support for log level propagation in the diagnostic context within standalone WebLogic Server
For more information, see Chapter 4, "Using WLDF with Java Flight Recorder".
Support for dynamic debug patches. Dynamic debug patches allow you to capture diagnostic information using a patch that is activated and deactivated without requiring a server restart. For more information, see Chapter 18, "Using Debug Patches".