Previous Contents Index Next |
Sun Java System Application Server 7 2004Q2 Update 1 Standard and Enterprise Edition Administration Guide

> ## Chapter 6
> Monitoring Sun Java System Application Server

> This chapter contains information about the monitoring and Simple Network Management Protocol (SNMP) features and functions available in Sun Java System Application Server.

> This chapter includes the following sections:

> - About Monitoring Sun Java System Application Server
> - Extracting Monitoring Data Using the CLI
> - Administering the Transaction Service Using the CLI
> - Using HTTP Quality of Service
> - About SNMP
> - Setting Up SNMP
> - Enabling and Starting the SNMP Master Agent

> ##

> About Monitoring Sun Java System Application Server

> You can monitor Sun Java System Application Server by collecting activity statistics from strategic data points on your system. The statistics show you how many requests your server is handling and how well it is handling those requests. You can view some statistics for individual virtual servers and others for the entire Sun Java System application server instance. Either the asadmin utility or SNMP can be used to monitor the Sun Java System Application Server.

> The following topics are addressed in this section:

> - Statistics
> - SNMP
> - HTTP Server Monitoring
> - Administration Server Security Auditing
> - Application Components and Subsystems Monitoring
> - Quality of Service (QOS)

> ### Statistics

> Statistics collection is always enabled for most of the Sun Java System Application Server application components and subsystems, including the HTTP server; no enabling functions are required. However, there are some statistics that are collected only when monitoring is explicitly enabled on that subsystem, or only when relevant functionality is enabled. These statistics include the following data points:

> - Statistics for EJB methods
> - Active transactions
> - Connections (only if Quality of Service is enabled)
> - DNS (only if DNS Cache is enabled)

> Monitoring can be enabled for application subsystems or components from the Administration interface, as described in Application Components and Subsystems Monitoring.

> If the server monitor reports that the server is handling a large number of requests, you may need to adjust the server configuration or the system’s network kernel. For more information on adjusting your server’s configuration, see the Sun Java System Application Server Performance Tuning and Sizing Guide.

> ### SNMP

> The Sun Java System Application Server provides network management information through its information gathering tools using Simple Network Management Protocol (SNMP), a protocol used to exchange management and monitoring information across a network. Using SNMP, programs called agents monitor various devices on the network (hubs, routers, bridges, and so on). Another program collects the data from the agents. The database created by the monitoring operations is called a management information base (MIB).This data is used to check if all devices on the network are operating properly.

> While only the HTTP server can be monitored using SNMP; all components and systems can be monitored using the command-line interface (CLI)

> For more information on SNMP, see About SNMP and Setting Up SNMP.

> ### HTTP Server Monitoring

> HTTP server monitoring is enabled by default, which means it doesn’t need to be specifically turned on. HTTP server monitoring is based on an XML file and is accessed using the asadmin command as a set of three monitorable attributes. The elements, subelements, and the attributes of this XML file are described in Monitorable HTTP Server Elements and Monitorable HTTP Server Attributes.

> Note | Only HTTP server statistics are available using SNMP. Statistics for all the subsystems of the Sun Java System Application Server, including the HTTP server, are available using the command-line interface.

> For more information about using asadmin, see Using the Command Line Interface.

> ### Application Components and Subsystems Monitoring

> Some of the subsystems or components within the Sun Java System Application Server do not need to have monitoring enabled because the relevant statistics are always collected. For example, monitoring for application components such as containers can be enabled or disabled. When monitoring is enabled, in addition to the statistics that are always collected, additional statistics on all EJB methods are also collected. Monitoring for JDBC connection pools is always enabled. A connection pool is initialized upon first access and relevant statistics can be monitored anytime after that.

> For a full list of monitorable data points, see Monitorable Attribute Names.

> You can enable monitoring for selected application components and subsystems from the Administration interface or from the command-line interface (CLI). For example, to enable monitoring from the CLI for the EJB container, type the following command from a terminal window:

> set server1.ejb-container.monitoringEnabled=true
> reconfig server1

> where server1 is the instance name.

> The equivalent functionality can be accessed on the Administration interface under the Containers node.

> The following topics are addressed in this section:

> - Monitoring for Container Subsystems
> - Monitoring for the ORB Service
> - Monitoring for the Transaction Service

> #### Monitoring for Container Subsystems

> In the case of the EJB container, when monitoring is enabled, the statistics related to the methods for all entity beans, stateful session beans, and stateless session beans are collected. These statistics include:

> - Total number of errors
> - Total number of calls
> - Total number of successes
> - Execution time, in milliseconds (for last invocation of the method)

> All other statistics for container subsystems are always collected. Some of the monitored data points include statistics relative to:

> - Initial, minimum, and maximum stateless beans in pool
> - Minimum and preferred number of stateful and entity beans in cache
> - Minimum and preferred number of stateless session beans in cache
> - Number of beans created and destroyed
> - Other related statistics

> #### Monitoring for the ORB Service

> For the ORB service, monitored data points include statistics gathered for the ORB connection and the ORB thread pool. ORB statistics are always collected and, therefore, it is not necessary to enable monitoring for the ORB service.

> #### Monitoring for the Transaction Service

> For the Java Transaction Service (JTS) service, monitored data points include:

> - Total completed transactions
> - Total rolled back transactions
> - Total inflight transactions
> - List of inflight transactions

> Refer to Administering the Transaction Service Using the CLI for further information.

> ### Administration Server Security Auditing

> Sun Java System Application Server provides a built in security audit logging service to monitor events that directly modify the configuration of the server.

> The audit logging is implemented within the admin module of Sun Java System Application Server. When the administration server starts up, a global audit session is created and persists until the administration server is stopped.

> To monitor administration-related changes to Application Server instances, you need to perform the following tasks:

> Note | The audit service does not monitor JVM specific configuration settings, the creation or deletion of domains, user-level ACL settings for customer applications, as well as a few other non-critical settings.

> - Configuring Administration Server to Use LDAP
> - Setting Up Audit Services Configuration Files
> - Viewing Security Audit Output

> ### Configuring Administration Server to Use LDAP

> This section describes the procedure to configure user authentication to Application Server administration server using the Lightweight Directory Access Protocol (LDAP).

> 1. Install a LDAP database and create an admin group, to which the Application Server administrators will belong.
> 2. Create one or more LDAP users (who will administer Application Server instances) and add them to the admin group.
> 3. Edit the appserver_install_dir/domain1/admin-server/config/generated.admin-server.acl file. Replace the contents of the file with the following:

> version 3.0;

> acl "admin-defaults";

> authenticate(user, group) {

> method="basic";

> database="default";

> prompt="LDAP user/password";

> };

> deny with file="appserver_install_dir/domains/domain1/admin-server/config/admin-denymsg.html";

> deny (all) user="anyone";

> allow (all) (group = "{ADMIN_GROUP}") );

> 4. Replace {ADMIN_GROUP} with the LDAP admin group to which the admin users belong.
> 5. Edit the appserver_install_dir/domain1/admin-server/config/dbswitch.conf file. Replace the contents of the file with the following:

> directory default ldap://{LDAP_SERVER}:{PORT}/{BASE_DN}

> default:binddn {BIND_DN}

> default:bindpw {BIND_PW}

> For example:

> directory default ldap://drectory.sun.com:1389/o=WebAuth

> default:binddn cn=Directory Manager

> default:bindpw dirmanager

> 6. Edit the appserver_install_dir/domain1/admin-server/config/obj.conf file. Comment out the following line of the default object section:

> PathCheck fn="admin-check-admpw"

> admpwfile="appserver_install_dir/domains/domain1/admin-server/config/admpw" admdns="*" admip="*" final="true"

> 7. Insert the following lines in the default object section, below the PathCheck fn="unix-uri-clean" line:

> PathCheck fn="check-acl" acl="admin-defaults"

> The updated obj.conf should look something like the following:

> <Object name="default">

> AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true"

> NameTrans fn="ntrans-j2ee" name="j2ee"

> NameTrans fn="admin-uri2path" root="/admin"

> #PathCheck fn="admin-check-admpw"

> admpwfile="/var/opt/SUNWappserver7/domains/domain1/admin-server/config/ admpw" admdns="*.iplanet.com" admip="*" final=false

> PathCheck fn=find-pathinfo

> PathCheck fn="unix-uri-clean"

> PathCheck fn="check-acl" acl="admin-defaults"

> PathCheck fn=find-index index-names="index.html"

> ObjectType fn="type-by-extension"

> ObjectType fn="force-type" type="magnus-internal/cgi"

> Service fn="send-cgi" type="magnus-internal/cgi"

> Service fn="imagemap" method="GET" type="magnus-internal/imagemap"

> Service fn="send-file" method="GET"

> Error fn="error-j2ee"

> Error fn="admin-error" reason="server error"

> AddLog fn="flex-log" name="access"

> </Object>

> ### Setting Up Audit Services Configuration Files

> To enable audit logging for the Administration Server, you have to create two configuration files in the following locations:

> - The global configuration file: /etc/defaults/s1asaudit
> - The Application Server instance specific configuration file: appserver_install_dir/s1asaudit

> The location of these two files can be set by using the following environment variables:

