Configuring and Using the WebLogic Diagnostics Framework

Introduction and Roadmap

What Is the WebLogic Diagnostic Framework?

Document Scope and Audience

Guide to This Document

Samples and Tutorials

Avitek Medical Records Application (MedRec) and Tutorials

New and Changed Features in this Release

Overview of the WLDF Architecture

Overview of the WebLogic Diagnostic Framework

Data Creation, Collection, and Instrumentation

Watch and Notification

Data Accessor

Diagnostic Image Capture

How It All Fits Together

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

Configuring and Capturing Diagnostic Images

How to Initiate Image Captures

Configuring Diagnostic Image Captures

How Diagnostic Image Capture Is Persisted in the Server’s Configuration

Contents of the Captured Image File

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

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

When Configuration Settings Are Validated

Sample Configurations for Different Harvestable Types

Configuring Watches and Notifications

Watches and Notifications

Overview of Watch and Notification Configuration

Sample Watch and Notification Configuration

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

Configuring Notifications

Types of Notifications

Configuring JMX Notifications

Configuring JMS Notifications

Configuring SNMP Notifications

Configuring SMTP Notifications

Configuring Image Notifications

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

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

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

Deploying WLDF Application Modules

Deploying a Diagnostic Module as an Application-Scoped Resource

Using Deployment Plans for Dynamically Controlling Instrumentation Configuration

Using a Deployment Plan: Overview

Creating a Deployment Plan Using weblogic.PlanGenerator

Sample Deployment Plan for Diagnostics

Enabling Hot-Swap Capabilities

Deploying an Application with a Deployment Plan

Updating an Application with a Modified Plan

Configuring and Using WLDF Programmatically

How WLDF Generates and Retrieves Data

Mapping WLDF Components to Beans and Packages

Programming Tools

Configuration and Runtime APIs

Configuration APIs

Runtime APIs

WLDF Packages

Programming WLDF: Examples

Example: DiagnosticContextExample.java

Example: HarvesterMonitor.java

Notification Listeners

HarvesterMonitor.java

Example: JMXAccessorExample.java

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

WLDF Instrumentation Library

Diagnostic Monitor Library

Diagnostic Action Library

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

Terminology