Figure 1: A data harvester collecting attributes from the JDBCDataSourceRuntimeMBean
Published on dev2dev (http://dev2dev.bea.com/)
http://dev2dev.bea.com/pub/a/2006/06/wldf.html
See this if you're having trouble printing code examples
by Rebecca Sly
06/21/2006
The WebLogic Diagnostics Framework (WLDF) gives administrators and IT managers the ability to analyze their server operating environment using a set of components that generate information from WebLogic servers and the resources, including applications, deployed on the servers. The resulting data can then be gathered for analysis, and later persisted for long-term storage. This information (usually generated by MBeans) can be used to diagnose and resolve issues, monitor and maintain a history of events, carry out performance tuning, and perform many other useful tasks for a system administrator.
The WLDF is a new addition to BEA WebLogic Server 9.0. This article provides an introduction to each components of the WebLogic Diagnostics Framework and how the components work to help you create a better WebLogic server environment.
Editor's note: Check out the related webinar, Deploying Services in BEA WebLogic Server: Explore the Power of WebLogic Diagnostic Framework
In previous versions of WebLogic Server, you had out-of-the-box log files and various monitoring pages in the administration console you could use to track what was going on in your environment. The log files offer a lot of information but are hard to slog through. The monitoring pages were scattered about the console and didn't always have the information you were looking for. If you wanted to take it a step farther you could develop your own JMX-based monitoring tools or you could purchase a third-party product.
The new WebLogic Diagnostics Framework has enhanced the tools available for monitoring a WebLogic Server environment out of the box. WLDF falls somewhere between the old way of monitoring the environment and the fancy third-party JMX and SNMP monitoring tools. It provides the means to track specific elements in your environment, to be notified when something particular happens, to take a snapshot of the environment at a given moment, to filter log messages, and to save all the information gathered for analysis at a later date.
The WebLogic Diagnostics Framework is made up of several components. The major pieces consist of:
These components work together to generate, gather, access, and persist data that will help you monitor your environment and analyze issues you may have with resources. The following sections examine these components and their place in your WebLogic environment.
You have two primary mechanisms for generating data for WLDF: using runtime MBeans, and using instrumentation of the server and/or application. Let's look at each of these in more detail.
To monitor your environment, data needs to be generated by the various systems. Two main pieces in WLDF generate data that will later be collected, accessed, and archived. The primary data generators are the runtime MBeans for each part of the WebLogic server environment. Runtime MBeans exist only on the managed servers that deploy the managed resources. Each instance of the resource running on the server will have a runtime MBean, and each MBean has a set of attributes with data that can be gathered by WLDF. Runtime data held by a runtime MBean is transient; there is no persistent definition of their runtime state. When a server is stopped, all its runtime MBeans are destroyed. For more information on the different types of runtime MBeans and their attributes, see the WebLogic Server MBean Reference guide.
The second way in which data is generated for WLDF is through the Instrumentation component. Instrumentation is a way to define an action that occurs when a point, usually a method, is reached in a body of code. That action can occur before the point is reached, after it has passed the point, or while that point is running, for example, while the body of a method is executing. The action that occurs when that point is reached is simply another piece of code with instructions on what to do. The benefit of instrumentation is you do not have to touch the actual business logic code to add functionality like logging and tracing. Adding this functionality is achieved outside the code and then woven into the code by a special compiler. WLDF instrumentation is based on AspectJ, the Java implementation of aspect-oriented programming. Aspect-oriented programming allows a developer to insert functionality across all parts of an application without modifying the actual application code. This is known as "crosscutting." Some common terminology in AspectJ is:
WLDF provides a predefined set of diagnostic actions that can occur when the defined point in the code is reached; this is how data is generated. Actions can gather method arguments or return values, trace events, the time it takes to perform a method, stack dumps, and thread dumps. At this point, you cannot create your own actions or customize the existing ones.
In WLDF, instrumentation acts as a data provider and a data publisher. Data providers are data creators that are sampled at regular intervals to gather current values. Data publishers are data creators that synchronously generate events. Both the server and an application can be instrumented. These are called "diagnostic monitors."
There are three kinds of diagnostic monitors: standard, delegating, and custom. A standard monitor performs specific, predefined diagnostic actions at specific, predefined pointcuts and locations. A delegating monitor has its scope, pointcuts, and locations hardcoded in the monitor, but you select the actions the monitor will perform. With a custom monitor you assign a name, define the pointcut and the diagnostics location the monitor will use, and then assign actions from the set of predefined diagnostic actions.
The following instrumentation deployment descriptor defines two diagnostic monitors for an application. The first monitor is a delegating monitor with a predefined pointcut, before an entity EJB method is executed, and an action that will generate a trace event. The second monitor is a custom monitor that will generate data containing the amount of time it took to execute any methods in any classes that begin with FindBy, take a string parameter, and return an Enumeration.
<instrumentation> <enabled>true</enabled> <wldf-instrumentation-monitor> <name>EJB_Before_EntityEjbMethods</name> <enabled>true</enabled> <action>TraceAction</action> </wldf-instrumentation-monitor> <wldf-instrumentation-monitor> <name>FindBy</name> <enabled>true</enabled> <action>TraceElapsedTimeAction</action> <location>around</location> <pointcut> execution(Enumeration * findBy*(java.lang.String)); </pointcut> </wldf-instrumentation-monitor> </instrumentation>
So, as you can see, there are two main components of the diagnostics framework that focus on generating data. With the exception of custom runtime MBeans, you do not need to do anything special to runtime MBeans to have them generate data; they do it naturally. Instrumentation requires some setup, with the server-scoped instrumentation requiring less work than application-scoped instrumentation. However, you have more flexibility with application-scoped instrumentation. Your next challenge will be to decide on the means of gathering all the data that interests you.
|
While MBeans and the Instrumentation component are busy generating data, the next major step is to start gathering the pieces of data you are interested in with the eventual goal of analyzing it. A lot of data can be generated from the MBeans and the Instrumentation component so you will probably want to pick and choose what you wish to view. Several components in WLDF help gather the generated data in different ways.
Data harvesters are used to collect, analyze, and archive the metrics that the runtime MBeans generate. Values from selected MBean attributes are gathered by the harvester at a specified sampling rate. Harvesting data is particularly useful for monitoring system state and measuring system performance. The data harvester component is managed by the WLDFHarvesterRuntimeBean, which defines which attributes, instances, and types of other MBeans are harvestable.
Figure 1 and Figure 2 are screenshots from the administration console displaying the configuration of a data harvester.
Figure 1: A data harvester collecting attributes from the JDBCDataSourceRuntimeMBean
Figure 2: Data harvesters can pick the instances from which it gathers the previously chosen attributes.
Watches take the generated data and collect the data of interest to you. A watch will then notify you when the data is generated. This comes in handy when you are looking for a particular event or attribute value. Instead of sitting in front of the server trying to catch it happening, you can let WLDF let you know when it happens. Watches can gather data from log records, data events (instrumentation), and harvested metrics. The watch contains a rule expression so when the conditions are met, one or more notifications are launched. For example, if you wanted to be notified when the SocketsOpenedTotalCount for the administration server was over 5, you would set up a watch with a rule expression such as the following:
<rule-expression>
(${com.bea:Name=MyAdministrationServer,
Type=ServerRuntime//SocketsOpenedTotalCount} > 5)
</rule-expression>
Once you have defined what you are watching and on what servers, then you need to determine how you want to be notified. The notifications inform you when the rule expression or event you are waiting for happens. There are five different kinds of notifications: JMX, JMS, SNMP, SMTP, and Image.
Each watch can have one or more notifications. The WLDFWatchNotificationMBean can provide statistical information about the watches and notifications managed by each server.
A diagnostic image is a server-level state dump for the purpose of diagnosing significant failures. It provides the capability to capture a significant amount of important data in a structured format and then to provide that data to support personnel for analysis. When an image capture is performed, information is collected on the different subsystems, such as JMS, JDBC, EJB, and JNDI, as well as common sources of the server state such as:
The data is saved as a series of XML files in a single archived file. Images can be captured manually through the administration console, via a WLDF notification, as a ""first failure" detection, through WLST and using JMX. The WLDFImageRuntimeMBean is the MBean that supports the creation of a diagnostic image. Each operation performed by the MBean spawns a separate thread to perform the actual work, as shown in Figure 3.
Figure 3: A diagnostic image is a series of .img files (XML files) gathered together into a .zip file.
In summary, other than the standard log files, there are three ways of gathering the data generated by MBeans and instrumentation. The data harvester (collected metrics) will gather data from runtime MBeans so you can pick and choose which runtime MBeans you want data from and what attributes you are interested in. Watches look for a particular event generated from the Instrumentation component, for runtime MBean generated data or for log file entries, gathers the data, and notifies you when it appears. Image capture gathers data about your system by taking a snapshot at a given moment in time. Now it is time to take a look at that data.
|
Once you have finished gathering the data, you will probably want to analyze it to find out what is going on in your system. Before you can do that, however, you will need to access the data and possibly persist it for historical purposes or just in case you call in sick or the data is collected over the weekend.
Diagnostic data is the event data generated from the Instrumentation component and the metric data generated by runtime MBeans and collected by the harvester; diagnostic data can be accessed from a running server or in offline mode, after the server shuts down. While the server is running you can access the data using the administration console, WLST, or third-party tools. In offline mode you can use the WLST command, exportDiagnosticData, to access archived data. Figure 4 illustrates the relationship the data accessor has with the other WLDF components.
Figure 4: The data accessor provides access to data generated from runtime MBeans and events generated by the Instrumentation component. It interacts with the harvester and archive to get the current and past state of harvestable values in the server.
WLDF uses the WLDFDataAccessRuntimeMBean to access data from the different types of data stores. A data store is a WLDF component that stores the gathered diagnostic information.
Data stores are separated by the types of diagnostic data, for example, server logs, HTTP logs, and harvested metrics. They can be modeled as tabular data where each record represents an item and the columns describe the characteristics of an item. Figure 5 illustrates the role of both online and offline data accessors.
Figure 5: Data can be accessed both online and offline. Online accesses current data and offline accesses stored data.
For long-term storage of diagnostic data, you will set up the WLDF data archiver. The Archiver component persists all data events, log records, and metrics collected by the WLDF from WebLogic Server and applications. The diagnostic archive is configured on a per-server basis in the config.xml for the domain, under the server element for the server. The data can be stored in a file or in a database. The WLDF file-based archive is the default storage for historic data and is stored in the data/store/diagnostics directory under the home directory for the server. The location of this file can be changed, and you can also choose to store long-term data in a JDBC-based store. The data archiver uses the following MBeans:
At this point you should have all the tools you need to track what is going on in your environment, including the servers, applications, and system resources. Runtime MBeans, log files, and the Instrumentation component generate data. The data harvester, watches and notifications, log files, and image capture gather the generated data into groups for your convenience. The data accessor helps you access the data using the administration console, WLST, or third-party tools. And finally, the data archiver helps you save the data in a file or in a database. If you are experiencing problems you can ensure the right data is being generated, gathered, and accessed. You then analyze the data to hopefully resolve the issue. If you are trying to enhance the performance in your environment, try creating an Instrumentation event that tracks how long it takes something to happen; if it takes longer than you would expect, have a watch notify you.
If you just want to do some long-term analysis of your environment, then you could take the data generated by the runtime MBeans, gather certain attributes with the data harvester (collected metrics), and persist these attributes in a database for use with a graphing tool. The (diagnostic) world is your oyster with the WebLogic Diagnostics Framework, and I'm sure you can think of a lot more ways to improve your WebLogic environment using the tools provided to you to generate, gather, access, and persist the data in your WebLogic server world.
Rebecca Sly is a curriculum developer in the education services group in BEA focusing on customer education. She started out with BEA in the UK working as an instructor teaching WLS, WLI and WLP courses to customers.
Return to dev2dev.