> - For the global configuration file: s1asaudit.default.file
> - For Application Server instance specific configuration file: s1asaudit.config.file

> Here’s an example: On Solaris, use the following command:

> setenv s1asaudit.config.file /etc/opt/appserver7/auditconfig

> Configure these two files using the procedures described in Audit Configuration Settings.

> Note | Settings specified in the instance configuration file will override those of the global configuration file.

> #### Audit Configuration Settings

> The global and instance specific configuration files can contain the same settings.However, the instance specific settings will take precedence over the global configuration settings.

> A sample audit configuration file for Solaris is shown here.

> # This configuration file specifies the default audit
> # type and audit session class file for this S1AS installation
> #
> # Syntax:
> # audit.default.type={Audit_Type}
> # audit.{Audit_Type}.class={Audit_Session_Class}
> #
> # Default audit types are: Log and Solaris
> #

> audit.default.type=Solaris

> audit.Log.class=com.iplanet.ias.admin.audit.LogAuditSession

> audit.Solaris.class=com.iplanet.ias.admin.audit.SolarisAuditSession

> At the very minimum, the configuration files should contain a minimum of two entries:

> - The default audit type, and
> - The audit type definition.

> The default audit type entry must match one of the two audit type definitions- Log or Solaris.

> For platforms other than Solaris, set the audit.default.type to Log and remove the audit.Solaris.class line.

> If the configuration file does not exist, or if a default audit type is not specified, security audit events will not be logged by the administration server.

> ### Viewing Security Audit Output

> This section describes the output of the security audit logs and how to view them on different platforms. The following topics are described:

> - Viewing Security Audit Logs on Non-Solaris 9 Platforms
> - Viewing Security Audit Logs Using BSM Auditing on Solaris

> #### Viewing Security Audit Logs on Non-Solaris 9 Platforms

> Security audit logs on non-Solaris 9 platforms, where native BSM auditing is not supported, audit events will be written to the default server log of the administration server instance.

> There following three distinct audit events will be logged:

> Login Event

> Login events are generated at startup of the administration server instance and indicates that an audit session has been created.

> Modify Event

> Modify events correspond to all configuration changes which are audited by the administration server. Each modify event will contain the following data:

> - ObjectName

> ObjectName specifies the configuration item that is being modified.

> - RemoteHost

> RemoteHost specifies the remote host which initiated the request. Due to Application Server restrictions on remote administration, this value will always indicate the localhost.

> - Type

> Type specifies the kind of change that has been made, such as, create, add, delete, and update.

> - Mode

> Mode specifies whether the request originated from the CLI or the admin GUI.

> - Value

> Value specifies the new or modified value of the ObjectName.

> Logout Event

> Logout events are generated at shutdown of the administration server instance and indicates that the audit session has been stopped.

> #### Viewing Security Audit Logs Using BSM Auditing on Solaris

> Us e the following procedure to enable BSM auditing on Solaris:

> 1. Login to the Solaris machine as root.
> 2. Edit the /etc/security/audit_control file.
> 3. Set naflags to lo,ad.
> 4. Enable auditing by executing /etc/security/bsmconv.
> 5. Reboot the Solaris machine.

> Use the command praudit to monitor audit events. Here’s an example:

> tail -f /var/audit/20031219001450.not_terminated.machine1 | praudit

> You should replace the audit filename (20031219001450.not_terminated.machine1) with the name of the audit file created on your local machine.

> ### Quality of Service (QOS)

> Quality of Service refers to the performance limits you set for a server instance virtual server class or virtual server. For example, if you are an Internet Service Provider (ISP), you might want to charge different fees for virtual servers depending on how much bandwidth is provided. You can limit two areas: the amount of bandwidth and the number of connections.

> The Quality of Service information provided by the Sun Java System Application Server is used to determine server efficiency during runtime with respect to:

> - Start-up time
> - Server traffic and effects of traffic upon bandwidth
> - Analysis of live versus static data
> - Other data elements

> For more information, see Administering the Transaction Service Using the CLI.

> ##

> Extracting Monitoring Data Using the CLI

> With the asadmin command, you can extract monitored data through the command-line interface (CLI) using the list and get commands.

> Note | The set command is only used to set monitoring for the transaction service as described in Administering the Transaction Service Using the CLI.

> This section addresses the following topics:

> - list --monitor Command
> - get --monitor Command
> - CLI Name Mapping
> - HTTP Server Monitorable Objects

> ### list --monitor Command

> The list command provides information about the application components and subsystems currently being monitored for the specified server instance name. Using this command, you can see the monitorable components and sub-components for a server instance.

> ##### Example

> asadmin> list --monitor server1

> returns the following list of application components and subsystems that have monitoring enabled:

> iiop-service
> transaction-service
> application.converter
> application.myApp
> http-server

> You can also list applications that are currently monitored in the specified server instance. This can be useful when particular monitoring statistics are sought from an application using the get command.

> ##### Example

> asadmin> list --monitor server1.application

> returns:

> converter
> myApp

> For a more comprehensive example, see Petstore Example.

> ### get --monitor Command

> This command retrieves the following monitored information:

> - All attribute(s) monitored within a component or subsystem
> - Specific attribute monitored within a component or subsystem

> When an attribute is requested that does not exist for a particular component or subsystem, an error is returned. Similarly, when a specific attribute is requested that is not active for a component or subsystem, an error is returned.

> Refer to CLI Name Mapping for more information on the use of the get command.

> ##### Example 1

> Attempt to get all attributes from a subsystem for a specific attribute:

> asadmin> get --monitor server1.iiop-service.orb.system.orb-connection.*

> total-inbound-connections=1
> total-outbound-connections=1

> ##### Example 2

> Attempt to get all attributes from a J2EE application:

> asadmin> get --monitor server1.application.converter.*

> Attribute name(s) not found

> There are no monitorable attributes exposed at the J2EE-application level, therefore the command fails.

> ##### Example 3

> Attempt to get a specific attribute from a subsystem:

> asadmin> get --monitor server1.transaction-service.inflight-tx

> Attribute name = inflight-tx Value = No active transaction found.

> ##### Example 4

> Attempt to get an unknown attribute from within a subsystem attribute:

> asadmin> get --monitor server1.iiop-service.orb.system.orb-connection.bad-name

> Could not get the attribute

> Execution failed for the command: get --monitor server1.iiop-service.orb-connection.bad-name

> ### CLI Name Mapping

> The Sun Java System Application Server uses a tree structure to track monitorable objects. Every node in the tree has a name and a type. If a type is singleton, only a single node of the type can exist under any parent node. For more information on type of nodes in this tree, see Monitorable Object Types.

> The root object in the tree is represented by the Application Server instance name. For example, the root monitoring object for an instance named server1 is:

> server1

> All child objects are then addressed using the dot (.) character as separator. If a child node is of singleton type, then only the monitoring object type is needed to address the object, otherwise a name of the form type.name is needed to address the object.

> For example, http-server is one of the valid monitorable object types and is singleton. To address a singleton child node representing the http-server of instance server1, the name is:

> server1.http-server

> Another example, application, is a valid monitorable object type and is not a singleton. To address a non-singleton child node representing the application Petstore, the name is:

> server1.application.petstore

> The CLI names can also address specific attributes in monitorable objects. For example, http-server has a monitorable attribute called summary. The following name addresses the summary attribute:

> server1.http-server.summary

> There is no fixed naming convention for attribute names exposed by monitoring objects.

> You are not expected to know the valid names for CLI use. The list command lets you inspect available monitorable objects, while the get command used with a wildcard parameter allows you to inspect all available attributes on any monitorable object.

> The following example illustrate some client name mapping scenarios:

> #### Petstore Example

> A user wants to inspect the number of calls made to a method in the Petstore application deployed on the Sun Java System Application Server instance named server1. A combination of the list and get commands is used to access desired statistics on a method.

> 1. Invoke the CLI in multi-mode.
> 2. Set some useful environment variables to avoid entering them for every command:

> asadmin>export AS_ADMIN_USER=admin AS_ADMIN_PASSWORD=admin123

> asadmin>export AS_ADMIN_HOST=localhost AS_ADMIN_PORT=4848

> 3. List monitorable components for instance server1:

> asadmin>list --monitor server1

> Output is:

> iiop-service
> transaction-service
> application.CometEJB
> application.ConverterApp
> application.petstore
> http-server
> resources

> The list of monitorable components includes iiop-service, http-server, transaction-service, resources, and all deployed (and enabled) applications.

> 4. List the monitorable subcomponents in the Petstore application (-m can be used instead of --monitor):

> asadmin>list -m server1.application.petstore

> Output is:

> ejb-module.signon-ejb_jar
> ejb-module.catalog-ejb_jar
> ejb-module.uidgen-ejb_jar
> ejb-module.customer-ejb_jar
> ejb-module.petstore-ejb_jar
> ejb-module.AsyncSenderJAR_jar
> ejb-module.cart-ejb_jar

> 5. List the monitorable subcomponents in the EJB module sigon-ejb_jar of the Petstore application:

> asadmin>list -m server1.application.petstore.ejb-module.signon-ejb_jar

> Output is:

> entity-bean.UserEJB
> stateless-session-bean.SignOnEJB

