Contents

Title and Copyright Information

Preface

• Documentation Accessibility
• Conventions

1 Introduction and Roadmap

• What Is the WebLogic Diagnostics Framework?
• Document Scope and Audience
• Guide to This Document
• Related Documentation
• Samples and Tutorials
  • Avitek Medical Records Application (MedRec) and Tutorials
  • WLDF Samples Available for Download
• New and Changed Features in this Release

2 Overview of the WLDF Architecture

• Overview of the WebLogic Diagnostics Framework
• Data Creation, Collection, and Instrumentation
• Archive
• Watch and Notification
• Data Accessor
• Monitoring Dashboard and Request Performance Pages
  • Monitoring Dashboard
  • Diagnostics Request Performance Page
• Diagnostic Image Capture
• How It All Fits Together

3 Using WLDF with Oracle JRockit Flight Recorder

• About Oracle JRockit Flight Recorder
• Key Features of WLDF Integration with JRockit Flight Recorder
• JRockit Flight Recorder Use Cases
  • Diagnosing a Critical Failure — The "Black Box"
  • Profiling During Performance Testing or in Production
  • Real-time Application Diagnostics and Reporting (RADAR)
• Obtaining the JRockit Flight Recording File
• Analyzing Flight Recorder Data in JRockit Mission Control
  • JFR Graphical User Interface
  • Analyzing Execution Flow — A Sample Walkthrough
    • Displaying Event Data for a Product Subcomponent
    • Viewing the Event Log to Display Details
    • Tracking Execution Flow by Analyzing an Operative Set
    • Expanding the Operative Set and Viewing Correlated Diagnostic Data
  • Changing the Location of Temporary JFR Files

4 Understanding WLDF Configuration

• Configuration MBeans and XML
• Tools for Configuring WLDF
• How WLDF Configuration Is Partitioned
  • Server-Level Configuration
  • Application-Level Configuration
• Configuring Diagnostic Image Capture and Diagnostic Archives
• Configuring Diagnostic Image Capture for JRockit Flight Recorder
• Configuring Diagnostic System Modules
  • The Diagnostic System Module and Its Resource Descriptor
  • Referencing the Diagnostics System Module from Config.xml
  • The DIAG_MODULE.xml Resource Descriptor Configuration
  • Managing Diagnostic System Modules
  • More Information About Configuring Diagnostic System Resources
• Configuring Diagnostic Modules for Applications
• WLDF Configuration MBeans and Their Mappings to XML Elements

5 Configuring and Capturing Diagnostic Images

• How to Initiate Image Captures
• Configuring Diagnostic Image Captures
  • Configuring WLDF Diagnostic Volume
  • WLST Commands for Generating an Image Capture
• How Diagnostic Image Capture Is Persisted in the Server's Configuration
• Content of the Captured Image File
  • Data Included in the Diagnostics Image Capture File
  • WLST Online Commands for Downloading Diagnostics Image Captures

6 Configuring Diagnostic Archives

• Configuring the Archive
• Configuring a File-Based Store
• Configuring a JDBC-Based Store
  • Creating WLDF Tables in the Database
  • Configuring JDBC Resources for WLDF
• Retiring Data from the Archives
  • Configuring Data Retirement at the Server Level
  • Configuring Age-Based Data Retirement Policies for Diagnostic Archives
  • Sample Configuration

7 Configuring the Harvester for Metric Collection

• Harvesting, Harvestable Data, and Harvested Data
• Harvesting Data from the Different Harvestable Entities
• Configuring the Harvester
  • Configuring the Harvester Sampling Period
  • Configuring the Types of Data to Harvest
  • Specifying Type Names for WebLogic Server MBeans and Custom MBeans
  • Harvesting from the DomainRuntime MBeanServer
  • When Configuration Settings Are Validated
  • Sample Configurations for Different Harvestable Types

8 Configuring Watches and Notifications

• Watches and Notifications
• Overview of Watch and Notification Configuration
• Sample Watch and Notification Configuration

9 Configuring Watches

• Types of Watches
• Configuration Options Shared by All Types of Watches
• Configuring Harvester Watches
• Configuring Log Watches
• Configuring Instrumentation Watches
• Defining Watch Rule Expressions

10 Configuring Notifications

• Types of Notifications
• Configuring JMX Notifications
• Configuring JMS Notifications
• Configuring SNMP Notifications
• Configuring SMTP Notifications
• Configuring Image Notifications

11 Configuring Instrumentation

• Concepts and Terminology
  • Instrumentation Scope
  • Configuration and Deployment
  • Joinpoints, Pointcuts, and Diagnostic Locations
  • Diagnostic Monitor Types
  • Diagnostic Actions
• Instrumentation Configuration Files
• XML Elements Used for Instrumentation
  • <Instrumentation> XML Elements
  • <wldf-instrumentation-monitor> XML Elements
  • Mapping <wldf-instrumentation-monitor> XML Elements to Monitor Types
• Configuring Server-Scoped Instrumentation
• Configuring Application-Scoped Instrumentation
  • Comparing System-Scoped to Application-Scoped Instrumentation
  • Overview of the Steps Required to Instrument an Application
  • Creating a Descriptor File for a Delegating Monitor
  • Creating a Descriptor File for a Custom Monitor
    • Defining Pointcuts for Custom Monitors
    • Annotation-based Pointcuts
