Managing and Monitoring Sun Java System Application Server 8.1

Print-friendly Version

Sun Java System Application Server 8.1 (henceforth, Application Server) includes a robust set of management tools and an implementation of the Java 2 Platform, Enterprise Edition 1.4 (J2EE 1.4 platform) Management Specification (Java Specification Request 77, JSR 77 for short). The J2EE 1.4 platform specification also includes a management information model and a standard management and monitoring interface; Application Server is fully compatible with that platform. Those standards, combined with vendor-specific tools and enhancements, make it simpler to access server management functionality and develop applications that monitor and manage Application Server and its resources.

This article introduces the management tools and the associated APIs and shows you how to use them to monitor the system attributes.

Figure 1 illustrates the management architecture in Application Server. You access all administrative and monitoring operations through Java Management Extensions (JMX) Management Beans (MBeans). Because administrative domains can span multiple machines, you can access remote MBeans through JMX connectors (JSR 160).

Figure 1: Management Architecture in Sun Java System Application Server 8.1

Initially, at installation, the installer creates a domain with a stand-alone server, the Domain Administration Server (DAS). A central repository, which is maintained on the DAS file system, contains the following:

• The domain configuration file, domain.xml
  
  
• All the deployed J2EE applications, J2EE modules, and life-cycle modules
  
  
• Static content delivered over HTTP, shared Java archive (JAR) files, and other configuration files, such as the password file for authenticating J2EE file realms, security policy files, and Secure Sockets Layer (SSL) keystores.
  

With the exception of DAS, each server instance or node agent keeps its own partial copy of the central repository. The copied central repository ensures that you can restart the server instances and node agents without the DAS running. The DAS, however, does not maintain a cache and runs according to the configuration in the central repository.

The node agent is a lightweight, Java virtual machine process that hosts a JMX runtime and executes the life-cycle operations for the server instances on the node (host machine). The standard configuration is one node agent per domain per host machine. However, since multiple domains can coexist on a single node, each node can have multiple node agents that serve a domain. Concurrently, each node agent maintains a one-on-one relationship with a domain.

This section describes the Application Server management and monitoring tools along with examples.

The Admin Console is a browser-based tool with an easy-to-navigate interface and online help. Figure 2 shows an example of that console performing a monitoring task.

Figure 2: Application Server Admin Console Performing a Monitoring Task

Here, the domain consists of applications, resources, clusters, instances, node agents, and configurations. Clicking and expanding a cluster displays the instances; clicking an instance opens the instance screen.

In addition, if you click the Monitoring tab and choose a module, all the parameters that you can monitor for that module are displayed. Also displayed are timestamps in the locale's date format.

Figure 3 shows the controls for configuring the monitoring settings from the Admin Console.

Figure 3: Configuration Controls for Monitoring Application Server

Here, you can set the monitoring levels for the various components to HIGH, LOW, or OFF. Enabling monitoring has a negative performance impact, so choose your options carefully. This is a cluster-wide operation that applies to all the instances in the cluster.

The asadmin utility is the command-line interface (CLI) for performing administrative tasks for Application Server. In the current release, asadmin includes new commands for generic access to MBeans.

If monitoring is enabled, asadmin can display the attributes that you can monitor. Application Server uses a tree structure to track monitorable objects. That tree is dynamic and changes as you add, update, or delete instance components. The root object in the tree is the server instance name, for example, server.

To view the names of the objects that you can monitor, run the asadmin list command. For example, to display the application components and subsystems that have monitoring enabled for the server instance, type the following command to display the top level of the tree:

asadmin list --monitor server

Here's an example of the output:

server.applications
server.http-service
server.connector-service
server.jms-service
server.jvm
server.orb
server.resources
server.thread-pools

To display the statistics for an application component or subsystem for which monitoring has been enabled, run the asadmin get command and specify as an argument the name displayed by asadmin list in the preceding step. For example, type the following command line to display the attributes from a subsystem for a specific object:

asadmin get --monitor server.jvm.*

Here's an example of the output that lists the attributes and relevant data:

server.jvm.dotted-name = server.jvm
server.jvm.heapsize-current = 49160192
server.jvm.heapsize-description = Provides statistical information about the JVM's
memory heap size.
server.jvm.heapsize-highwatermark = 49160192
server.jvm.heapsize-lastsampletime = 1095958878163
server.jvm.heapsize-lowerbound = 0
server.jvm.heapsize-lowwatermark = 0
server.jvm.heapsize-name = JvmHeapSize
server.jvm.heapsize-starttime = 1095958503675
server.jvm.heapsize-unit = bytes
server.jvm.heapsize-upperbound = 531628032
server.jvm.uptime-count = 374510
server.jvm.uptime-description = Provides the amount of time the JVM has been running.
server.jvm.uptime-lastsampletime = 1095958878164
server.jvm.uptime-name = JvmUpTime
server.jvm.uptime-starttime = 1095958503667
server.jvm.uptime-unit = milliseconds

Table 1 describes the parameters that you can monitor by specifying them as arguments to the asadmin get --monitor command.

Table 1: Parameters for Monitoring

Description and Dotted Notation
Parameters related to bean methods: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name
Parameters related to the bean pool: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-pool
Parameters related to the bean cache: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache
Parameters related to the virtual server: instance_name.applications.app_name.WAR_name.server_name
Parameters related to the connector service: instance_name.connector-service
Parameters related to the connection queue of HTTP service: instance_name.http-service.connection-queue
Parameters related to the domain name service (DNS) of the HTTP service: instance_name.http-service.dns
Parameters related to the file cache of the HTTP service: instance_name.http-service.file-cache
Parameters related to the keep-alive capability of the HTTP service: instance_name.http-service.keep-alive
Parameters related to the production Web container (PWC) thread pool of the HTTP service: instance_name.http-service.pwc-thread-pool
Parameters related to the request of the HTTP service: instance_name.http-service.service.request
Parameters related to the Java Message Service (JMS): instance_name.jms-service
Parameters related to the Java virtual machine: instance_name.jvm
Parameters related to the Object Request Broker (ORB): instance_name.orb.connection-managers.orb\.Connections\.Inbound\.AcceptedConnections
Parameters related to the resources: instance_name.resources
Parameters related to the default thread pool: instance_name.thread-pools.orb\.threadpool\.default-threadpool
Parameters related to a specific thread pool: instance_name.thread-pools.orb\.threadpool\.thread-pool-1
Parameters related to the transaction service: instance_name.transaction-service
The time in milliseconds spent during the last successful or unsuccessful attempt to execute the operation: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.executiontime-count
The number of times an operation was called, the total time spent during its execution, and other related measurements: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.methodstatistic-count instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.methodstatistic-maxtime instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.methodstatistic-mintime instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.methodstatistic-totaltime
The total number of errors that occurred during invocation or execution of an operation: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.totalnumerrors-count
The total number of successful invocations of the method: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-methods.method_name.totalnumsuccess-count
The number of times a user request hits an Enterprise JavaBeans (EJB) component in an associated EJB cache instance; also, the information on high and low watermarks as well as upper and lower bounds: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachehits-current instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-highwatermark instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-lowwatermark instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-upperbound instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-lowerbound
The number of times a user request fails to find an Enterprise JavaBeans (EJB) component in an associated EJB cache instance; also, the information on high and low watermarks as well as upper and lower bounds: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-current instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-highwatermark instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-lowwatermark instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-upperbound instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.cachemisses-lowerbound
The total number of EJB components in the associated EJB cache and the various statistical values, such as high and low watermarks as well as upper and lower bounds: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numbeansincache-current instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numbeansincache-highwatermark instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numbeansincache-lowwatermark instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numbeansincache-upperbound instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numbeansincache-lowerbound
The number of beans in a cache: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numbeansincache-name
The number of expired sessions that were deleted from the bean cache: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numexpiredsessionsremoved-count
The number of errors that occurred while you were passivating a stateful session bean from the bean cache: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numpassivationerrorscount
The number of passivations for a stateful session bean from the bean cache: instance_name.applications.app_name.EJB-JAR_name.bean_name.bean-cache.numpassivations-count
The number of successful passivations for a stateful session bean from the bean cache: instance_name.applications.app_name.EJB-JAR_name.bean_name.beancache.numpassivationsuccess-count
Information on whether profiling is enabled: instance_name.http-service.flagprofilingenabled-count
Information on whether an overflow exists in the virtual server: instance_name.http-service.flagvirtualserveroverflow-count
Instance name: instance_name.http-service.id-current
Parameters related to an average of 15-minute loads by the HTTP service: instance_name.http-service.load15minuteaverage-count
Parameters related to an average of 1-minute loads by the HTTP service: instance_name.http-service.load1minuteaverage-count
Parameters related to an average of 5-minute loads by the HTTP service: instance_name.http-service.load5minuteaverage-count
Parameters related to the maximum number of threads of the HTTP service: instance_name.http-service.maxthreads-count
The maximum number of request processing threads created by the listener, that is, the maximum number of simultaneous requests Application Server can handle: instance_name.http-service.maxthreads-description
Parameters related to the maximum virtual servers of the HTTP service: instance_name.http-service.maxvirtualservers-count
Parameters related to the rate of bytes received by the HTTP service: instance_name.http-service.ratebytesreceived-count
Parameters related to the rate of bytes transmitted by the HTTP service: instance_name.http-service.ratebytestransmitted-count
The time in seconds since the service started: instance_name.http-service.secondsrunning-count
The start time of the HTTP service: instance_name.http-service.timestarted-current
The version of the HTTP service engine: instance_name.http-service.versionserver-current