> 6. List the monitorable subcomponents in the entity bean UserEJB for the EJB module sigon-ejb_jar of the Petstore application:

> asadmin>list -m server1.application.petstore.ejb-module.signon-ejb_jar.entity-bean.UserEJB

> Output is:

> bean-method.create0
> bean-method.findByPrimaryKey1
> bean-method.remove2
> bean-method.getUserName3
> bean-method.setPassword4
> bean-method.getPassword5
> bean-method.matchPassword6
> bean-method.remove7
> bean-method.isIdentical8
> bean-method.getEJBLocalHome9
> bean-method.getPrimaryKey10
> bean-pool
> bean-cache

> 7. List the monitorable subcomponents in the method getUserName3 for the entity bean UserEJB in the EJB module sigon-ejb_jar of the Petstore application:

> asadmin>list -m server1.application.petstore.ejb-module.signon-ejb_jar.entity-bean.UserEJB.bean-method.getUserName3

> Output is:

> No monitorable entities for element
> server1.application.petstore.ejb-module.signon-ejb_jar.entity-bean.UserEJB.bean-method.getUserName3

> 8. There are no monitorable subcomponents for methods. Get all monitorable statistics for the method getUserName3.

> asadmin>get -m server1.application.petstore.ejb-module. signon-ejb_jar.entity-bean.UserEJB.bean-method.getUserName3.*
> method-name = public abstract java.lang.String com.sun.j2ee.blueprints.signon.user.ejb.UserLocal.getUserName()
> total-num-errors = 0
> total-num-success = 2
> execution-time-millis = 1
> total-num-calls = 2

> 9. You can also get a specific statistic, such as execution time.

> asadmin>get -m server1.application.petstore.ejb-module. signon-ejb_jar.entity-bean.UserEJB.bean-method.getUserName3.execution-time-millis
> execution-time-millis = 1

> #### Monitorable Object Types

> The tree of objects used for monitoring contains several nodes. A node is a specific entry in the object tree, and is identified uniquely by its type, name, and parent node. Some of the node types are singleton, meaning that only one node of the type can exist under a parent node. A name is not relevant for a singleton node. A non-singleton type node needs a name.

> The following tree describes the tree structure in terms of possible parent-child relationships among various node types and the namespaces for some of the node types.

> serverInstance
> .application.applicationName
> .ejb-module.moduleName (for x.jar, name is x_jar)
> .stateless-session-bean.beanName
> .bean-pool
> .bean-method.methodName
> .stateful-session-bean.beanName
> .bean-cache
> .bean-method.methodName
> .entity-bean.beanName
> .bean-cache
> .bean-pool
> .bean-method.methodName
> .message-driven-bean.beanName
> .bean-pool
> .bean-method.methodName (methodName = onMessage)
> .http-server
> .process
> .virtual-server
> .iiop-service
> .orb.orbName> (orbName = "system", or userOrbName)
> .orb-connection
> .orb-thread-pool
> .standalone-ejb-module.moduleName
> .stateless-session-bean.beanName
> .bean-pool
> .bean-method.methodName
> .stateful-session-bean.beanName
> .bean-cache
> .bean-method.methodName
> .entity-bean.beanName
> .bean-cache
> .bean-pool
> .bean-method.methodName
> .message-driven-bean.beanName
> .bean-pool
> .bean-method.methodName (methodName = onMessage)
> .transaction-service
> .resources
> .jdbc-connection-pool.poolName

> #### Monitorable Attribute Names

> It is not necessary for every monitorable object to expose monitorable attributes. Some of the objects are used just for grouping other objects. For the Sun Java System Application Server, except for an http-server node, only the leaf nodes of the tree have attributes. The http-server node type has attributes as well as child nodes. The following tables list possible monitorable attribute names for various nodes.

> Table 6-1 http-server

> Attribute Name | Datatype | Description
> --- | --- | ---
> summary | String (Formatted) | HTTP server summary. Includes virtual servers and processes. NOTE: See section HTTP Server Monitorable Objects for more information on what data is exposed in the formatted string.

> Table 6-2 virtual-server

> Attribute Name | Datatype | Description
> --- | --- | ---
> <vs-id> | String (Formatted) | Virtual server information. For every application server instance there can be one or more virtual servers. The list of virtual server IDs can be obtained from the summary attribute of http-server. You can look up statistics for a specific virtual server using the get command parameter of the form server1.http-server.virtual-server.<vs-id>. You can look up statistics for all virtual servers using the get command parameter of the form server1.http-server.virtual-server.*. NOTE: See section HTTP Server Monitorable Objects for more information on what data is exposed in the formatted string.

> Table 6-3 process

> Attribute Name | Datatype | Description
> --- | --- | ---
> <pid> | String (Formatted) | Process information. For every application server instance there is one process. The process ID can be obtained from the summary attribute of http-server. Statistics for a process can be obtained using the parameter of the form server1.http-server.process.<pid> to the get command. NOTE: See section HTTP Server Monitorable Objects for more information on what data is exposed in the formatted string.

> Table 6-4 orb-connection

> Attribute Name | Datatype | Description
> --- | --- | ---
> total-inbound-connections | Integer | Total inbound connections to ORB.
> total-outbound-connections | Integer | Total outbound connections from ORB.

> Table 6-5 orb-thread-pool

> Attribute Name | Datatype | Description
> --- | --- | ---
> thread-pool-size | Integer | Total number of threads in ORB thread pool.
> waiting-thread-count | Integer | Number of thread pool threads waiting for work to arrive.

> Table 6-6 jdbc-connection-pool

> Attribute Name | Datatype | Description
> --- | --- | ---
> total-threads-waiting | Integer | Total threads waiting for JDBC connection.
> total-outbound-connections | Integer | Total JDBC connection validation failures.
> total-connections-timed-out | Integer | Total connection requests timed out.

> Table 6-7 transaction-service

> Attribute Name | Datatype | Description
> --- | --- | ---
> total-tx-completed | Integer | Total completed transactions.
> total-tx-rolled-back | Integer | Total rolled back transactions.
> total-tx-inflight | Integer | Total inflight (live) transactions.
> isFrozen | String | Is transaction system frozen (true or false)?
> inflight-tx | String (Formatted) | List of inflight transactions.

> Table 6-8 bean-pool

> Attribute Name | Datatype | Description
> --- | --- | ---
> max-pool-size | Integer | The maximum number of bean instances in the pool.
> steady-pool-size | Integer | The number of bean instances normally maintained in the pool. When a pool is first created, it will be populated with a size equal to steady-pool-size. When an instance is removed from the pool, it is replenished asynchronously, so that the pool size is at, or above, steady-pool-size.
> pool-resize-quantity | Integer | The increment by which pool grows up to max-pool-size or shrinks to steady-pool-size
> idle-timeout-in-seconds | Integer | Defines the rate at which the pool cleaning thread is executed. Checks if the current size is greater than the steady pool size and removes the pool-resize-quantity elements. If the current size is less than steady-pool-size, it is increased by pool-resize-quantity, with a ceiling of min (current-pool-size + pool-resize-quantity, max-pool-size). Only objects that have not been accessed for more than pool-idle-timeout-in-seconds are candidates for removal
> num-beans-in-pool | Integer | Number of beans available in pool.
> num-threads-waiting | Integer | Number of threads waiting for free beans.
> total-beans-created | Integer | Number of beans created so far.
> total-beans-destroyed | Integer | Number of beans destroyed so far.
> jms-max-messages-load | Integer | The maximum number of messages to load into a JMS session at one time for a message-driven bean to serve. Default is 1. Applies only to pools for message driven beans.

> Table 6-9 bean-cache

> Attribute Name | Datatype | Description
> --- | --- | ---
> cache-resize-quantity (resize-quantity) | Integer | The quantity by which the cache size is reduced when the number of beans in cache equals max-cache-size (that is, when cache overflow occurs.)
> cache-misses | Integer | The number of times a user request did not find a bean in the cache.
> idle-timeout-in-seconds | Integer | Rate at which the cache cleaner thread is scheduled. This cleaner thread examines all beans in the cache and passivates those beans that are not accessed for cache-idle-timeout-in-seconds.
> cache-hits | Integer | The number of times a user request found an entry in the cache.
> total-beans-in-cache | Integer | The number of beans in the cache. This is the current size of the cache.
> max-beans-in-cache | Integer | Maximum number of beans that can be held in the cache beyond which cache overflow occurs.
> num-passivations | Integer | Number of passivations. Applies only to stateful session beans.
> num-passivation-errors | Integer | Number of errors during passivation. Applies only to stateful session beans.
> num-expired-sessions-removed | Integer | Number of expired sessions removed by the cleanup thread. Applies only to stateful session beans.
> num-passivation-success | Integer | Number of times passivation completed successfully. Applies only to stateful session beans.

> Table 6-10 bean-method