• Creating Request Performance Data

12 Configuring the DyeInjection Monitor to Manage Diagnostic Contexts

• Contents, Life Cycle, and Configuration of a Diagnostic Context
  • Context Life Cycle and the Context ID
  • Dyes, Dye Flags, and Dye Vectors
  • Where Diagnostic Context Is Configured
• Overview of the Process
• Configuring the Dye Vector via the DyeInjection Monitor
  • Dyes Supported by the DyeInjection Monitor
  • PROTOCOL Dye Flags
  • THROTTLE Dye Flag
  • When Diagnostic Contexts Are Created
• Configuring Delegating Monitors to Use Dye Filtering
• How Dye Masks Filter Requests to Pass to Monitors
  • Dye Filtering Example
• Using Throttling to Control the Volume of Instrumentation Events
  • Configuring the THROTTLE Dye
  • How Throttling is Handled by Delegating and Custom Monitors
• Using weblogic.diagnostics.context

13 Accessing Diagnostic Data With the Data Accessor

• Data Stores Accessed by the Data Accessor
• Accessing Diagnostic Data Online
  • Accessing Data Using the Administration Console
  • Accessing Data Programmatically Using Run-Time MBeans
  • Using WLST to Access Diagnostic Data Online
  • Using the WLDF Query Language with the Data Accessor
• Accessing Diagnostic Data Offline
• Accessing Diagnostic Data Programmatically
• Resetting the System Clock Can Affect How Data Is Archived and Retrieved

14 Deploying WLDF Application Modules

• Deploying a Diagnostic Module as an Application-Scoped Resource
• Using Deployment Plans to Dynamically Control Instrumentation Configuration
• Using a Deployment Plan: Overview
• Creating a Deployment Plan Using weblogic.PlanGenerator
• Sample Deployment Plan for Diagnostics
• Enabling Java HotSwap
• Deploying an Application with a Deployment Plan
• Updating an Application with a Modified Plan

15 Using the Monitoring Dashboard

• Running the Monitoring Dashboard
• Scope of the Diagnostic Information Displayed
• About the Monitoring Dashboard Interface
  • View List
  • Metric Browser
  • View Display Panel
• Understanding How Metrics Are Collected and Presented
  • About Metrics and Chart Types
    • Current Time Range Charts
    • Custom Time Range Charts
  • Sequence in which Metrics Data is Displayed
  • Notes about Metric Data Retention
• The Parts of a Chart

16 Configuring and Using WLDF Programmatically

• How WLDF Generates and Retrieves Data
• Mapping WLDF Components to Beans and Packages
• Programming Tools
  • Configuration and Run-Time APIs
    • Configuration APIs
    • Run-Time APIs
• WLDF Packages
• Programming WLDF: Examples
  • Example: DiagnosticContextExample.java
  • Example: HarvesterMonitor.java
    • Notification Listeners
    • HarvesterMonitor.java
  • Example: JMXAccessorExample.java

A WLDF Query Language

• Components of a Query Expression
• Supported Operators
• Operator Precedence
• Numeric Relational Operations Supported on String Column Types
• Supported Numeric Constants and String Literals
• About Variables in Expressions
• Creating Watch Rule Expressions
  • Creating Log Event Watch Rule Expressions
  • Creating Instrumentation Event Watch Rule Expressions
  • Creating Harvester Watch Rule Expressions
• Creating Data Accessor Queries
  • Data Store Logical Names
  • Data Store Column Names
• Creating Log Filter Expressions
• Building Complex Expressions

B WLDF Instrumentation Library

• Diagnostic Monitor Library
• Diagnostic Action Library
  • TraceAction
  • DisplayArgumentsAction
  • TraceElapsedTimeAction
  • TraceMemoryAllocationAction
  • StackDumpAction
  • ThreadDumpAction
  • MethodInvocationStatisticsAction
    • Instrumenting an Application with MethodInvocationStatisticsAction and Querying the Results
    • Configuring the Harvester to Collect MethodInvocationStatisticsAction Data
    • Configuring Watch Rules Based on MethodInvocationStatistics Metrics
    • Using JMX to Collect Data
  • MethodMemoryAllocationStatisticsAction

C Using Wildcards in Expressions

• Using Wildcards in Harvester Instance Names
  • Examples
• Specifying Complex and Nested Harvester Attributes
  • Examples
• Using the Accessor with Harvested Complex or Nested Attributes
• Using Wildcards in Watch Rule Instance Names
• Specifying Complex Attributes in Harvester Watch Rules

D WebLogic Scripting Tool Examples

• Example: Dynamically Creating DyeInjection Monitors
• Example: Configuring a Watch and a JMX Notification
• Example: Writing a JMXWatchNotificationListener Class
• Example: Registering MBeans and Attributes For Harvesting
• Example: Setting the WLDF Diagnostic Volume
• Example: Capturing a Diagnostic Image
• Example: Retrieving a JFR File from a Diagnostic Image Capture

Glossary