For details, see Chapter 21, "Monitoring Components and Services," in the Sun Java System Application Server Enterprise Edition 8.1 Administration Guide.

This section introduces JSR 77 and the associated managing and monitoring APIs.

JSR 77 specifies the following:

• A hierarchical model of standards-managed objects that are based on the J2EE component model
• A remote client interface (javax.management.j2ee.Management) that is based on JMX and EJB standards

The objects types are hierarchically arranged in a tree with associations to the following:

• The children of a managed object, defined as ObjectName string attributes of the managed object
• The parent-managed object, defined as standard properties of ObjectName itself

For example, an application deployed to a J2EE server called server1 would have an ObjectName attribute with the property J2EEServer=server1, which indicates that the application is deployed on server1. Also, the application's J2EE application-managed object would contain the attribute modules with an array of OBJECT_NAME strings that's equivalent to the return value of javax.management.ObjectName.toString(). That way, the client can reference the child objects that contain the management information for the modules that make up the application.

For the complete standard managed object types model, see the J2EE Management Specification.

The Management Enterprise JavaBeans (MEJB) component is an interoperable vendor-neutral connector for remotely managing and monitoring clients, and it is a required standard for all the servers that comply with the J2EE 1.4 platform. An MEJB client can access the MBeans on compliant servers.

The MEJB interface is nearly identical to the JMX javax.management.MBeanServer interface. The former contains a getListenerRegistry method that enables the client to listen to remote event notifications with a simple local object by returning a listener proxy. Also, the MEJB component does not include the MBeanServer methods that create, register, and unregister MBeans. Instead, those operations are controlled by the server containers according to the deployed life cycle of the managed components.

You implement an MEJB component as a standard session bean that can be accessed by J2EE components or stand-alone Internet Inter-ORB Protocol (IIOP) clients. In Application Server, the default security configuration for an MEJB component enables only the default file realm's authenticated users, who belong to the asadmin group, to access the MEJB methods.

The code segment below assumes a user (whose ID and password are j2ee) in the asadmin group in the default realm. The Java Naming and Directory Interface (JNDI) name for the MEJB is ejb/mgmt/MEJB. Here, you see how a stand-alone client authenticates itself with the server and connects to the MEJB.