> Attribute Name | Datatype | Description
> --- | --- | ---
> method-name | String | Fully qualified name of the method.
> total-num-calls | Integer | Number of times the method has been invoked. This is collected for stateless and stateful session beans and entity beans if monitoring enabled is true for EJB container, and for message-driven beans if monitoring is enabled for the message-driven bean container.
> total-num-errors | Integer | Number of times the method execution resulted in an exception. This is collected for stateless and stateful session beans and entity beans if monitoring is enabled under EJB settings, and for message-driven beans if monitoring is enabled under MDB settings.
> total-num-success | Integer | Number of times the method successfully executed. This is collected for stateless and stateful session beans and entity beans if monitoring enabled is true for EJB container, and for message-driven beans if monitoring is enabled for the container.
> execution-time-millis | Long | Time spent executing the method for the last successful run of this method. This is collected for stateless and stateful session beans and entity beans if monitoring is enabled on the EJB container and for message-driven beans if monitoring is enabled on the container.

> ### HTTP Server Monitorable Objects

> The HTTP server monitorable attribute name summary prints the attribute values of the Server element and a summary of its subelements, including the number of each subelement and attribute values for each subelement. The HTTP server virtual-server attribute prints the attribute values of the VirtualServer element and the details of each of its subelements.The process attribute prints the attribute values of the Process element and the details of each of its subelements.

> To enable NSAPI performance profiling and obtain statistics on the Profile and ProfileBucket elements, see the Sun Java System Application Server Developer's Guide to NSAPI.

> For information on how to use the monitoring statistics for performance tuning, see the Sun Java System Application Server Performance and Tuning Guide.

> #### Monitorable HTTP Server Elements

> The following table lists the HTTP server monitorable elements.

> Table 6-11 Monitorable HTTP Server Elements

> Element Name | Subelements | Description
> --- | --- | ---
> Server | ConnectionQueue ThreadPool Profile Process VirtualServer | A server instance.
> ConnectionQueue | None | The queue in which requests are held prior to being serviced. There is only one connection queue in Sun Java System Application Server.
> ThreadPool | None | A thread pool, as defined in the init.conf file.
> Profile | None | An NSAPI performance profile bucket, as defined in the init.conf file.
> Process | ConnectionQueueBucketThreadPoolBucket DnsBucket DnsBucket KeepaliveBucket CacheBucket Thread | A single server process within a server instance.
> ConnectionQueueBucket | None | Tracks statistics pertaining to a specific ConnectionQueue.
> ThreadPoolBucket | ThreadPoolBucket | Tracks statistics pertaining to a specific ThreadPool.
> DnsBucket | None | Tracks DNS statistics.
> KeepaliveBucket | None | Tracks keepalive (persistent connection) statistics.
> CacheBucket | None | Tracks file cache (NSFC) statistics.
> Thread | RequestBucket ProfileBucket | Describes a request processing thread.
> VirtualServer | RequestBucket ProfileBucket | Describes a virtual server.
> RequestBucket | None | Tracks request-related statistics.
> ProfileBucket |  | Tracks statistics pertaining to a Profile element.

> #### Monitorable HTTP Server Attributes

> The following tables list the HTTP server monitorable attributes.

> Table 6-12 Server

> Attribute Name | Values | Description
> --- | --- | ---
> Id |  | The server instance ID (for example, server1).
> VersionServer |  | A string that contains the Sun Java System Application Server version.
> TimeStarted | GMT | The time this server instance was started.
> SecondsRunning |  | The number of seconds since this server instance started.
> TicksPerSecond |  | The number of ticks in a second. This value is system-dependent.
> MaxProcs |  | The maximum number of processes.
> MaxThreads |  | The maximum number of processing threads.
> MaxVirtualServers |  | The maximum number of virtual servers tracked.
> FlagProfilingEnabled | 0 (off), 1 (on) | Indicates whether NSAPI performance profiling is enabled (on).
> FlagVirtualServerOverflow | 0 (no), 1 (yes) | Indicates whether more than MaxVirtualServers are configured (yes). If this attribute is set to 1, statistics are not being tracked for all virtual servers.
> LoadMinuteAverage |  | Average load in 1 minute.
> Load5MinuteAverage |  | Average load in 5 minutes.
> Load15MinuteAverage |  | Average load in 15 minutes.
> RateBytesTransmitted | bytes per second | The rate at which data is transmitted over some server-defined interval, or 0 if this information is not available.
> RateBytesReceived | bytes per second | The rate at which data is received over some server-defined interval, or 0 if this information is not available.

> Table 6-13 ConnectionQueue

> Attribute Name | Values | Description
> --- | --- | ---
> Id |  | The connection queue ID.

> Table 6-14 ThreadPool

> Attribute Name | Values | Description
> --- | --- | ---
> Id |  | The thread pool ID.
> Name |  | The symbolic name of the thread pool.

> Table 6-15 Profile

> Attribute Name | Values | Description
> --- | --- | ---
> Id |  | The NSAPI performance profile bucket ID.
> Name |  | The symbolic name of the NSAPI performance profile bucket.
> Description |  | The description of the NSAPI performance profile bucket.

> Table 6-16 Process

> Attribute Name | Values | Description
> --- | --- | ---
> Pid |  | The operating system process identifier that uniquely identifies this process.
> Mode | unknown active | Displays active when this process is active.
> TimeStarted | GMT | The time this process was started.
> CountConfigurations |  | The number of times a configuration has been loaded, or 0 if this information is not available.
> SizeVirtual | kilobytes | The size of virtual memory used by this process.
> SizeResident | kilobytes | The size of the resident memory used by this process.
> FractionSystemMemoryUsage |  | Fraction of system memory used by this process.

> Table 6-17 ConnectionQueueBucket

> Attribute Name | Values | Description
> --- | --- | ---
> ConnectionQueue |  | The ID of a ConnectionQueue element.
> CountTotalConnection |  | The total number of new connections that have been accepted.
> CountQueued |  | The number of connections currently enqueued.
> PeakQueued |  | The largest number of connections that have been in the queue simultaneously.
> MaxQueued |  | The maximum number of connections that can be in the queue.
> CountOverflow |  | The number of times the queue has been too full to accommodate a connection.
> CountTotalQueued |  | The total number of connections that have been queued. A given connection may be queued multiple times, so CountTotalQueued may be greater than or equal to CountTotalConnections.
> TicksTotalQueued |  | The total number of ticks that connections have spent in the queue. A tick is a system-dependent unit of time; see TicksPerSecond.

> Table 6-18 ThreadPoolBucket

> Attribute Name | Values | Description
> --- | --- | ---
> Thread-pool |  | The ID of a ThreadPool element.
> CountThreadsIdle |  | The number of request processing threads currently idle.
> CountThreads |  | The number of request processing threads.
> MaxThreads |  | The maximum number of request processing threads that can exist concurrently.
> CountQueued |  | The number of requests queued for processing by this thread pool.
> PeakQueued |  | The largest number of requests that have been in the queue simultaneously.
> MaxQueued |  | The maximum number of requests that can be in the queue.

> Table 6-19 DnsBucket

> Attribute Name | Values | Description
> --- | --- | ---
> FlagCacheEnabled | 0 (off), 1 (on) | Indicates whether the DNS cache is enabled (on).
> CountCacheEntries |  | The number of DNS entries presently in the cache.
> MaxCacheEntries |  | The maximum number of DNS entries the cache can accommodate.
> CountCacheHits |  | The number of times a DNS cache lookup has succeeded.
> CountCacheMisses |  | The number of times a DNS cache lookup has failed.
> FlagAsyncEnabled | 0 (off), 1 (on) | Indicates whether asynchronous DNS lookups are enabled (on).
> CountAsyncNameLookups |  | The total number of asynchronous DNS name lookups performed.
> CountAsyncAddrLookups |  | The total number of asynchronous DNS address lookups performed.
> CountAsyncLookupsInProgress |  | The total number of asynchronous DNS lookups currently in progress.

> Table 6-20 KeepaliveBucket

> Attribute Name | Values | Description
> --- | --- | ---
> CountConnections |  | The number of connections currently in keepalive mode.
> MaxConnections |  | The maximum number of simultaneous keepalive connections.
> CountHits |  | The total number of times connections in keepalive mode have subsequently made a valid request.
> CountFlushes |  | The number of times keepalive connections have been closed by the server.
> CountTimeouts |  | The number of times keepalive connections have timed out.
> SecondsTimeouts |  | The number of seconds before the server closes an idle keepalive connection.
> CountRefusals |  | The number of times keepalive connections have been refused by the server.

> Table 6-21 CacheBucket

> Attribute Name | Values | Description
> --- | --- | ---
> FlagEnabled | 0 (off), 1 (on) | Indicates whether the file cache is enabled (on).
> SecondsMaxAge | Number of seconds | The maximum age of a file cache entry.
> CountEntries |  | The number of entries currently in the file cache.
> MaxEntries |  | The maximum number of cache entries the file cache can accommodate simultaneously.
> CountOpenEntries |  | The number of entries associated with an open file.
> MaxOpenEntries |  | The maximum number of cache entries associated with an open file that the file cache can accommodate simultaneously.
> SizeHeapCache | Number of bytes | The amount of heap used by cached file content.
> MaxHeapCacheSize | Number of bytes | The maximum amount of heap the file cache uses for cached file content.
> SizeMmapCache | Number of bytes | The amount of address space used by memory mapped file content.
> MaxMmapCacheSize | Number of bytes | The maximum amount of address space that the file cache uses for memory mapped file content.
> CountHits |  | The number of times a cache entry lookup has succeeded.
> CountMisses |  | The number of times a cache entry lookup has failed.
> CountInfoHits |  | The number of times a file information lookup has succeeded.
> CountInfoMisses |  | The number of times a file information lookup has failed.
> CountContentHits |  | The number of times a content lookup has succeeded.
> CountContentMisses |  | The number of times a content lookup has failed.

