Programming WebLogic Management Services with JMX
To report changes in configuration and runtime information, all WebLogic Server MBeans emit JMX notifications. A notification is a JMX object that describes a state change or some other specific condition that has occurred in an underlying resource.
You can create Java classes called listeners that listen for these notifications. For example, your application can include a listener that receives notifications when applications are deployed, undeployed, or redeployed.
The following sections describe working with notifications and listeners:
All WebLogic Server MBeans implement the javax.management.NotificationBroadcaster
interface, which enable them to emit different types of notification objects depending on the type of event that occurs. For example, MBeans emit notifications when the values of their attributes change.
To listen for these notifications, you create a listener class that implements javax.management.NotificationListener
.
By default, your listener receives all notifications that the MBean emits. However, typically, you want your listener to retrieve only specific notifications. For example, the LogBroadCasterRuntime
MBean emits a notification each time a WebLogic Server instance generates a log message. Usually you listen for only specific log messages, such as messages of specific severity level. To limit the notifications that your listener receives, you can create a notification filter.
After creating your listener and optional filter, you register the classes with the MBeans from which you want to receive notifications.
Figure 6-1 shows a basic system in which a NotificationListener
receives only a subset of the notifications that an MBean broadcasts.
Figure 6-1 Receiving Notifications from an MBean
For a complete explanation of JMX notifications and how they work, download the JMX 1.0 specification from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html.
WebLogic Server includes a set of monitor MBeans that can be configured to periodically observe MBeans and emit JMX notifications only if a specific MBean attribute has changed beyond a specific threshold. A monitor MBean can observe the exact value of an attribute in an MBean, or optionally, the difference between two consecutive values of a numeric attribute. The value that a monitor MBean observes is called the derived gauge.
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.
To use monitor MBeans, you configure and register a monitor with a WebLogic Server MBean. Then you create a listener class and register the class with the monitor MBean. Because monitor MBeans emit only very specific types of notification, you usually do not use filters when listening for notifications from monitor MBeans.
Figure 6-2 shows a basic system in which a monitor MBean is registered with a WebLogic Server MBean. A NotificationListener
is registered with the monitor MBean, and it receives notifications when the conditions within the monitor MBean are satisfied.
WebLogic Server provides two ways to be notified about changes in an MBean: you can create a listener and register it directly with an MBean (see Figure 6-1), or you can configure a monitor MBean that periodically observes an MBean and sends notifications when an attribute value satisfies criteria that you specify (see Figure 6-2). The method that you choose depends mostly on the complexity of the situations in which you want to receive notifications.
If your requirements are simple, registering a listener directly with an MBean is the preferred technique. The NotificationListener
and NotificationFilter
interfaces, which are classes that you implement in your listener and filter, provide few facilities for comparing values with thresholds and other values. You must create you own code to evaluate the data within notifications and respond accordingly. However, the advantage of registering a listener directly with an MBean is that the MBean pushes its notifications to your listener and you are notified of a change almost immediately.
If your notification requirements are sufficiently complex, or if you want to monitor some set of changes that are not directly associated with a single change in the value of an MBean attribute, use a monitor MBean. The monitor MBeans provide a rich set of tools for comparing data and sending notifications only under highly specific circumstances. However, the monitor periodically polls the observed MBean for changes in attribute value and you are notified of a change only as frequently as the polling interval that you specify.
The attributes in Table 6-1 provide a general overview of the performance of WebLogic Server. You can monitor these attributes either by creating a listener and registering it directly with the MBeans that contain the attributes or by configuring monitor MBeans.
To create and register a listener or to configure monitor MBeans, you must provide the WebLogicObjectName
of the MBean that contains the attributes you want to monitor. (See Registering a Notification Listener and Filter and Instantiating the Monitor and Listener.)
Use the information in Table 6-1 to construct the WebLogicObjectName
for each MBean. In the table, domain
refers to the name of the WebLogic Server domain, and server
refers to the name of the WebLogic Server instance that hosts the MBean you want to monitor.
WebLogicObjectName for the MBean: For example: |
Indicates whether the server is in an |
Attribute Name: WebLogicObjectName for the MBean: |
Use these two attributes together to compare the current activity on the server's listen ports to the total number of requests that can be backlogged on the ports. Note that the attributes are located in two separate MBeans: |
WebLogicObjectName for the MBean: |
|
MBean Type: Attribute Name: WebLogicObjectName for the MBean: For example: |
Displays the number of threads in a server's default execute queue that are taking up memory space but are not being used to process data. You can create multiple execute queues on a server instance to optimize the performance of critical applications, but the |
MBean Type: Attribute Name: WebLogicObjectName for the MBean: |
Displays the number of requests waiting in a server's default execute queue. |
Attribute Name: WebLogicObjectName for the MBean: For example: |
Displays the amount of memory (in bytes) that is currently available in the server's JVM heap. For more information, refer to "Tuning Java Virtual Machines (JVMs)." |
MBean Type: Attribute Name: WebLogicObjectName for the MBean: where For example: |
Displays the current number of active connections in a JDBC connection pool. For more information, refer to "How JDBC Connection Pools Enhance Performance." |
MBean Type: Attribute Name: WebLogicObjectName for the MBean: |
The high water mark of active connections in a JDBC connection pool. The count starts at zero each time the connection pool is instantiated. |
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 |
|
MBean Type: |
Notify a listener when the current number of active connections to a specified JDBC connection pool reaches a predefined threshold. |
Notify a listener when the average time to connect to a connection pool exceeds a predefined threshold. |
|
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. |
To listen for the notifications that WebLogic Server MBeans emit directly:
WebLogic Server MBeans implement the javax.management.NotificationBroadcaster
interface, which enable them to emit different types of notification objects depending on the type of event that occurs:
javax.management.AttributeChangeNotification
object.LogBroadcasterRuntimeMBean
emits a notification of type weblogic.management.WebLogicLogNotification
. For more information about WebLogicLogNotification
, refer to the WebLogic Server Javadoc.javax.management.MBeanServerNotification
.add
AttributeName
method to add an element to the array, the MBean emits a weblogic.management.AttributeAddNotification
object. One example of an MBean that exposes add
AttributeName
methods is weblogic.management.configuration.XMLRegistryMBean
. For more information, refer to the WebLogic Server Javadoc.remove
AttributeName
method to remove an element from the array, the MBean emits a weblogic.management.AttributeRemoveNotification
object.For more information about the javax.management
notification types, 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.
For more information about the weblogic.management
notification types, refer to the Javadoc for AttributeAddNotification and AttributeRemoveNotification.
To create a notification listener:
javax.management.NotificationListener
. weblogic.management.RemoteNotificationListener
. NotificationListener.handleNotification(Notification notification, java.lang.Object handback)
method.RemoteNotificationListener.handleNotification(Notification notification, java.lang.Object handback)
method.Note: Your implementation of this method should return as soon as possible to avoid blocking its notification broadcaster.
handleNotification
method, invoke javax.management.Notification
methods on the notification objects.For example, to retrieve the time stamp associated with the notification, invoke notification.getTimeStamp().
Because all notification types extend javax.management.Notification
, the following Notification
methods are available for all notifications:
For more information on Notification
methods, refer to the javax.management.Notification
Javadoc in 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.
WebLogicLogNotification
provides methods for retrieving specific attributes of WebLogic Server log messages, such as getSeverity()
, which retrieves the severity level that the log message specifies.If you want to retrieve data that is specific to a notification type (and therefore not retrievable through the standard javax.management.Notification
methods):
In addition to the previous steps, consider the following while creating your NotificationListener
class:
Instead of using one listener for all possible notifications that an MBean emits, the best practice is to use a combination of filters and listeners. While having multiple listeners adds to the amount of time for initializing the JVM, the trade-off is ease of code maintenance.
For example, if your WebLogic Server domain contains three JDBC connection pools, you can create one listener class that listens for AttributeChangeNotifications
. Then, you create three registration classes. Each registration class registers the listener with a specific instance of a JDBCConnectionPoolRuntime
MBean.
handleNotification
method signature includes an argument for a handback object, your listener does not need to retrieve data from or otherwise manipulate the handback object. It is an opaque object that helps the listener to associate information regarding the MBean emitter.The following example creates a remote listener. Then the listener receives a AttributeChangeNotification object, it uses AttributeChangeNotification methods to retrieve the name of the attribute with a changed value, and the old and new values.
Listing 6-1 Notification Listener
import javax.management.Notification;
import javax.management.NotificationFilter;
import javax.management.NotificationListener;
import weblogic.management.RemoteNotificationListener;
import javax.management.AttributeChangeNotification;
public class MyListener implements RemoteNotificationListener {
public void handleNotification(Notification notification, Object obj) {
if(notification instanceof AttributeChangeNotification) {
AttributeChangeNotification attributeChange =
(AttributeChangeNotification) notification;
System.out.println("This notification is an
AttributeChangeNotification");
System.out.println("Observed Attribute: " +
attributeChange.getAttributeName() );
System.out.println("Old Value: " + attributeChange.getOldValue() );
System.out.println("New Value: " + attributeChange.getNewValue() );
}
}
}
To create and register a filter:
Optionally import the javax.management.NotificationFilterSupport
class, which provides utility methods for filtering notifications. For more information about using these methods, 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.
The filter needs to be serializable only if it is used in a remote notification listener. A class that is used with RMI must be serializable so it can be deconstructed and reconstructed in remote JVMs.
isNotificationEnabled(Notification notification)
method to indicate whether the serializable object returns a true value when a set of conditions are satisfied. If the boolean returns true, then the filter forwards the notification to the listener with which the filter is registered.
javax.management.AttributeChangeNotification
methods to view the new value of a specific attribute. If the value is over a threshold that you specify, you can use JavaMail API to send e-mail to an administrator.Listing 6-2 provides an example NotificationFilter
that forwards only notifications of type AttributeChangeNotification
.
Listing 6-2 Example Notification Filter
import javax.management.Notification;
import javax.management.NotificationFilter;
import javax.management.AttributeChangeNotification;
public class MyHiCountFilter implements NotificationFilter,
java.io.Serializable {
public boolean isNotificationEnabled(Notification notification) {
if (!(notification instanceof AttributeChangeNotification)) {
return false;
}
AttributeChangeNotification acn =
(AttributeChangeNotification)notification;
acn.getAttributeName().equals("ActiveConnectionsHighCount"); {
return true;
}
}
}
If you create a filter for a listener that runs in a remote JVM, you can add the filter's classes to the classpath of the server instance from which you are listening for notifications. Although the listener runs in the remote JVM, adding the filter's classes to the server' s classpath minimizes the transportation of serialized data between the filter and the listener. (See Figure 6-3.)
Figure 6-3 Filters Can Run on WebLogic Server
After you implement a notification listener class and optional filter class, you create an additional class that registers your listener and filter with an MBean instance. You must create one registration class for each MBean instance that you want to monitor.
To register a notification listener and filter:
MBeanHome
interface and then uses MBeanHome
to retrieve the MBeanServer
interface.If you want to register a listener and filter with an Administration MBean, you must retrieve the Administration MBeanHome
, which resides only on the Administration Server. If you want to register with a Local Configuration MBean or a Runtime MBean, you must retrieve the Local MBeanHome
for the server instance that hosts the MBean.
For a list of commonly monitored MBeans and their WebLogicObjectName
, refer to Table 6-1.
WebLogicObjectName
, listener class, and filter class to the addNotificationListener()
method of the MBeanServer
interface.While Figure 6-1 illustrates registering a listener and filter directly with an MBean (which you can do by calling the MBean's addNotificationListener()
method), in practice it is preferable to use the addNotificationListener()
method of the MBeanServer
interface, which saves the trouble of looking up a particular MBean simply for registration purposes.
The following example is a registration class that runs in a remote JVM. If the class ran within the same JVM as a WebLogic Server instance, the code for retrieving the MBeanHome
interface would be simpler. For more information, refer to Accessing an MBeanHome Interface.
The example class registers the listener from Listing 6-1 and filter from Listing 6-2 with the Server Administration MBean for a server instance named Server1. In the example, weblogic
is a user who has permission to view and modify MBean attributes. For information about permissions to view and modify MBeans, refer to "Security Roles" in the Securing WebLogic Resources guide.
The example class also includes some code the keep the class active until it receives a notification. Usually this code is not necessary because a listener class runs in the context of some larger application that is responsible for invoking the class and keeping it active. It is included here so you can easily compile and see the example working.
Listing 6-3 Registering a Listener for an Administration MBean
import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.Context;
import javax.management.ObjectName;
import javax.management.Notification;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.WebLogicMBean;
import weblogic.management.WebLogicObjectName;
import weblogic.management.RemoteMBeanServer;
import weblogic.management.configuration.ServerMBean;
public class listener {
public static void main(String[] args) {
MBeanHome home = null;
RemoteMBeanServer rmbs = null;
//domain variables
String url = "t3://localhost:7001";
String serverName = "Server1";
String username = "weblogic";
String password = "weblogic";
//Using MBeanHome to get MBeanServer.
try {
Environment env = new Environment();
env.setProviderUrl(url);
env.setSecurityPrincipal(username);
env.setSecurityCredentials(password);
Context ctx = env.getInitialContext();
//Getting the Administration MBeanHome.
home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
System.out.println("Got the Admin MBeanHome: " + home );
rmbs = home.getMBeanServer();
} catch (Exception e) {
System.out.println("Caught exception: " + e);
}
try {
//Instantiating your listener class.
MyListener listener = new MyListener();
MyFilter filter = new MyFilter();
//Constructing the WebLogicObjectName of the MBean that you want
//to listen to.
WebLogicObjectName mbeanName = new WebLogicObjectName(serverName,
"Server",home.getDomainName());
System.out.println("Created WebLogicObjectName: " + mbeanName);
//Passing the name of the MBean and your listener class to the
//addNotificationListener method of MBeanServer.
rmbs.addNotificationListener(mbeanName, listener, filter, null);
System.out.println("\n[myListener]: Listener registered ...");
//Keeping the remote client active.
System.out.println("pausing...........");
System.in.read();
} catch(Exception e) {
System.out.println("Exception: " + e);
}
}
}
You can configure the Administration Server to emit a log message when a user changes the configuration or invokes management operations on any resource within a domain. For example, if a user disables SSL on a Managed Server in a domain, the Administration Server emits a log message. These messages provide an audit trail of changes within a domain's configuration (configuration auditing). See "Configuration Auditing" in Administration Console Online Help.
To create and use a JMX listener and filter that respond to configuration auditing messages:
LogBroadcasterRuntime
MBean. This is the MBean that a WebLogic Server instance uses to broadcast its log messages as JMX notifications.If the notification listener runs within the Administration Server's JVM (for example, if it runs as a startup class), add the notification listener and registration class to the Administration Server's classpath as well.
See "Startup and Shutdown Classes" in Administration Console Online Help.
Like the notification listener in Listing 6-1, the listener in Listing 6-4 implements RemoteNotificationListener
and its handleNotification
method.
Because all configuration auditing messages are of type WebLogicLogNotification
, the listener in Listing 6-4 imports the WebLogicLogNotification
interface and uses its methods to retrieve information within each configuration auditing message.
Listing 6-4 Notification Listener for Configuration Auditing Messages
import javax.management.Notification;
import javax.management.NotificationListener;
import weblogic.management.RemoteNotificationListener;
import weblogic.management.logging.WebLogicLogNotification;
public class ConfigAuditListener implements RemoteNotificationListener {
public void handleNotification(Notification notification, Object obj) {
WebLogicLogNotification changeNotification =
(WebLogicLogNotification) notification;
System.out.println("A user has attempted to change the configuration
of a WebLogic Server domain.");
System.out.println("Admin Server Name: " +
changeNotification.getServername() );
System.out.println("Time of attempted change:" +
changeNotification.getTimeStamp() );
System.out.println("Message details:" +
changeNotification.getMessage() );
System.out.println("Message ID string:" +
changeNotification.getMessageId() );
}
}
Without a notification filter, the listener in Listing 6-4 would print the Server Name, Timestamp, and Message Text for all messages that the Administration Server broadcast.
To forward only the configuration auditing message that indicates a resource has been modified, the filter in Listing 6-5 uses the WebLogicLogNotification.getMessageId
method to retrieve the message ID of all incoming log notifications.
The resource-change configuration auditing message is identified by the message ID 159904
(see Configuration Auditing" in Administration Console Online Help). If the message ID value in an incoming log notification matches the configuration auditing message ID, the filter evaluates as true
and forwards the message to its registered listener.
Listing 6-5 Notification Filter for Configuration Auditing Messages
import javax.management.Notification;
import javax.management.NotificationFilter;
import weblogic.management.logging.WebLogicLogNotification;
public class ConfigAuditFilter implements NotificationFilter ,
java.io.Serializable{
int configChangedId =159904
;
public boolean isNotificationEnabled(Notification notification) {
if (!(notification instanceof WebLogicLogNotification)) {
return false;
}
WebLogicLogNotification wln =
(WebLogicLogNotification)notification;
int messageId = wln.getMessageId();
if (configChangedId == messageId) {
return true;
} else {
return false;
}
}
}
The class in Listing 6-6 registers the notification listener and filter with the LogBroadcasterRuntime
MBean of the Administration Server. This MBean is a singleton in each instance of WebLogic Server and is always named TheLogBroadcaster
.
Listing 6-6 Registration Class for Configuration Auditing Messages
import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.Context;
import javax.management.ObjectName;
import javax.management.Notification;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.WebLogicMBean;
import weblogic.management.WebLogicObjectName;
import weblogic.management.RemoteMBeanServer;
import weblogic.management.configuration.ServerMBean;
public class ListenRegistration {
public static void main(String[] args) {
MBeanHome home = null;
RemoteMBeanServer rmbs = null;
//domain variables
String url = "t3://localhost:7001";
String serverName = "examplesServer";
String username = "weblogic";
String password = "weblogic";
//Using MBeanHome to get MBeanServer.
try {
Environment env = new Environment();
env.setProviderUrl(url);
env.setSecurityPrincipal(username);
env.setSecurityCredentials(password);
Context ctx = env.getInitialContext();
//Getting the Administration MBeanHome.
home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
System.out.println("Got the Admin MBeanHome: " + home );
rmbs = home.getMBeanServer();
} catch (Exception e) {
System.out.println("Caught exception: " + e);
}
try {
//Instantiating your listener class.
ConfigAuditListener listener = new ConfigAuditListener();
ConfigAuditFilter filter = new ConfigAuditFilter();
//Constructing the WebLogicObjectName of the MBean that you want
//to listen to.
WebLogicObjectName mbeanName = new WebLogicObjectName(
"TheLogBroadcaster",
"LogBroadcasterRuntime",
home.getDomainName(),
serverName );
System.out.println("Created WebLogicObjectName: " + mbeanName);
//Passing the name of the MBean and your listener class to the
//addNotificationListener method of MBeanServer.
rmbs.addNotificationListener(mbeanName, listener, filter, null);
System.out.println("\n[myListener]: Listener registered ...");
//Keeping the remote client active.
System.out.println("pausing...........");
System.in.read();
} catch(Exception e) {
System.out.println("Exception: " + e);
}
}
}
To configure and use monitor MBeans:
WebLogic Server provides monitor MBeans that are specialized to observe changes in specific data types. You must configure and 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.
weblogic.Admin GET
command, which provides information about the MBean that you specify. For more information, refer to "MBean Management Command Reference" in Configuring and Managing WebLogic Server.javap
command on the MBean you are monitoring. The javap
command is a standard Java utility that disassembles a class file.
Integer or floating-point ( |
|
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.
Each type of monitor MBean emits specific types of javax.management.monitor.MonitorNotification
notifications. For any given notification, you can use the MonitorNotification.getType()
method to determine its type.
The following table describes the type of notifications that monitor MBeans emit.
All monitors can emit the following notification types to indicate error cases:
jmx.monitor.error.mbean
, which indicates that the observed MBean is not registered in the MBean Server. The observed object name is provided in the notification.jmx.monitor.error.attribute
, which indicates that the observed attribute does not exist in the observed object. The observed object name and observed attribute name are provided in the notification.jmx.monitor.error.type
, which indicates that the object instance of the observed attribute value is null
or not of the appropriate type for the given monitor. The observed object name and observed attribute name are provided in the notification.jmx.monitor.error.runtime
, which contains exceptions that are thrown while trying to get the value of the observed attribute (for reasons other than the cases described above).The counter and the gauge monitors can also emit the following jmx.monitor.error.threshold
notification type under the following circumstances:
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:
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. You could further refine the logic so that listener responds differently to the different types of monitor notifications described in Monitor Notification Types.
Listing 6-7 Listener for Monitor Notifications
import javax.management.Notification;
import javax.management.NotificationListener;
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("Message=" + notification.getMessage() );
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() );
}
}
}
The steps you take to register a monitor MBean with an observed MBean differ depending on whether you are registering the monitor MBean on a single server instance or on multiple server instances in a domain.
Note: Because WebLogic Server does not provide type-safe stubs for monitor MBeans, you must use standard JMX design patterns in which your JMX client uses the MBeanServer
interface to get and set attributes and invoke operations on the monitor MBean.
The following sections provide examples for both tasks:
The following example creates a counter monitor for the ServicedRequestTotalCount
attribute of the ExecuteQueueRuntimeMBean
, which returns the number of requests that have been processed by the corresponding execution queue. WebLogic Server uses execute queues to optimize the performance of critical applications. For more information, refer to "Using Execute Queues to Control Thread Usage."
To create a counter monitor for an ExecuteQueueRuntimeMBean
on a single server instance, the example class in Listing 6-8:
The object name must be unique throughout the entire WebLogic Server domain and it must follow the JMX conventions:
domain name
:Name=
name
,Type=
type
[,attr
=value
]...
See the Javadoc for javax.management.ObjectName
, which you can download from http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html.
CounterMonitorMBean
and registers it under the object name that you created in the previous step.The MBeanServer.createMBean
method both creates the MBean object in the WebLogic Server JVM and registers the object in the server's MBean server.
CounterMonitorMBean ObservedObject
attribute.For a list of commonly monitored MBeans and their WebLogicObjectName
, refer to Table 6-1.
For information about the attributes and operations that you use to configure monitors, refer to:
Configuring CounterMonitor Objects
Configuring GaugeMonitor Objects
In the example, weblogic
is a user who has permission to view and modify MBean attributes. For information about permissions to view and modify MBeans, refer to "Security Roles" in the Securing WebLogic Resources guide.
Listing 6-8 Instantiating a Counter Monitor and Listener on a Single Server
import javax.management.Attribute;
import javax.management.AttributeList;
import javax.management.MBeanServer;
import javax.management.ObjectInstance;
import javax.management.ObjectName;
import javax.management.monitor.CounterMonitor;
import javax.naming.Context;
import javax.naming.InitialContext;
import java.util.Hashtable;
public class ClientMonitor {
// The name of the WebLogic domain. Please change this to match the
// name of your installation specific domain name
private static String weblogicDomain = "mydomain";
// The name and URL of the WebLogic server. Please change these to match the
// name of your installation specific server name and URL
private static String weblogicServer = "myserver";
private static String url = "t3://localhost:7001";
// The credentials for a user in the Administrator role. Please change these
// to match the name of an administrator in your security realm.
private static String username = "weblogic";
private static String password = "weblogic";
public static void main(String Args[]) {
try {
//Get the MBeanServer interface this is needed when you are
// creating/registering a monitor from the client side.
MBeanServer rmbs = null;
Hashtable props = new Hashtable();
props.put(Context.PROVIDER_URL, url);
props.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
props.put(Context.SECURITY_PRINCIPAL, username);
props.put(Context.SECURITY_CREDENTIALS, password);
InitialContext ctx = new InitialContext(props);
rmbs = (MBeanServer) ctx.lookup("weblogic.management.server");
// Construct the objectName for your CounterMonitor object
ObjectName monitorObjectName = new ObjectName(
"mcompany:Name=MyCounter,Type=CounterMonitor");
// Create the Monitor MBean.
rmbs.createMBean(
"javax.management.monitor.CounterMonitor", monitorObjectName);
//Configure your monitor object using the MBean attributes
AttributeList monitorAttributes = new AttributeList();
// Construct the objectName for the observed MBean
ObjectName qObjectName = new ObjectName(weblogicDomain
+ ":Name=weblogic.kernel.Default,Location=" + weblogicServer
+ ",Type=ExecuteQueueRuntime,ServerRuntime=" + weblogicServer);
Attribute observedObjectAttribute = new Attribute("ObservedObject",
qObjectName);
monitorAttributes.add(observedObjectAttribute);
Attribute observedAttributeAttribute =
new Attribute("ObservedAttribute", "ServicedRequestTotalCount");
monitorAttributes.add(observedAttributeAttribute);
Attribute notifyAttribute = new Attribute("Notify", new Boolean(true));
monitorAttributes.add(notifyAttribute);
// Define variables to be used when configuring your
// CounterMonitor object.
Integer threshold = new Integer(10);
Integer offset = new Integer(1);
Attribute thresholdAttribute = new Attribute("Threshold", threshold);
monitorAttributes.add(thresholdAttribute);
Attribute offsetAttribute = new Attribute("Offset", offset);
monitorAttributes.add(offsetAttribute);
monitorAttributes = rmbs.setAttributes(monitorObjectName,
monitorAttributes);
//Instantiate and register your listener with the monitor
CounterListener listener = new CounterListener();
rmbs.addNotificationListener(monitorObjectName, listener, null, null);
// Start the monitor
Object[] params = new Object[0];
String[] signature = new String[0];
rmbs.invoke(monitorObjectName, "start", params, signature);
// Prevent the client program from exiting
synchronized (listener) {
try {
listener.wait();
} catch (InterruptedException ignore) {
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
A WebLogic Server domain maintains a set of MBean instances for each server instance. For example, each server instance hosts its own ServerRuntimeMBean
, LogMBean
, and ExecuteQueueRuntimeMBean
. As a convenience, you can access all of these MBean instances from a single connection to the Administration Server. This single connection also enables you to create monitor MBeans for these MBeans on all servers in the domain. For example, your JMX client can connect to the Administration Server and create a counter monitor MBean on each Managed Server to monitor the server's ExecuteQueueRuntimeMBean
.
JMX clients that use this technique must import the weblogic.management.MBeanHome
and weblogic.management.runtime.ServerRuntimeMBean
classes.
To monitor instances of ExecuteQueueRuntimeMBean
on each server instance in a domain, the code excerpt in Listing 6-9 does the following:
The Administration MBeanHome
interface enables your client to access all active server instances in the domain without having to determine the listen address and listen port for each server instance and without having to determine whether the server instance is currently active.
Only servers that are currently running maintain a ServerRuntimeMBean
instance. If a server is not running, the MBeanHome.getMBeansByType
method will not return a ServerRuntimeMBean
for the server.
Once the code retrieves the local server's MBeanServer
interface, it can proceed with creating monitor MBeans as in Listing 6-8.
Listing 6-9 Instantiating a Monitor on Multiple Server Instances
import weblogic.management.MBeanHome;
import weblogic.management.runtime.ServerRuntimeMBean;
...
// Get the Admin home
MBeanHome adminhome = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
// Get the list of running managed servers and iterate over it
Set srSet = adminhome.getMBeansByType("ServerRuntime");
Iterator sr_iter = srSet.iterator();
while (sr_iter.hasNext()) {
ServerRuntimeMBean bean = (ServerRuntimeMBean) sr_iter.next();
// Get the local home for the managed server
MBeanHome localhome =
(MBeanHome) ctx.lookup(MBeanHome.JNDI_NAME + "." + bean.getName());
// Get the MBeanServer for the managed server
MBeanServer rmbs = localhome.getMBeanServer();
... // code to create monitor MBeans
}
CounterMonitor
objects observe changes in MBean attributes that are expressed as integers. The following list describes groups of CounterMonitor
attributes that you set to achieve typical configurations of a CounterMonitor
instance:
Threshold
to 1000
and Offset
to 2000
, when the observed attribute exceeds 1000
, the CounterMonitor
object sends a notification and increases the threshold to 3000
. When the observed attribute exceeds 3000
, the CounterMonitor
object sends a notification and increases the threshold again to 5000
.Modulus
attribute, the threshold is returned to the value that was specified through the latest call to setter for the monitor's Threshold
attribute, before any offsets were applied. For example, if the original Threshold
is set to 1000
and the Modulus
is set to 5000
, when the Threshold
exceeds 5000
, the monitor sends a notification and resets the Threshold
to 1000
.Threshold
is 20
and the monitor observes an attribute value of 2
. If the next observation is greater than 22
, then the monitor sends a notification. However, if the value is 10
at the next observation, and 25
at the following observation, then the monitor does not send a notification because the value has not changed by more than 20
for any two consecutive observations.Modulus
attribute, the threshold is returned to the value that was specified through the latest call to setter for the monitor's Threshold
attribute, before any offsets were applied. 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.
GaugeMonitor
objects observe changes in MBean attributes that are expressed as integers or floating-point. The following list describes groups of GaugeMonitor
attributes and 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.
StringMonitor
objects observe changes in MBean attributes that are expressed as strings. The following list describes groups of StringMonitor
attributes that you set to achieve typical configurations of a StringMonitor
instance:
StringToCompare
.StringToCompare
.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.