try {
    Context ctx = new InitialContext();
    Object objref = ctx.lookup(jndiName);
    ManagementHome home = (ManagementHome)PortableRemoteObject.narrow(objref,
javax.management.j2ee.ManagementHome.class);

    // Authentication
    ProgrammaticLogin pl = new ProgrammaticLogin();
    System.out.println("Login success = " + pl.login("j2ee","j2ee","default", true));

    // Use the MEJB
    Management mejb = home.create();

For information on adding users, see the section Managing File Realm Users in Chapter 14 of the Sun Java System Application Server Enterprise Edition 8.1 Administration Guide.

See a complete example of an MEJB standalone client that connects and authenticates to the MEJB, locates all the available MBeans, and prints the information on their attributes and operations. To compile this example, first do the following:

1. Add three Java archives (JARs) to your class path in the lib directory of Application Server's root installation directory: j2ee.jar, appserv-rt.jar, and appserv-admin.jar.
   
   
2. Set the values for the Java virtual machine startup options, as follows:
   
   jvmarg value = "-Dorg.omg.CORBA.ORBInitialHost=${ORBhost}"
jvmarg value = "-Dorg.omg.CORBA.ORBInitialPort=${ORBport}"
   
   where ORBhost is Application Server's host name and ORBport is the ORB port number, whose default is 3700 for the default instance. You can obtain that information from the domain.xml file on the remote system. For details on that file, see Chapter 1 in Sun Java System Application Server Enterprise Edition 8.1 Administration Reference.

Here is an example of the compilation command line (all on one line):

java -classpath
.;c:\Sun\AppServer.ib\j2ee.jar;c:\Sun\AppServer.ib\appservrt.jar;c:\Sun\AppServer.ib
\appserv-admin.jar
-Dorg.omg.CORBA.ORBInitialHost=localhost
-Dorg.omg.CORBA.ORBInitialPort=3700 MEJBStandaloneClient ejb/mgmt/MEJB

The client can programmatically adjust monitoring levels through the MEJB. The MBean that sets the monitoring levels for different modules is the module-monitoring-levels MBean. To retrieve that MBean for the default server configuration, set JMX ObjectName as follows:

ObjectName monitorLevels = new ObjectName("com.sun.appserv:type=module-monitoring-levels,
config=server-config,category=config");

By setting the appropriate attribute to HIGH, LOW, or OFF, you can adjust the monitoring levels as desired. The attributes for module-monitoring levels are as follows:

connector-connection-pool		jvm
connector-service		orb
ejb-container		thread-pool
http-service		transaction-service
jdbc-connection-pool		web-container
jms-service

 

For example, to set the Java virtual machine monitoring level to HIGH, configure the attribute like this:

mejb.setAttribute(monitorLevels, new Attribute("jvm","HIGH"));

 

Retrieval of Monitoring Data

 

With monitoring enabled for a module, the monitoring data are stored in an MBean. To identify the MBeans that hold this information, set the ObjectName pattern as follows:

"com.sun.appserv:category=monitor,type=<monitor type>,server=<instance_name>,name=<name>*"

 

The metadata are derived from the dotted name, which has the pattern <instance_name>.<type>.<name>. Since some of the monitoring objects, such as server.jvm, do not use the name property to retrieve the server.jvm statistic, set the ObjectName pattern as follows:

"com.sun.appserv:category=monitor,type=jvm,server=server"

 

The MBean returned by the query contains all the monitoring data available for the Java virtual machine and includes the JSR 77 statisticProvider methods, which return objects that implement the interfaces for JSR 77 statistics. See the runtime output of the MEJBStandaloneClient example for the Java virtual machine monitor MBean.

Event Notifications

 

A key capability of the MEJB interface enables the client to register a local listener and receive remote event notifications. Events are instances of javax.management.Notification. All JSR 77-compliant MBeans support the boolean attribute eventProvider, which specifies whether that MBean emits event notifications. Listeners must implement the javax.management.NotificationListener interface. The MEJB client registers the listener with the ListenerRegistration interface, which contains two methods:

• Add a listener to a registered, managed object.
  
  

  public void addNotificationListener(javax.management.ObjectName name, javax.management.NotificationListener listener, javax.management.NotificationFilter filter, Object handback)

   
  
• Delete a listener from a registered, managed object.
  
  

  public void removeNotificationListener(javax.management.ObjectName name,javax.management.NotificationListener listener)

   
  

To obtain the object that implements this interface, call the getListenerRegistry() method of the MEJB, followed by the addNotificationListener method on the returned ListenerRegistration object. For example:

ListenerRegistration lr = mejb.getListenerRegistry(); lr.addNotificationListener(objectname, listener, null, "MEJBTester");

 

For details on notifications, see the JMX Specification and the J2EE Management Specification.

Application Server Management Extensions

Application Server Management Extensions (AMX), a superset of JSR 77, are interfaces and MBeans that smooth the way for programmatically managing Application Server. Besides being a strongly typed and convenient interface for accessing the server-side MBeans, AMX is intuitive by virtue of its familiar Java object model. It also supports navigation and creation of objects.

A client uses an AMX interface through dynamic client-side proxies that implement them. The attributes are exposed as getters and setters. MBean operations are exposed as Java methods.

AMX supports connections to the DAS only. All AMXs that emit Notification instances place Map within the userData field of a standard Notification, which you can obtain with the Notification.getUserData() method. Within Map are zero or more items that vary according to the Notification type. Each Notification type and its data are defined in its respective MBean or an appropriate location.

If Application Server is running with Transport Layer Security (TLS) enabled, you must use the constructor that includes the TLSParams parameter. Here is an example of how to connect to Application Server with TLS enabled.

final File trustStore = new File( "~/.keystore" ); final char[] trustStorePassword = "changeme".toCharArray(); // or whatever it is final HandshakeCompletedListener listener = new HandshakeCompletedListenerImpl(); final TrustStoreTrustManager trustMgr = new TrustStoreTrustManager( trustStore, trustStorePassword); trustMgr.setPrompt( true ); final TLSParams tlsParams = new TLSParams( new X509TrustManager[] { trustMgr }, listener ); final AppserverConnectionSource src = new AppserverConnectionSource( AppserverConnectionSource.PROTOCOL_RMI, "localhost", 8686, "admin", "admin123", tlsParams, null ); final DomainRoot domainRoot = src.getDomainRoot();

 

If security is not a concern, simply disable TLS on Application Server. However, you can also connect with TLS, whereby the server certificate is always trusted, as follows:

final TLSParams tlsParams = new TLSParams( TrustAnyTrustManager.getInstanceArray(), null ); final AppserverConnectionSource src = new AppserverConnectionSource( AppserverConnectionSource.PROTOCOL_RMI, "localhost", 8686, "admin", "admin123", tlsParams, null ); final DomainRoot domainRoot = src.getDomainRoot();

 

Access to Application Server From DomainRoot

 

You can access the other parts of Application Server from the DomainRoot class. The methods are as follows.

java.lang.String	getAppserverDomainName() Return the name of this Application Server domain.
BulkAccess	getBulkAccess() Retrieve BulkAccess.
ConfigDottedNames	getConfigDottedNames() Retrieve ConfigDottedNames.
DeploymentMgr	getDeploymentMgr() Retrieve DeploymentMgr.
DomainConfig	getDomainConfig() Retrieve DomainConfig.
J2EEDomain	getJ2EEDomain() Retrieve JSR 77 J2EEDomain.
JMXMonitorMgr	getJMXMonitorMgr() Retrieve JMXMonitorMgr.
MonitoringDottedNames	getMonitoringDottedNames() Retrieve MonitoringDottedNames.
MonitoringRoot	getMonitoringRoot() Retrieve MonitoringRoot.
NotificationServiceMgr	getNotificationServiceMgr() Retrieve NotificationServiceMgr.
QueryMgr	getQueryMgr() Retrieve QueryMgr.
SystemInfo	getSystemInfo() Retrieve SystemInfo.
UploadDownloadMgr	getUploadDownloadMgr() Retrieve UploadDownloadMgr.

 

Declarative Alerts

 

The following code exemplifies the configuration for a declarative alert from the domain.xml file in Application Server. Whenever the listener receives notifications from the MBeans listed, this alert sends an email message to the recipients, as specified.

<alert-service> <alert-subscription id=subscription1> <listener-config listener-class- name=com.sun.enterprise.admin.notification.MailAlert subscribe-listener-with=LogMBean, ServerStatusMonitor, HeapSizeMonitor > <property name=recipients value="john.doe@abc.com, lab-admin@abc.com" /> <property name=fromAddress value=SJSAS@abc.com /> <property name=subject value="Alert From Application Server" /> <property name=includeDiagnostics value=false /> <property name=mailSMTPHost value=mail-server.abc.com /> </listener-config> <filter-config filter-class-name="com.sun.appserv.management.alert.MailFilter" > <property name=filterWarningMessages value=true /> </filter-config> </alert-subscription> </alert-service>

 

For details on the AMX API, see Chapter 16 of the Sun Java System Application Server Platform Edition 8.1 2005Q1 Developer's Guide.

Summary

The intuitive GUI and scriptable CLI in Application Server make it simple to configure monitoring settings and access monitoring attributes in meticulous detail. Furthermore, with the standard management and monitoring API (JSR 77), you can develop both vendor-neutral clients and a value-added, vendor-specific API (AMX) that simplifies the development process for managing and monitoring clients.

Give it a try!

References

• Sun Java System Application Server
  • Main page
  • Developer home
  • Software Forum
  
  
• Project GlassFish (open-source version of Sun Java System Application Server)
  
  
• J2EE Management Specification (JSR 77)

Rate and Review Tell us what you think of the content of this page. Excellent   Good   Fair   Poor   Comments: Your email address (no reply is possible without an address): Sun Privacy Policy Note: We are not able to respond to all submitted comments.