> Table 6-22 Thread

> Attribute Name | Values | Description
> --- | --- | ---
> Mode | unknown, idle, DNS, request, processing, response, updating | The thread's last known status.
> TimeStarted | GMT | The time this thread was started.
> ConnectionQueue |  | The ID of the ConnectionQueue the thread is servicing.

> Table 6-23 VirtualServer

> Attribute Name | Values | Description
> --- | --- | ---
> Id |  | The virtual server ID.
> Mode | unknown, active | Displays active when this virtual server is active.
> Hosts |  | The software virtual server hostnames serviced by this virtual server (for example, www.foo.com foo.com foo.isp.com).
> Interfaces |  | The interfaces (listeners) the virtual server is configured for (for example, 192.168.1.2:80 192.168.1.2:443).

> Table 6-24 RequestBucket

> Attribute Name | Values | Description
> --- | --- | ---
> CountRequests |  | The number of requests serviced.
> CountBytesReceived |  | The number of bytes received, or 0 if this information is not available.
> CountBytesTransmitted |  | The number of bytes transmitted, or 0 if this information is not available.
> RateBytesTransmitted | bytes per second | The rate at which data was transmitted over some server-defined interval, or 0 if this information is not available.
> MaxByteTransmissionRate |  | The maximum rate at which data was transmitted over some server-defined interval, or 0 if this information is not available.
> CountOpenConnections |  | The number of open connections, or 0 if this information is not available.
> MaxOpenConnections |  | The maximum number of open connections, or 0 if this information is not available.
> Count2xx |  | The number of 200-level responses sent.
> Count3xx |  | The number of 300-level responses sent.
> Count4xx |  | The number of 400-level responses sent.
> Count5xx |  | The number of 500-level responses sent.
> CountOther |  | The number of responses sent that were not 200, 300, 400, or 500 level.
> Count200 |  | The number of 200-level responses sent.
> Count302 |  | The number of 302-level responses sent.
> Count304 |  | The number of 304-level responses sent.
> Count400 |  | The number of 400-level responses sent.
> Count401 |  | The number of 401-level responses sent.
> Count403 |  | The number of 403-level responses sent.
> Count404 |  | The number of 404-level responses sent.
> Count503 |  | The number of 503-level responses sent.

> Table 6-25 ProfileBucket

> Attribute Name | Values | Description
> --- | --- | ---
> Profile |  | The ID of a Profile element.
> Countcalls |  | The number of calls to NSAPI SAFs.
> CountRequests |  | The number of requests processed.
> TicksDispatch |  | The number of ticks spent dispatching requests. A tick is a system-dependent unit of time; see TicksPerSecond.
> TicksFunction |  | The number of ticks spent in NSAPI SAFs. A tick is a system-dependent unit of time; see TicksPerSecond.

> ##

> Administering the Transaction Service Using the CLI

> You can use the set command to administer the statistics you want to monitor for the JTS.

> ##### Example 1

> To add a transaction to a rollback list (which results in rollback or specified transaction), issue the set command as follows:

> set --monitor server1.transaction-service.rollback-list=txnid1

> ##### Example 2

> To freeze the transaction service, issue the set command as follows:

> set --monitor server1.transaction-service.freeze=true

> The attributes that you can monitor can be set from the command line according to the rules described in CLI Name Mapping.

> For more information on the java transaction service, refer to Chapter 8, "Using Transaction Services."

> ##

> Using HTTP Quality of Service

> The following settings govern how traffic is counted and how often the bandwidth is recomputed:

> - Recompute interval—Indicates how often (in milliseconds) the bandwidth is computed.
> - Metric interval—The period of time for which data is used in traffic calculations.

> In the Administration interface, you can enable these server or class-level settings for the server instance or for a class of virtual servers. However, you can override them for an individual virtual server.

> This section includes the following topics:

> - Quality of Service Example
> - Configuring Quality of Service (QOS)
> - Required Changes to the obj.conf File
> - Known Limitations to Quality of Service

> ### Quality of Service Example

> The following example shows how the Quality of Service information is collected and computed.

> - The server has metric interval of 30 seconds.
> - The server starts up at a time of 0 seconds.
> - At 1 second, an HTTP connection generates 5000 bytes of traffic to/from the server.
> - No more connections are made after that. At 30 seconds, the total traffic for the last 30 seconds is 5000 bytes.
> - At 32 seconds, the traffic sample from 1 second is discarded, since it is older than the 30 seconds of the metric interval. The total traffic for the last 30 seconds is now 0.

> The recompute interval works similarly. The server’s recompute interval is 100ms.

> Continuing with the example, the bandwidth is recomputed periodically every 100 milliseconds. The calculation is based on the amount of traffic as well as the metric interval.

> - At 0 seconds, the bandwidth is calculated for the first time. The total traffic is zero, divided by the metric interval of 30 seconds, giving a bandwidth of zero.
> - At 1 second, the bandwidth is calculated for the 10th time (1000 milliseconds/ 100 milliseconds). The total traffic is 5000 bytes, which is divided by 30 seconds. The bandwidth is 5000/30 = 166 bytes per second.
> - At 30 seconds, the bandwidth is calculated for the 300th time. The total traffic is 5000 bytes, which is divided by 30 seconds. The bandwidth is 5000/30 = 166 bytes per second.
> - At 32 seconds, the bandwidth is computed again for the 320th time. The traffic is now 0 (since the one connection that generated traffic is too old to be counted), divided by 30, giving a bandwidth of 0 bytes/second.

> ### Configuring Quality of Service (QOS)

> Quality of Service for a server instance or a class of virtual servers is configured through the Administration interface.

> Note | To enforce your Quality of Service settings, you must also set up Server Application Functions (SAFs) in the obj.conf file as described in Required Changes to the obj.conf File.

> To configure Quality of Service, follow these steps:

> 1. Select the App Server Instances node in the left pane.
> 2. Expand the server instance node to display the HTTP Server node.
> 3. Click the HTTP Server node to display the QOS tab.
> 4. Click the QOS tab.

> A page displays the general settings for Quality of Service, followed by a properties button.

> 5. To enable Quality of Service for this HTTP Server, click QOS Enable.

> Note: By default, Quality of Service is disabled. Enabling Quality of Service slightly increases server overhead.

> 6. Specify the QOS Metrics Interval.

> The metrics interval is the time period, in seconds, that data is sampled during server traffic calculations. The default value is 30 seconds.

> If your site commonly has large file transfers, use a large value (several minutes or more) for this field. A large file transfer might take up all the allowed bandwidth for a short metric interval, and result in connections being denied if you’ve enforced the maximum bandwidth setting. Since the bandwidth is averaged by the metric interval, a longer interval smooths out spikes caused by large files.

> If the bandwidth limit is much lower than available bandwidth (for example, 1 MB-per-second bandwidth limit but with a 1 GB-per-second connection to the backbone), the metric interval should be shortened.

> Note: If you have large static file transfers and a bandwidth limit that is much lower than the available bandwidth, you must decide which situation to tune for, since the problems require opposite solutions.

> 7. Specify the QOS Recompute Time Interval.

> The recompute time interval is the number of milliseconds between each computation of the bandwidth for all servers, classes, and virtual servers. The default is 100 milliseconds.

> 8. Specify the Bandwidth Limit.

> This is the maximum bandwidth limit for the server instance in bytes per second. It is interdependent with the QOS Metrics Interval to some extent.

> 9. Choose whether or not to enforce the maximum bandwidth setting.

> If you choose to enforce the maximum bandwidth, when the server reaches its bandwidth limit, additional connections are refused.

> If you do not enforce the maximum bandwidth, when the maximum is exceeded, the server logs a message to the event log.

> 10. Specify the connection limit.

> This is the number of concurrent requests processed.

> 11. Choose whether or not to enforce the connection limit setting.

> If you choose to enforce the maximum connections, when the server reaches its limit, additional connections are refused. If you do not enforce the maximum connections, when the maximum is exceeded, the server logs a message to the event log.

> 12. (Optional). If specifying additional name-value pair attributes for Quality of Service, click the Properties button.

> For a list of allowed name-value pairs for Quality of Service properties, refer to the online help.

> 13. Click Save to commit the changes to the server instance.
> 14. Access App Server Instances and your server instance in the left pane, then click Apply Changes.

> ### Required Changes to the obj.conf File

> To enforce Quality of Service, you must include directives in your obj.conf file to invoke following Server Application Functions (SAFs):

> - AuthTrans qos-handler
> - Error qos-error

> In order to work properly, the qos-handler AuthTrans directive must be the first AuthTrans configured in the default object. The role of the Quality of Service handler is to examine the current statistics for the virtual server, virtual server class, and global server, and to enforce the limits by returning an error. The Sun Java System Application Server includes a built-in sample Quality of Service handler SAF, called qos-handler. This SAF logs when limits are reached, and returns a 503 Server busy error to the server so that it can be processed by the NSAPI.

