bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search
e-docs > WebLogic Server > Programming WebLogic Management Services with JMX > Monitoring WebLogic Server MBeans

Programming WebLogic Management Services with JMX

 Previous Next Contents Index View as PDF  

Monitoring WebLogic Server MBeans

WebLogic Server includes a set of monitor MBeans that emit JMX notifications only when specific MBean attributes change beyond a specific threshold. A monitor MBean observes the attribute of another MBean (the observed MBean) at specific intervals. The monitor derives a value from this observation, called the derived gauge. This derived gauge is either the exact value of the observed attribute, or optionally, the difference between two consecutive observed values of a numeric attribute.

When the value of the derived gauge satisfies a set of conditions, the monitor MBean emits a specific notification type. Monitors can also send notifications when certain error cases are encountered while monitoring an attribute value.

The process for monitoring an attribute of an MBean is as follows:

  1. Create a listener class that can listen for notifications from monitor MBeans.
  2. Choose a monitor MBean type that matches the type of data you want to observe.
  3. Configure and instantiate a monitor MBean.
  4. Instantiate the listener class.

This topic contains the following sections:

 

Creating a Notification Listener

As any other MBean, monitor MBeans emit notifications by implementing javax.management.NotificationBroadcaster. To create a listener for notifications from a monitor MBean, create a class that does the following:

  1. Implements NotificationBroadcaster or weblogic.management.RemoteNotificationListener.
  2. Includes the NotificationListener.handleNotification() or the RemoteNotificationListener.handleNotification() method.

You can register the same notification listener with instances of LogBroadcasterMBean, monitor MBeans, or any other MBean.

The example below creates a listener object for an application that runs in a JVM outside the WebLogic Server JVM. It includes logic that outputs additional messages when it receives notifications from monitor MBeans.

Listing 6-1 Listener for Monitor Notifications

import java.rmi.Remote;
import javax.management.Notification;
import javax.management.monitor.MonitorNotification;
import weblogic.management.RemoteNotificationListener;
public class CounterListener 
             implements RemoteNotificationListener {
 public void handleNotification(Notification notification ,Object obj) {
  System.out.println("\n\n Notification Received ...");
  System.out.println("Type=" + notification.getType() );
  System.out.println("SequenceNumber=" + notification.getSequenceNumber());
  System.out.println("Source=" + notification.getSource());
  System.out.println("Timestamp=" + notification.getTimeStamp() + "\n" );
  if(notification instanceof MonitorNotification) {
   MonitorNotification monitorNotification = (MonitorNotification) notification;
   System.out.println("This notification is a MonitorNotification");
   System.out.println("Observed Attribute: " +
                       monitorNotification.getObservedAttribute() );
   System.out.println("Observed Object: " +
                       monitorNotification.getObservedObject() );
   System.out.println("Trigger value: " + monitorNotification.getTrigger() );
  }
 }
}

 

Choosing a WebLogic Server Monitor Type

Monitor MBeans are specialized to observe changes in specific data types. You must instantiate the type of monitor MBean that matches the type of the object that an MBean returns for an attribute value. For example, a monitor MBean based on the StringMonitor type can observe an attribute that is declared as an Object as long as actual values of the attributes are String instances, as determined by the instanceof operator.

To choose a monitor type, do the following:

  1. Determine the type of object that is returned by the MBean attribute that you want to observe by doing any of the following:
  2. Choose a monitor type from the following table.

    A Monitor MBean of This Type

    Observes This Object Type

    CounterMonitor

    Integer

    GaugeMonitor

    Integer or floating-point (Byte, Integer, Short, Long, Float, Double)

    StringMonitor

    String


     

For more information about monitor types, refer to the JMX 1.0 specification, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html. The archive that you download includes the API documentation.

 

Instantiating the Monitor and Listener

After you determine which type of monitor to instantiate, you create a class that instantiates and configures the monitor, and instantiates and registers the listener.

This section contains the following subsections:

Main Steps for Instantiating a Monitor and Listener