> The Sun Java System Application Server also includes a built-in sample error SAF called qos-error which returns an error page stating which limits caused the 503 error and the value of the statistic that triggered the limit.

> For more information on these SAFs and how to use them, see the Sun Java System Application Server Developer’s Guide to NSAPI.

> ### Known Limitations to Quality of Service

> When you use the Quality of Service features, keep in mind the following limitations:

> - The Quality of Service features only measure the HTTP bandwidth at the application level. The HTTP bandwidth can differ from the actual TCP network bandwidth for a variety of reasons:
> - If SSL is enabled, handshakes and client certificate exchanges add to the traffic but are not measured.
> - If chunked encoding is enabled in either or both directions, the chunking layer removes the chunk headers and they are not counted in the traffic. Other headers or protocol items are counted.
> - The Quality of Service features cannot accurately measure traffic from PR_TransmitFile calls. For basic I/O operations such as PR_Send()/net_write or PR_Recv()/net_read, the data transferred can be quickly accounted for by the bandwidth manager, since the number of bytes transferred in one system call is usually the size of a buffer and the I/O call returns quickly. This works very well to measure the instantaneous bandwidth of dynamic content applications. However, because the amount of data transferred from PR_TransmitFile is only known at the end of the transfer, it can’t be measured before it completes.

> If the PR_TransmitFile is short, then the Quality of Service features will perform adequately. However, If the PR_TransmitFile is long, as in the case of a long file downloaded by a dialup user, the whole amount of data transferred will be counted at completion time. When the bandwidth manager recomputes bandwidth after the next recompute interval period starts, the bandwidth computed will increase significantly because of that recent large PR_TransmitFile. This case could cause the server to deny all requests until the next metric interval, when the bandwidth manager will "expire" the transmit file operation (since it is too old) and thus the bandwidth value will go back down. If your site commonly has very long static file downloads, you should increase the metric interval from the default 30 seconds.

> - The bandwidth computed is always an approximation because it is not measured instantaneously, but is recomputed at regular intervals and over a certain period. For example, if the metric interval is the default 30 seconds and the server is idle for 29 seconds, then the next second, a client could potentially use 30 times the bandwidth limit in one second.
> - The Quality of Service bandwidth statistics are lost whenever the server is reconfigured dynamically. In addition, the Quality of Service limitations are not enforced in threads that have connections on an older, inactive configuration, because the bandwidth manager thread only computes bandwidth statistics for the active configuration. Potentially, a client that doesn’t close its socket for a long time and remains active so that the server doesn’t time it out would not be subject to the Quality of Service limitations after a dynamic server reconfiguration.
> - The concurrent connections are computed with a different granularity for virtual servers than for virtual server classes and the global server instance. The connection counter for an individual virtual server is incremented atomically immediately after the request is parsed and routed to the virtual server. It is also decremented atomically at the end of the response processing for that request. This means that the virtual server connection statistics are always exact at any instant.

> However, the connection statistics for the virtual server class and global server instance are not updated instantly. They are updated by the bandwidth manager thread every recompute interval. The connection count for the virtual server class is the sum of the connections on all virtual servers of that class; and the global server instance connection count is the sum of connections on all virtual server classes.

> Because of the way these values are computed, the number of connections for a virtual server is always correct, and if you’ve enforced a limit to the number of connections, you can never have more than the limit. The virtual server class and server instance values are not quite as accurate, since they are only computed at intervals.

> ##

> About SNMP

> Simple Network Management Protocol (SNMP) is a protocol used to exchange management and monitoring information across a network. With SNMP, data travels between a managed device and a network management station (NMS). A managed device is anything that runs SNMP: hosts, routers, your HTTP server, and other servers on your network.

> This section addresses the following topics:

> - Network Management Station (NMS)
> - Management Information Base (MIB) Objects
> - SNMP Messages
> - SNMP Trap Destinations
> - SNMP Agent Community

> ### Network Management Station (NMS)

> The network management station (NMS) is a machine used to remotely manage a specific network. Usually, the NMS software will provide a graph to display collected data or use that data to make sure the server is operating within a particular tolerance.

> The NMS is usually a powerful workstation with one or more network management applications installed. A network management application such as HP OpenView graphically shows information about managed devices, such as your HTTP servers. For example, it might show which servers in your enterprise are up or down, or the number and type of error messages received. When you use SNMP with the Sun Java System Application Server, this information is transferred between the NMS and the server through the use of two types of agents: the subagent and the master agent.

> The subagent gathers information about the server instances running in various domains and passes the information to the master agent. There is a master agent and a subagent for every installation of the Sun Java System Application Server.

> Note | After making any SNMP configuration changes, you must click the Apply button, then restart the SNMP subagent.

> The master agent exchanges information between the various subagents and the NMS. The master agent is installed with the Sun Java System Application Server.

> You can have multiple subagents installed on a host computer, but only one master agent. For example, if you had Sun ONE Directory Server, Sun Java System Application Server, and the Sun ONE Messaging Server installed on the same host, the subagents for each of the servers would communicate with the same master agent.

> The NMS either requests information from the server or changes the value of a variable store in the server’s MIB. For example:

> 1. The NMS sends a message to the Admin Server master agent. The message might be a request for data (a GET message), or an instruction to set a variable in the MIB (a SET message).
> 2. The master agent forwards the message to the appropriate subagent.
> 3. The subagent retrieves the data or changes the variable in the MIB.
> 4. The subagent reports data or status to the master agent, then the master agent forwards the message back (a GET message) to the NMS.
> 5. The NMS displays the data textually or graphically through its network management application.

> ### Management Information Base (MIB) Objects

> The Sun Java System Application Server stores variables pertaining to managing and monitoring information across a network. Variables the master agent can access are called managed objects. These objects are defined in a tree-like structure called the management information base (MIB). The MIB provides access to the HTTP server’s network configuration, status, and statistics. Using SNMP, you can view this information from the network management workstation (NMS).

> The top level of the MIB tree shows that the internet object identifier has the following subtrees:

> - directory (1)
> - mgmt (2)
> - experimental (3)
> - private (4)

> The private (4) subtree contains the enterprises (1) node. Each subtree in the enterprises (1) node is assigned to an individual enterprise, which is an organization that has registered its own specific MIB extensions. An enterprise can then create product-specific subtrees under its subtree. MIBs created by companies are located under the enterprises (1) node.

> Each Sun Java System Application Server subagent provides a MIB for use in SNMP communication. The server reports significant events to the NMS by sending messages or traps containing these variables. The NMS can query the server's MIB for data.

> Each Sun Java System Application Server has its own MIB located at install_dir/lib

> The Sun Java System Application Server’s MIB is a file called appserv.mib. This MIB contains the definitions for various variables pertaining to network management for the Sun Java System Application Server.

> The Sun Java System Application Server MIB has an object identifier of

> appserver 1 (as appserver7 OBJECT IDENTIFIER ::= {appserver 1 }) and is located in the install_dir/lib directory.

> You can see administrative information about your Sun Java System Application Server and monitor the server in real time using the Sun Java System Application Server MIB. The following table lists and describes the managed objects stored in the appserv.mib file.

> Table 6-26 appserv.mib Managed Objects and Descriptions