To instantiate a monitor MBean and listener object, create a class that does the following:

  1. Creates a monitor object. The example in Listing 6-2 creates a CounterMonitor object using the default constructor of javax.management.monitor.CounterMonitor.
  2. Configures the monitor object by doing the following:
    1. Constructs a JMX object name for the monitor object. Listing 6-2 uses WebLogicObjectName(), but you can use javax.management.ObjectName for the monitor object. The object name must be unique throughout the entire WebLogic Server domain, and it must follow the JMX conventions:

      2. domain name:Name=name,Type=type[,attr=value]...

    2. Constructs a JMX object name for the observed MBean using WebLogicObjectName().

      3. If the observed MBean is a WebLogic Server MBean, you must use WebLogicObjectName() instead of javax.management.ObjectName. You can also use MBeanHome.getMBeansByType() or other WebLogic Server APIs to get the name of the observed MBean object. For examples of different methods of retrieving MBeans, refer to Accessing WebLogic Server MBeans.

    3. Sets values for the monitor's threshold parameters. The set of available parameters varies, depending on whether you are instantiating a CounterMonitor, GaugeMonitor, or StringMonitor.

      4. For more information about the parameters that you pass to configure a monitor argument, refer to Configuring CounterMonitor Objects, Configuring GaugeMonitor Objects, and Configuring StringMonitor Objects.

    4. Configures the monitor object using the monitor's APIs.
  3. Instantiates the listener object that you created in Creating a Notification Listener.
  4. Registers the listener object using the monitor's addNotificationListener() method.
  5. (This step is needed only if your monitor class runs in a JVM that is outside the WebLogic Server JVM.) Initializes a reference to the monitor object within the MBean Server by doing the following:
    1. Retrieving the MBeanServer interface using the Administration MBeanHome interface.
    2. Using the monitor's preRegister() method
  6. Starts the monitor using the monitor's start() method.

Example: Instantiating a CounterMonitor for a Remote Application

The following example creates a monitor for the ServicedRequestTotalCount attribute of the ExecuteQueRuntimeMBean, which returns the number (int) of requests that have been processed by the corresponding execution queue.

Listing 6-2 Instantiating the Monitor and Listener

import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.*;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import javax.management.ObjectName;
import weblogic.management.WebLogicMBean;
import weblogic.management.configuration.ServerMBean;
import weblogic.management.*;
import weblogic.management.monitor.*;
import javax.management.*;
import javax.management.monitor.CounterMonitor;
public class clientMonitor {
    public static void main (String Args[]) {
    try {
      //Instantiate a CounterMonitor 
      CounterMonitor monitor = new CounterMonitor();
       // construct the objectName for your CounterMonitor object
            WebLogicObjectName monitorObjectName = new
              WebLogicObjectName("mydomain:Type=CounterMonitor,Name=MyCounter");
       // Construct the objectName for the observed MBean
            WebLogicObjectName qObjectName = new
                WebLogicObjectName("mihirDomain:Location=MyServer,Name=default,
                           ServerRuntime=MyServer,Type=ExecuteQueueRuntime");
       // Define variables to be used when configuring your CounterMonitor
       // object.
            Integer threshold = new Integer(1000);
            Integer offset = new Integer(2000);
       //Configure your monitor object using the CounterMonitor APIs
            monitor.setThreshold(threshold);
            monitor.setNotify(true);
            monitor.setOffset(offset);
            monitor.setObservedObject(qObjectName);
            monitor.setObservedAttribute("ServicedRequestTotalCount");
       //Instantiate and register your listener with the monitor
         CounterListener listener = new CounterListener();
         monitor.addNotificationListener(listener, null, null);
   //Use the Administration MBeanHome API to get the MBeanServer interface.
   // this is needed when you are registering a monitor from the
   // client side.
     String url = "t3://localhost:7001"; //URL of the Administration server
     String username = "weblogic"; 
     String password = "weblogic";
     MBeanHome home = null;
     Environment env = new Environment();
     env.setProviderUrl(url);
     env.setSecurityPrincipal(username);
     env.setSecurityCredentials(password);
     Context ctx = env.getInitialContext();
     home = (MBeanHome) ctx.lookup(weblogic.management.adminhome);
     RemoteMBeanServer rmbs = home.getMBeanServer();
     monitor.preRegister(rmbs, monitorObjectName);
  //start the monitor
   monitor.start();
}
      catch (Exception e) {   e.printStackTrace();     }   }
}

Configuring CounterMonitor Objects

CounterMonitor objects observe changes in MBean attributes that are expressed as integers. The following list describes groups of CounterMonitor operations that you use to achieve typical configurations of a CounterMonitor instance:

To see all possible configurations of a CounterMonitor instance, refer to the JMX 1.0 API documentation, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html. The archive that you download includes the API documentation.

Configuring GaugeMonitor Objects

GaugeMonitor objects observe changes in MBean attributes that are expressed as integers or floating-point. The following list describes groups of GaugeMonitor operations that you use to achieve typical configurations of a GaugeMonitor instance:

GaugeMonitor does not support an offset or modulus.

To see all possible configurations of a GaugeMonitor instance, refer to the JMX 1.0 API documentation, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html. The archive that you download includes the API documentation.

Configuring StringMonitor Objects

StringMonitor objects observe changes in MBean attributes that are expressed as strings. The following list describes groups of StringMonitor operations that you use to achieve typical configurations of a StringMonitor instance:

To see all possible configurations of a StringMonitor instance, refer to the JMX 1.0 API documentation, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html. The archive that you download includes the API documentation.

 

Notification Types

Each type of monitor MBean emits specific types of notifications. The following table describes the type of notifications that monitor MBeans emit.

A Monitor MBean of This Type

Emits This Notification Type

CounterMonitor

A counter monitor emits a jmx.monitor.counter.threshold when the value of the counter reaches or exceeds a threshold known as the comparison level.

GaugeMonitor