> Managed object | Description
> --- | ---
> iwsCpuID | CPU identifier.
> iwsCpuIdleTime | Idle CPU time.
> iwsCpuKernelTime | CPU kernel time.
> iwsCpuTable | Application Server CPUs.
> iwsCpuUserTime | CPU user time.
> iwsInstanceTable | Application Server instances.
> iwsInstanceId | Server instance identifier
> iwsInstanceVersion | String, such as SunONE-ApplicationServer-Enterprise/7 BB1-01/24/2001 17:15 (SunOS DOMESTIC)
> iwsInstanceDescription | Description of the server instance.
> iwsInstanceOrganization | Organization responsible for the server instance.
> iwsInstanceContact | Contact information for person(s) responsible for server instance.
> iwsInstanceLocation | Where the server is located.
> iwsInstanceStatus | Status of the server instance.
> iwsInstanceUptime | How long the server has been running.
> iwsInstanceDeathCount | Number of times server instance processes have gone down.
> iwsInstanceRequests | Number of requests processed by the server instance.
> iwsInstanceInOctets | Number of octets received by the server instance. Will show 0 if information is not available.
> iwsInstanceOutOctets | Number of octets transmitted by the server instance. Will show 0 if information is not available.
> iwsInstanceCount2xx | Number of 200-level (Successful) responses issued by the server instance.
> iwsInstanceCount3xx | Number of 300-level (Redirection) responses issued by the server instance.
> iwsInstanceCount4xx | Number of 400-level (Client Error) responses issued by the server instance.
> iwsInstanceCount5xx | Number of 500-level (Server Error) responses issued by the server instance.
> iwsInstanceCountOther | Number of other (neither 2xx, 3xx, 4xx, nor 5xx) responses issued by the server instance.
> iwsInstanceCount200 | Number of 200 (OK) responses issued by the server instance.
> iwsInstanceCount302 | Number of 302 (Moved Temporarily) responses issued by the server instance.
> iwsInstanceCount304 | Number of 304 (Not Modified) responses issued by the server instance.
> iwsInstanceCount400 | Number of 400 (Bad Request) responses issued by the server instance.
> iwsInstanceCount401 | Number of 401 (Unauthorized) responses issued by the server instance.
> iwsInstanceCount403 | Number of 403 (Forbidden) responses issued by the server instance.
> iwsInstanceCount404 | Number of 404 (Not Found) responses issued by the server instance.
> iwsInstanceLoad1MinuteAverage | 1 minute load average of the system running the server instance.
> iwsInstanceLoad5MinuteAverage | 5 minute load average of the system running the server instance.
> iwsInstanceLoad15MinuteAverage | 15 minute load average of the system running the server instance.
> iwsInstanceNetworkInOctets | Number of octets transmitted on the network per second.
> iwsInstanceNetworkOutOctets | Number of octets received on the network per second.
> iwsVsTable | Server virtual servers.
> iwsVsId | Virtual server identifier.
> iwsVsRequests | Number of requests processed by the virtual server.
> iwsVsInOctets | Number of octets received by the virtual server.
> iwsVsOutOctets | Number of octets transmitted by the virtual server.
> iwsVsCount2xx | Number of 200-level (Successful) responses issued by the virtual server.
> iwsVsCount3xx | Number of 300-level (Redirection) responses issued by the virtual server.
> iwsVsCount4xx | Number of 400-level (Client Error) responses issued by the virtual server.
> iwsVsCount5xx | Number of 500-level (Server Error) responses issued by the virtual server.
> iwsVsCountOther | Number of other (neither 2xx, 3xx, 4xx, nor 5xx) responses issued by the virtual server.
> iwsVsCount200 | Number of 200 (OK) responses issued by the virtual server.
> iwsVsCount302 | Number of 302 (Moved Temporarily) responses issued by the virtual server.
> iwsVsCount304 | Number of 304 (Not Modified) responses issued by the virtual server.
> iwsVsCount400 | Number of 400 (Bad Request) responses issued by the virtual server.
> iwsVsCount401 | Number of 401 (Unauthorized) responses issued by the virtual server.
> iwsVsCount403 | Number of 403 (Forbidden) responses issued by the virtual server.
> iwsVsCount404 | Number of 404 (Not Found) responses issued by the virtual server.
> iwsProcessTable | Application Server processes.
> iwsProcessId | Operating system process identifier.
> iwsProcessThreadCount | Number of request processing threads.
> iwsProcessThreadIdle | Number of request processing threads currently idle.
> iwsProcessConnectionQueueCount | Number of connections currently in connection queue.
> iwsProcessConnectionQueuePeak | Largest number of connections that have been queued simultaneously.
> iwsProcessConnectionQueueMax | Maximum number of connections allowed in connection queue.
> iwsProcessConnectionQueueTotal | Number of connections that have been accepted.
> iwsProcessConnectionQueueOverflows | Number of connections rejected due to connection queue overflow.
> iwsProcessKeepaliveCount | Number of connections currently in keepalive queue.
> iwsProcessKeepaliveMax | Maximum number of connections allowed in keepalive queue.
> iwsProcessSizeVirtual | Process size in kilobytes.
> iwsProcessSizeResident | Process resident size in kilobytes.
> iwsProcessFractionSystemMemoryUsage | Fraction of process memory in system memory.
> iwsListenTable | Application Server listen sockets.
> iwsListenId | Listen socket identifier.
> iwsListenAddress | Address where socket listens.
> iwsListenPort | Port where socket listens.
> iwsListenSecurity | Encryption support.
> iwsThreadPoolCount | Number of requests denied.
> iwsThreadPoolMax | Maximum number of requests allowed in queue.
> iwsThreadPoolPeak | Largest number of requests that have been queued simultaneously.
> iwsThreadPoolTable | Application Server thread pools.
> iwsVsCount503 | Number of 503 (Unavailable) responses issued.
> iwsInstanceCount503 | Number of 503 (Unavailable) responses issued.

> ### SNMP Messages

> GET and SET are two types of messages defined by SNMP.

> Each object is assigned a unique identifier within the MIB. Objects are accessed by the SNMP Manager by issuing GET and GETNEXT commands which specify the object's unique identifier. The Proxy Agent obtains the value of the specified object and transmits it to the SNMP manager. Events added to the log may generate SNMP traps provided they satisfy trap filter conditions. Events that do not generate traps are merely recorded as an entry in the maintenance log table and are accessed by the SNMP Manager through normal GET and GETNEXT commands.

> GET and SET messages are sent by a network management station (NMS) to a master agent. You can use one or the other, or both, through the Administration interface.

> SNMP exchanges network information in the form of protocol data units (PDUs). These units contain information about variables stored on the managed device, such as the HTTP server. These variables, also known as managed objects, have values and titles that are reported to the NMS as necessary. Protocol data units sent by the server to the NMS are known as traps. The use of GET, SET, and trap messages are explained further in the following sections.

> ### SNMP Trap Destinations

> An SNMP trap is a message the SNMP agent sends to a network management station (NMS). For example, an SNMP agent sends a trap when the status of an interface has changed from up to down. The SNMP agent must know the address of the NMS so it knows where to send traps.

> You can configure this trap destination for the SNMP master agent from the Sun Java System Application Server Administration interface. You can also view, edit, and remove the trap destinations you have already configured. When you configure trap destinations using the Administration interface, you are actually editing the CONFIG file.

> The server subagent sends a message or trap to the NMS when a significant event has occurred. For example:

> 1. The subagent informs the master agent that the server has stopped.
> 2. The master agent sends a message, or trap, reporting the event to the NMS.
> 3. The NMS displays the information textually or graphically through its network management application.

> Refer to Installing the SNMP Master Agent for instructions on setting up the SNMP trap port.

> ### SNMP Agent Community

> The SNMP agent community consists of a community string and the operations assigned to the specified community. The community string is a text string for a network management station (NMS) name that an SNMP agent uses for authorization. This means that an NMS would send a community string with each message it sends to the agent.

> The operations assigned are get and/or set. The SNMP agent can then verify whether the NMS is authorized to perform get, set, or both get and set operations for data exchange. Community strings are not concealed when sent in SNMP packets; strings are sent in ASCII text.

> You can configure and manage the community string and the allowed operations for each specified community from the Administration interface. Refer to Installing the SNMP Master Agent for instructions on setting up the SNMP Agent Community.

> ##

> Setting Up SNMP

> In general, to use SNMP, a master agent and at least one subagent must be installed and running on your system. The master agent must be installed before you can enable a subagent. Refer to Installing the SNMP Master Agent.

> The procedures for setting up SNMP are different depending upon your system. The following table provides an overview of procedures to follow for different situations. The actual procedures are described in detail later in the chapter.

> Table 6-27 Procedure for Setting Up SNMP

> If your server meets these conditions... | ...follow these procedures. (discussed in detail in the following sections).
> --- | ---
> No native agent is currently running | 1. Start the master agent. 2. Enable the subagent for each server installed on the system.
> Native agent is currently running No SMUX No need to continue using native agent | 1. Stop the native agent when you install the master agent for your Administration Server. 2. Start the master agent. 3. Configure the SNMP subagent for each server instance.
> Native agent is currently running No SMUX Needs to continue using native agent | 1. Install a proxy SNMP agent. 2. Start the proxy SNMP agent. 3. Restart the native agent using a port number other than the master agent port number. 4. Start the master agent. 5. Enable the subagent for each server installed on the system.

> Before you begin, you should verify two things:

> - Is your system already running an SNMP agent (an agent native to your operating system)?
> - If so, does your native SNMP agent support SMUX communication?

> See your system documentation for information on how to verify this information.

> Note | After changing SNMP settings in the Admin Server, installing a new server, or deleting an existing server, you must perform the following steps: (UNIX) Restart the SNMP master agent and the SNMP subagent using the Administration Server.

> The following topics are addressed in this section:

> - Using a Proxy SNMP Agent
> - Installing the SNMP Master Agent

> ### Using a Proxy SNMP Agent

> You need to use a proxy SNMP agent when you already have a native agent running, and you want to continue using it concurrently with a Sun Java System Application Server master agent. Before you start, be sure to stop the native master agent. (See your system documentation for detailed information.)

> Note | To use a proxy agent, you’ll need to install it and then start it. You’ll also have to restart the native SNMP master agent using a port other than the port the Sun Java System Application Server master agent is running on.

> This section includes the following topics:

> - Installing the Proxy SNMP Agent
> - Starting the Proxy SNMP Agent
> - Restarting the Native SNMP Daemon

> #### Installing the Proxy SNMP Agent

> If an SNMP agent is running on your system and you want to continue using the native SNMP daemon, follow the steps in these sections:

> 1. Install the SNMP master agent. See Installing the SNMP Master Agent.
> 2. Install and start the proxy SNMP agent and restart the native SNMP daemon. See Using a Proxy SNMP Agent.
> 3. Start the SNMP master agent. See Enabling and Starting the SNMP Master Agent.
> 4. Enable the subagent. See Enabling the Subagent.

> To install the SNMP proxy agent, edit the CONFIG file (you can give this file a different name), located in install_dir/lib/snmp/sagt in the server root directory, so that it includes the listening port for the SNMP daemon. The proxy agent also needs to include the MIB trees and traps that the proxy SNMP agent will forward.

> Here is an example of a CONFIG file:

> AGENT AT PORT 1161 WITH COMMUNITY public SUBTREES 1.3.6.1.2.1.1, 1.3.6.1.2.1.2, 1.3.6.1.2.1.3, 1.3.6.1.2.1.4, 1.3.6.1.2.1.5, 1.3.6.1.2.1.6, 1.3.6.1.2.1.7, 1.3.6.1.2.1.8 FORWARD ALL TRAPS;

> #### Starting the Proxy SNMP Agent

> To start the proxy SNMP agent, enter the following at the command prompt:

> # sagt -c CONFIG&

> #### Restarting the Native SNMP Daemon

> After starting the proxy SNMP agent, restart the native SNMP daemon at the port you specified in the CONFIG file.

> To restart the native SNMP daemon, enter the following at the command prompt:

> # snmpd -P port_number

> where port_number is the port number specified in the CONFIG file. For example, on the Solaris platform, using the port in the previously mentioned example of a CONFIG file, you would enter:

> # snmpd -P 1161

> ### Installing the SNMP Master Agent

> Note | You cannot use the Administration interface to install and start the master SNMP agent unless the server is running as root.

> To install the master SNMP agent:

> 1. Log in as root.
> 2. Check whether an SNMP daemon (snmpd) is running on port 161.

> If no SNMP daemon is running, go to Step 4.

> If an SNMP daemon is running, make sure you know how to restart it and which MIB trees it supports.

> 3. If an SNMP daemon is running, kill its process.
> 4. In the Administration interface, select the Admin Server node from the left pane.
> 5. Select the Monitoring tab to display the SNMP Agent Trap page.

> The Manager Entries information is displayed on this page.

> 6. Type the name of the system that is running your network management software.
> 7. Type the trap port number at which your network management system listens for traps. (The well-known port is 162.) For more information on traps, see SNMP Trap Destinations.
> 8. Type the community string you want to use in the trap. For more information on community strings, see SNMP Agent Community.
> 9. Click OK.
> 10. Click the SNMP Agent Community link within the Monitoring tab.

> The Community Strings information is displayed.

> 11. Type the community string for the master agent.
> 12. Choose an operation level for the community.

> After you establish a community, you can edit its settings or remove it from the buttons indicated within the Current Communities heading on this page.

> 13. Click OK.
> 14. Access App Server Instances and your server instance in the left pane, then click Apply Changes.

> ##

> Enabling and Starting the SNMP Master Agent

> Master agent operation is defined in an agent configuration file named CONFIG, which you can edit manually. You must install the master SNMP agent before you can enable the SNMP subagent.

> Note | If you get a bind error similar to System Error: Could not bind to port when restarting the master agent, use ps -ef | grep snmp to check if magt is running. If it is running, use the command kill -9 pid to end the process. The CGIs for SNMP will then start working again.

> This section includes the following topics:

> - Starting the Master Agent on Another Port
> - Manually Configuring the SNMP Master Agent
> - Editing the Master Agent CONFIG File
> - Defining sysContact and sysLocation Variables
> - Configuring the SNMP Subagent
> - Starting the SNMP Master Agent
> - Enabling the Subagent

> ### Starting the Master Agent on Another Port

> The Administration interface will not start the SNMP master agent on ports other than 161. However, you can manually start the master agent on another port using the following steps:

> 1. Edit install_dir/lib/snmp/magt/CONFIG to specify the desired port.
> 2. Run the start script as follows:

> cd instance_root/admin-server ./start -shell install_dir/lib/snmp/magt/magt
> install_dir/lib/snmp/magt/CONFIG
> install_dir/lib/snmp/magt/INIT

> The master agent will then start on the desired port. However, the Administration interface will be able to detect that the master agent is running.

> ### Manually Configuring the SNMP Master Agent

> To configure the master SNMP agent manually:

> 1. Log in as root.
> 2. Check to see if there is an SNMP daemon (snmpd) running on port 161.

> If an SNMP daemon is running, make sure you know how to restart it and which MIB trees it supports. Then kill its process.

> 3. Edit the CONFIG file located in lib/snmp/magt in the server root directory.
> 4. (Optional) Define sysContact and sysLocation variables in the CONFIG file as described in Defining sysContact and sysLocation Variables.

> ### Editing the Master Agent CONFIG File

> The CONFIG file defines the community and the manager that will work with the master agent. The manager value should be a valid system name or an IP address.

> Here is an example of a basic CONFIG file:

> COMMUNITY public ALLOW ALL OPERATIONS MANAGER manager_station_name SEND ALL TRAPS TO PORT 162 WITH COMMUNITY public

> ### Defining sysContact and sysLocation Variables

> You can edit the CONFIG file to add initial values for sysContact and sysLocation which specify the sysContact and sysLocation MIB-II variables. The strings for sysContact and sysLocation in this example are enclosed in quotes. Any string that contains spaces, line breaks, tabs, and so on must be in quotes. You can also specify the value in hexadecimal notation.

> Here is an example of a CONFIG file with sysContact and sysLocation variables defined:

> COMMUNITY public ALLOW ALL OPERATIONS MANAGER nms2 SEND ALL TRAPS TO PORT 162 WITH COMMUNITY public INITIAL sysLocation “Server room 901 San Antonio Road Palo Alto CA 94303 USA” INITIAL sysContact “John Doe email: jdoe@sun.com”

> ### Configuring the SNMP Subagent

> To configure the SNMP subagent, perform the following steps:

> 1. From the Admin Server, select the server instance node in the left pane.
> 2. Select the Monitoring tab from the right pane.
> 3. Select the SNMP Subagent Configuration link.
> 4. (UNIX only) Enter the name and domain of the server in the Master Host field.
> 5. Enter the Description of the server, including operating system information.
> 6. Enter the Organization responsible for the server.
> 7. Enter the location of the server instance.
> 8. Enter the name of the person responsible for the server and the person’s contact information in the Contact field.
> 9. Select On to Enable the SNMP Statistics Collection.
> 10. Click OK.
> 11. Access App Server Instances and your server instance in the left pane, then click Apply Changes.

> ### Starting the SNMP Master Agent

> Once you have installed the SNMP master agent, you can start it manually or by using the Admin Server from the Administration interface.

> #### Manually Starting the SNMP Master Agent

> To start the master agent manually, enter the following at the command prompt:

> # magt CONFIG INIT&

> The INIT file is a nonvolatile file that contains information from the MIB-II system group, including system location and contact information. If INIT doesn’t already exist, starting the master agent for the first time will create it.

> Note | An invalid manager name in the CONFIG file will cause the master agent start-up to fail.

> To start a master agent on a non-standard port, use one of two methods:

> Method 1: In the CONFIG file, specify a transport mapping for each interface over which the master agent listens for SNMP requests from managers. Transport mappings allow the master agent to accept connections at the standard port and at a non-standard port. The master agent can also accept SNMP traffic at a non-standard port. The maximum number of concurrent SNMP is limited by your target system’s limits on the number of open sockets or file descriptors per process. Here is an example of a transport mapping entry:

> TRANSPORT extraordinary SNMP
> OVER UDP SOCKET
> AT PORT 11161

> After editing the CONFIG file manually, you should start the master agent manually by typing the following at the command prompt:

> # magt CONFIG INIT&

> Method 2: Edit the /etc/services file to allow the master agent to accept connections at the standard port as well as at a non-standard port.

> #### Starting the SNMP Master Agent Using the Admin Server

> To start the SNMP master agent using the Admin Server, perform the following steps:

> Note | You must be logged in the Sun Java System Application Server as root to start the SNMP Master Agent.

> 1. Log in to the Admin Server.
> 2. From the Admin Server node in the left pane, choose the Monitoring tab.
> 3. Choose the SNMP Agent Control link near the top of the right pane.

> The SNMP Agent Control page is displayed.

> 4. Click Start.

> You can also stop and restart the SNMP master agent from the SNMP Agent Control page.

> ### Enabling the Subagent

> After you have installed the master agent that comes with the Administration Server, you must enable the subagent for your server instance before you attempt to start it. For information on installing the master agent, see Installing the SNMP Master Agent.

> You can use the subagent to stop the SNMP function on UNIX/Linux platforms. You must stop the subagent first, then the master agent. If you stop the master agent first, you may not be able to stop the subagent. If that happens, restart the master agent, stop the subagent, then stop the master agent.

> To enable the SNMP subagent:

> 1. Expand the App Server Instances node in the left pane.
> 2. Select the server instance, then click the Monitoring tab.
> 3. Select the SNMP Subagent Control option to display the SNMP subagent Control page.

> From this page, you can start, stop, or restart the SNMP subagent. The status of the subagent is indicated just above the control buttons.

> Note | After making any SNMP configuration changes, you must click OK, then restart SNMP subagent from the SNMP Subagent Control page.

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.