  • If the observed attribute value is increasing and becomes equal to or greater than the high threshold value, the monitor emits a notification type of jmx.monitor.gauge.high. Subsequent crossings of the high threshold value do not cause further notifications unless the attribute value becomes equal to or less than the low threshold value.

  • If the observed attribute value is decreasing and becomes equal to or less than the low threshold value, the monitor emits a notification type of jmx.monitor.gauge.low. Subsequent crossings of the low threshold value do not cause further notifications unless the attribute value becomes equal to or greater than the high threshold value.

StringMonitor

  • If the observed attribute value matches the string to compare value, the monitor emits a notification type of jmx.monitor.string.matches. Subsequent matches of the string to compare values do not cause further notifications unless the attribute value differs from the string to compare value.

  • If the attribute value differs from the string to compare value, the monitor emits a notification type of jmx.monitor.string.differs. Subsequent differences from the string to compare value do not cause further notifications unless the attribute value matches the string to compare value.

 

Error Notification Types

All monitors can emit the following notification types to indicate error cases:

The counter and the gauge monitors can also emit the following jmx.monitor.error.threshold notification type under the following circumstances:

 

Sample Monitoring Scenarios

This section outlines some typical MBean attributes that you might consider monitoring to observe performance and/or resource usage. For more details on individual MBean attributes or methods, see the appropriate MBean API documentation.

JDBC Monitoring

The JDBCConnectionPoolRuntime MBean maintains several attributes that describe the connections to a deployed JDBC connection pool. Applications may monitor these attributes to observe the connection delays and connection failures, as well as connection leaks. The following table outlines those MBean attributes typically used for JDBC monitoring.

JDBCConnectionPoolRuntime MBean Attribute

Typical Monitoring Application

LeakedConnectionCount

Notify a listener when the total number of leaked connections reaches a predefined threshold. Leaked connections are connections that have been checked out but never returned to the connection pool via a close() call; it is important to monitor the total number of leaked connections, as a leaked connection cannot be used to fulfill later connection requests.

ActiveConnectionsCurrentCount

Notify a listener when the current number of active connections to a specified JDBC connection pool reaches a predefined threshold.

ConnectionDelayTime

Notify a listener when the average time to connect to a connection pool exceeds a predefined threshold.

FailuresToReconnect

Notify a listener when the connection pool fails to reconnect to its datastore. Applications may notify a listener when this attribute increments, or when the attribute reaches a threshold, depending on the level of acceptable downtime.

 

Back to Top Previous Next