Chapter 2 Enabling and Configuring the Monitoring Framework

As described in How Java ES Monitoring Works, the Monitoring Framework provides the instrumentation and the node agent needed by every monitored component. Therefore, the Monitoring Framework is a shared component that is automatically installed whenever you install a monitored component using the Java Enterprise System installer.

However, many of the monitored components do not have monitoring enabled by default, and some require further configuration to make them appear in the node agent. Follow the procedures in this chapter for each of the product components that you have installed.

It is good practice to install and configure all product components that you intend to run on a given host before performing any of the procedures in this chapter. Before you perform any installation or configuration, you should consult the Sun Java Enterprise System 5 Release Notes for UNIX.

These procedures use the mfwksetup command that is usually not needed and which therefore remains undocumented.

This chapter contains the following sections:

• Installed Directory Layout

• Using the Monitoring Framework with Access Manager

• Using the Monitoring Framework with Application Server

• Using the Monitoring Framework with Calendar Server

• Using the Monitoring Framework with Directory Server

• Using the Monitoring Framework with Instant Messaging

• Using the Monitoring Framework with Messaging Server

• Using the Monitoring Framework with Portal Server

• Using the Monitoring Framework with Web Server

• Setting up the Common Agent Container

• Troubleshooting the Monitoring Framework

• The mfwkadm Command

Installed Directory Layout

As a shared component, the Monitoring Framework is automatically installed whenever it is needed. For the name of the package installed on your operating system, see Chapter 5, List of Installable Packages, in Sun Java Enterprise System 5 Installation Reference for UNIX. The following table describes the directories in the Monitoring Framework package. The default installation directory mfwk-base has the following meaning, as described in Default Paths and File Names:

• Solaris systems: /opt/SUNWmfwk

• Linux systems: /opt/sun/mfwk

Using the Monitoring Framework with Access Manager

By default, monitoring is enabled in Access Manager, but a limitation prevents the monitored objects from appearing in the Monitoring Console.

See Instrumentation of Access Manager for the list of objects and attributes you can monitor.

To Enable Monitoring in Access Manager

1. Temporarily disable monitoring in Access Manager with the following commands:

   cacaoadm unregister-module com.sun.cmm.am.xml cacaoadm restart

2. Open the Access Manager XML descriptor file for editing:

   vi /etc/AccessMgr-base/config/com.sun.cmm.am.xml

3. Find the lines containing:

   <param-name>Product Name</param-name> <param-value>Access Manager</param-value>

   and modify the second line to:

   <param-value>Java ES Access Manager</param-value>

   Save the file and exit the editor.

4. Register the modified XML module:

   mfwk-base/bin/mfwksetup -u /etc/AccessMgr-base/config/com.sun.cmm.am.xml mfwk-base/bin/mfwksetup -r /etc/AccessMgr-base/config/com.sun.cmm.am.xml

5. Restart the Common Agent Container:

   cacaoadm restart

Troubleshooting

Due to untested behavior with third-party web containers, monitoring is disabled by default when Access Manager is deployed in Websphere or Weblogic. You may enable monitoring as described in how To Selectively Disable and Re-Enable Monitoring, although this configuration is unsupported.

Using the Monitoring Framework with Application Server

See Instrumentation of Application Server for the list of objects and attributes you can monitor.

To Enable Monitoring in Application Server

1. Edit the file /var/AppServer-base/domains/domain1/config/domain.xml and change all module-monitoring-level settings from OFF to HIGH. Alternatively:

   1. Log onto the Application Server administration console at https://hostname:4849

   2. Select Configurations, then select server-config (Admin Config)

   3. Set the Monitoring value to HIGH

   4. Set all other values to HIGH

2. Restart Application Server with the following commands:

   cd AppServer-base/appserv/bin asadmin stop-domain domain1 asadmin start-domain user myUser domain1

   Enter the password for myUser when prompted.

3. If you have deployed and monitored an instance of Portal Server with Application Server, the process of restarting Application Server interferes with Portal Server monitoring. To make the Portal Server instance appear in the Monitoring Console, you must visit a portal page in a browser. For example, load the page http://portalserv.example.com:8080/portal to allow monitoring of portalserv.example.com.

Troubleshooting

Due to a limitation, the monitored objects for Application Server are removed from the Monitoring Framework when Application Server crashes or is down. When this happens, Application Server disappears from the Monitoring Console and can no longer be monitored.

Using the Monitoring Framework with Calendar Server

See Instrumentation of Calendar Server for the list of objects and attributes you can monitor.

To Enable Monitoring in Calendar Server

1. Edit the ics.conf file:

   vi CalServ-base/cal/config/ics.conf

2. Add the line:

   local.mfagent.enable="yes"

3. Register Calendar Server XML module:

   mfwk-base/bin/mfwksetup -r /opt/SUNWics5/cal/lib/com.sun.cmm.cs.xml

4. Set the LD_LIBRARY_PATH environment variable as follows:

   LD_LIBRARY_PATH=mfwk-base/lib:$LD_LIBRARY_PATH export LD_LIBRARY_PATH

5. Restart Calendar Server:

   cd CalServ-base/cal/sbin/ ./stop-cal ./start-cal

6. Restart the Common Agent Container:

   cacaoadm restart

Using the Monitoring Framework with Directory Server

See Instrumentation of Directory Server for the list of objects and attributes you can monitor.

To Enable Monitoring in Directory Server

1. Create a temporary password file:

   echo –n password > /tmp/pwd

2. Enable the Monitoring Plugin with the following command:

   DirServ-base/ds6/bin/dscfg enable-plugin -e -p 389 -w /tmp/pwd "Monitoring Plugin"

3. Restart Directory Server:

   cd DirServ-base/ds6/bin ./dsadm restart /var/DirServ-base/DSinstance/

Using the Monitoring Framework with Instant Messaging

See Instrumentation of Instant Messaging for the list of objects and attributes you can monitor.

To Enable Monitoring with Instant Messaging

1. Open the Instant Messaging XML descriptor file for editing:

   vi /etc/IM-base/default/com.sun.cmm.im.xml

2. Change the Install Location from IM-base to /etc/IM-base/default.

3. Register the modified Instant Messaging XML descriptor:

   mfwk-base/bin/mfwksetup -r /etc/IM-base/default/com.sun.cmm.im.xml

4. Enable Instrumentation by adding the following line to the file IM-base/config/iim.conf:

   iim_server.monitor.enable = true

5. Restart Instant Messaging with the following commands:

   cd IM-base/sbin ./imadmin stop ./imadmin start

6. Restart the Common Agent Container:

   cacaoadm restart

Using the Monitoring Framework with Messaging Server

See Instrumentation of Messaging Server for the list of objects and attributes you can monitor.

To Enable Monitoring in Messaging Server

1. Enable Instrumentation with the following command:

   MsgServ-base/sbin/configutil -o local.mfagent.enable -v 1

2. Register the Messaging Server XML module:

   mfwk-base/bin/mfwksetup -r MsgServ-base/lib/com.sun.cmm.ms.xml

3. Restart Messaging Server:

   cd MsgServ-base/sbin ./stop-msg ./start-msg

4. Restart the Common Agent Container:

   cacaoadm restart

Using the Monitoring Framework with Portal Server

See Instrumentation of Portal Server for the list of objects and attributes you can monitor.

To Enable Monitoring in Portal Server

To enable Portal Server, the user has to log onto

http://FullHostname:8080/portal/dt

This will compile the portal JSP, which creates the portal instance that is ready for monitoring.

Troubleshooting

Whenever the Application Server hosting the Portal Server is restarted, you must manually re-enable monitoring with this procedure.

Using the Monitoring Framework with Web Server

See Instrumentation of Web Server for the list of objects and attributes you can monitor.

To Enable Monitoring in Web Server

1. Start Web Server with the following command:

   cd /var/WebServer-base/https-FullHostname/bin ./startserv

2. Start the administration server:

   cd /var/WebServer-base/admin-server/bin ./startserv

Setting up the Common Agent Container

The Common Agent Container is another shared component and one that the Monitoring Framework depends on to run the node agent. Depending on your installation sequence, Common Agent Container may be stopped and need restarting. In addition, Common Agent Container has been instrumented and can be monitored as well. For a description of the monitored objects, see Instrumentation of the Common Agent Container.

To check if the Common Agent Container and thus the node agent is already started, run the following command:

cacaoadm status

If a message similar to the following appears, the node agent is running:

default instance is DISABLED at system startup.
Smf monitoring process:
26996
Uptime: 0 day(s), 0:57

If a message similar to the following appears, the node agent is not running:

default instance is DISABLED at system startup.
default instance is not running.

To Enable Monitoring of the Common Agent Container

The Common Agent Container is a shared component that has instrumentation to allow monitoring. As described in Node Agents, all Java ES components on a host or in a zone share the Common Agent Container and the node agent. Perform this task as root on every logical host in your deployment where you wish to monitor the Common Agent Container.

1. If the Common Agent Container is running, stop it with the following command:

   cacaoadm stop

2. Enable instrumentation of the container itself:

   cacaoadm set-param enable-instrumentation=true

3. Check the value of the parameter you just set and restart the Common Agent Container:

   cacaoadm get-param enable-instrumentation cacaoadm start

4. Create a key password:

   echo –n password > /etc/mfwk-base/config/security/password.cacao

5. Generate your key:

   mfwk-base/bin/cpgenkey -n cacao -p /etc/mfwk-base/config/security/password.cacao

6. Register the Common Agent Container's own monitoring modules:

   cacaoadm register-module /usr/lib/cacao/ext/instrum/config/com.sun.cacao.instrum.xml cacaoadm register-module /usr/lib/cacao/ext/instrum_jesmf/config/com.sun.cacao.instrum.jesmf.xml cacaoadm register-module /usr/lib/cacao/ext/instrum_jesmf/config/com.sun.cacao.cmm.xml

Troubleshooting the Monitoring Framework

See also the known issues listed in the Sun Java Enterprise System 5 Release Notes for UNIX.

Using the Monitoring Framework on HP-UX Platforms

The Java Virtual Machine (JVM) on HP-UX is not tuned by default for the task-intensive processing needed by Monitoring Framework, and this may lead to OutOfMemory exceptions. To configure the JVM, download and run the HPjconfig tool from the following location:http://h21007.ww2.hp.com/dspp/tech/tech_TechDocumentDetailPage_IDX/1,1701,1620,00.html.

Using the Monitoring Framework on Microsoft Windows

Monitoring Java ES components on the Windows platform through the Monitoring Framework is fully supported, although there are some differences. For example, you must upgrade to Java 1.5 or later to avoid certain known issues. For other known issues, see the Sun Java Enterprise System 5 Release Notes for Microsoft Windows.

To Restart a Node Agent

If you need to restart the Common Agent Container that hosts a node agent, the components monitored through that node agent will not be visible in the Monitoring Console until you perform this procedure:

1. Restart the Common Agent Container that hosts the node agent:

   cacaoadm restart

2. Restart the Common Agent Container that hosts the master agent. The master agent runs in the Monitoring Framework on the host or in the zone where you installed theMonitoring Console.

   cacaoadm restart

   The master agent will automatically reconnect with all node agents that it was previously monitoring.

3. Restart the web server that hosts the Monitoring Console:

   /usr/sbin/smcwebserver restart

The mfwkadm Command

This section reproduces the man page for the mfwkadm command, a maintenance command in man page section 1M. Use this command to manage the contents of a node agent, including all of the modules for components being monitored and any monitoring rules, also known as jobs, that you have defined on this node. Some of the terms and descriptions in the man page have been modified here to match those used in this document.

Synopsis

Performance Monitoring

Operational Status Monitoring

Threshold Value Monitoring

Description

The mfwkadm utility is the command line interface for managing the Monitoring Framework agent, also called the node agent. The node agent runs inside the Common Agent Container. The mfwkadm utility can be used to stop and restart the node agent and to manage the monitoring jobs it performs. This command should be run from the same host where the node agent is running. The order of the arguments of this command presented here must be respected.

To change the language of the output messages, set the LC_MESSAGE environment variable to your locale. The mfwkadm command will use the messages contained in the file named JesmfMessages_locale.pm in the lib/resources directory. If the locale has no corresponding file of messages, or if no locale is specified, the mfwkadm command will use the default set of messages in the file JesmfMessages.pm.

The mfwkadm utility has the following subcommands. Those marked with an asterisk (*) require the Common Agent Container to be running and the node agent to be loaded:

• start

• stop

• restart

• list-params (*)

• list-modules (*)

• info (*)

• pm-job (*)

• opstat-job (*)

• thrsh-job (*)

Depending on the number of Common Agent Container modules to load, there is a delay of a few seconds to a few minutes between starting the node agent and the availability of the mfwkadm utility. During this period of time, commands fail with an explicit message.

Options

The following options are supported.

--help

Display the usage summary.

Subcommands

start

Start the Monitoring Framework node agent and its associated component product modules without stopping the Common Agent Container.

This action first deploys the node agent and then deploys the associated component product modules in the Common Agent Container. This facility is a wrapper on top of the cacaoadm utility's lock and undeploy subcommands.

The start subcommand only starts the node agent and the Java ES component modules associated with the Monitoring Framework. Component modules have the prefix com.sun.cmm.

Security: The start subcommand can be run only by the user who launched the Common Agent Container. Otherwise an error message similar to the following will be displayed:

Error occured in mfwkadm Problem running /usr/sbin/cacaoadm unlock com.sun.mfwk 2>&1. Stdout/Stderr: This command must be run by user: [root].

stop

Stop the Monitoring Framework node agent and its associated Java ES component modules in the Common Agent Container.

This action first stops any Java ES component's modules deployed in the Common Agent Container, and then stops the node agent. This facility is a wrapper on top of the cacaoadm lock and unlock subcommands.

The stop subcommand stops only those Java ES component modules associated with the Monitoring Framework and then the node agent itself. Component modules have the prefix com.sun.cmm.

Security: The stop subcommand can be run only by the user who launched the Common Agent Container. Otherwise an error message similar to the following will be displayed:

Error occured in mfwkadm Problem running /usr/sbin/cacaoadm unlock com.sun.mfwk 2>&1. Stdout/Stderr: This command must be run by user: [root].

restart

Restart the Monitoring Framework node agent and its associated Java ES component modules in the Common Agent Container.

This action will attempt to stop and then start the node agent and its associated modules in the Common Agent Container in the same way as the stop and start subcommands.

Security: The restart subcommand can be run only by the user who launched the Common Agent Container. Otherwise an error message similar to the following will be displayed:

Error occured in mfwkadm Problem running //usr/sbin/cacaoadm unlock com.sun.mfwk 2>&1. Stdout/Stderr: This command must be run by user: [root].

list-params

List all the configuration parameters related to the Monitoring Framework node agent.

Security: There is no user restriction for this command.

list-modules

Display a list of those component product modules that implement the Common Monitoring Model (CMM) and that are loaded into the Common Agent Container. This subcommand also lists all running instances of each installed Java ES component. Each component can have zero, one, or more running instances.

Security:For users other than the one who launched the Common Agent Container, the list of installed Java ES components does not include component instances.

info runningInstance

Display information on the named runningInstance. The runningInstance must match a running instance listed in the output of the list-modules subcommand.

The displayed information includes:

• For each type of monitoring job, all observable objects associated with the running instance, sorted by their class name. Observable objects are those on which you can create a performance monitoring job, an operational status job, or a threshold monitoring job using the pm-job, opstat-job, or thrsh-job subcommands, respectively.

• For each class of observable objects, all of its observable attributes, including the name and type of each.

Security: For users other than the one who launched the Common Agent Container, no information will be displayed.

Performance Monitoring

pm-job observable-classes

Display the list of all currently observable classes of objects for which you can create performance monitoring jobs.

pm-job observable-objects [class=objectC lass] [domain=objectDomain]

Display the list of all currently observable objects for which you can create performance monitoring jobs. By default all objects of all observable classes and in every domain will be listed. The list of objects is sorted by their class name.

class=objectClass

Specifying the optional objectClass will restrict the output to observable objects of that specific class. The objectClass must be one of the classes listed by the pm-job observable-classes subcommand.

domain=objectDomain

Specifying the optional objectDomain will restrict the output to observable objects in that domain. The domain of an object is the string preceding the colon (“:”) character in an object's name.

pm-job observable-attributes class=objectClass

Display the list of all observable attributes in the specified objectClass. Attributes are displayed with their name and type. The objectClass must be one of the classes that supports performance monitoring jobs, as listed by the pm-job observable-classes subcommand.

pm-job list

Displays the list of all currently defined performance monitoring jobs. Jobs are listed for each object having a defined performance job, and objects are sorted by their class name. The information displayed for each job is the same as displayed by the pm-job info subcommand.

Security: For other users than the one who launched the Common Agent Container, no jobs will be displayed.

pm-job info jobName

Display verbose information about a performance monitoring job named jobName. The jobName must be one displayed by the pm-job list subcommand. This subcommand displays the following information:

• The name of the performance monitoring job.

• The type of the performance monitoring job, either “by object” or “by class.” Jobs by object monitor one or more named object instances, whereas jobs by class monitor every instance of an object class. Note that it is not possible to create jobs by class with the mfwkadm utility.

• The state of the performance monitoring job: active on-duty, active off-duty, or suspended. An active on-duty job is currently scheduled to run and is collecting data. An active off-duty job is running but not collecting data because the current time is out of its working schedule. A suspended job is not running nor collecting any data. Use the pm-job suspend and pm-job resume subcommands to change the running state of a performance monitoring job.

• The granularity in seconds of the performance monitoring job. This is the interval for data collection by this job.

• The reporting period of the monitoring job. The reporting period times the granularity equals the notification frequency. For example, if the granularity period is 10 seconds and the reporting period is 6, a job reporting by event will collect data every 10 seconds and will send a notification including 6 reports every 60 seconds (10*6). If the job is also reporting by file, it will send an event every 60 seconds containing the locations of the 6 generated files.

• Whether the performance monitoring job is reporting by event. This means the results of the performance monitoring job are sent as notifications to a registered client.

• Whether the performance monitoring job is reporting by file. This means the reports of the performance monitoring job are written in local files and notifications containing the filenames are sent to registered clients.

• The report format of the performance monitoring job, which is always XML.

• The schedule of the performance monitoring job. The schedule specifies what days and times the job is active on-duty or active off-duty (collecting data or not, respectively).

Then for a job by-object:

• The list of observed objects, ordered by name.

• If only a subset of observable attributes are specified, the observed attributes of the observed objects are listed by name and type.

And for a job by-class:

• The list of observed classes, ordered by name.

• If only a subset of observable attributes are specified, the observed attributes of the observed classes are listed by name and type. These attributes are common to all classes.

Security: For users other than the one who launched the Common Agent Container, no information will be displayed.

pm-job create jobName granularity=integerValue object=objectName [object=objectName ...]

Creates a new performance monitoring job on one or more objects. The mfwkadm command cannot create jobs by class. When creating performance monitoring jobs, the following parameters can be set:

jobName

A string uniquely identifying the performance monitoring job. The jobName cannot be already in use by any other performance monitoring job.

granularity=integerValue

The time specified in seconds between the initiation of two successive collections of measurement data, while the job is active on-duty. Examples of granularity period can be 300 seconds (5 minutes), 900 seconds (15 minutes), 1800 seconds (every half-hour), 3600 seconds (every hour). A granularity period of 300 seconds is sufficient in most cases. For some measurements it can be more meaningful to collect data with larger granularity periods.

object=objectName [object=objectName ...]

One or more observable objects that the performance monitoring job will collect data from and report on. The objectName must be one displayed by the pm-job list or pm-job observable-objects subcommands. Specifying multiple object=objectName parameters will create a single performance monitoring job that monitors multiple objects.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

pm-job delete jobName

Delete a performance monitoring job named jobName. The jobName must be one displayed by the pm-job list subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

pm-job suspend jobName

Suspend a performance monitoring job named jobName. A suspended job is not active and will no longer collect data, regardless of its schedule. However, the job remains defined and can be made active again with the pm-job resume subcommand. The jobName must be one displayed by the pm-job list subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

pm-job resume jobName

Resume a performance monitoring job named jobName. A resumed job will begin collecting data and sending reports according to its schedule. The jobName must be one displayed by the pm-job list subcommand. This is the counterpart to the pm-job suspend subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

Operational Status Monitoring

opstat-job observable-classes

Display the list of all currently observable classes of objects for which you can create operational status monitoring jobs.

opstat-job observable-objects [class=objectClass] [domain=objectDomain]

Display the list of all currently observable objects for which you can create operational status monitoring jobs. By default all objects of all observable classes and in every domain will be listed. The list of objects is sorted by their class name.

class=objectClass

Specifying the optional objectClass will restrict the output to observable objects of that specific class. The objectClass must be one of the classes listed by the opstat-job observable-classes subcommand.

domain=objectDomain

Specifying the optional objectDomain will restrict the output to observable objects in that domain. The domain of an object is the string preceding the colon (“:”) character in the object's name.

opstat-job observable-attributes class=objectClass

Display the list of all observable attributes in the specified objectClass. Attributes are displayed with their name and type. The objectClass must be one of the classes listed by the opstat-job observable-classes subcommand.

opstat-job list

Displays the list of all currently defined operational status monitoring jobs. Jobs are listed for each object having a defined operational status job, and objects are sorted by their class name. The information displayed for each job is the same as displayed by the opstat-job info subcommand.

Security: For other users than the one who launched the Common Agent Container, no jobs will be displayed.

opstat-job info jobName

Display verbose information about an operational status monitoring job named jobName. The jobName must be one displayed by the opstat-job list subcommand. This subcommand displays the following information:

• The name of the operational status monitoring job.

• The type of the operational status monitoring job, either “by object” or “by class.” Jobs by object monitor a named object instance, whereas jobs by class monitor every instance of an object class. Note that it is not possible to create jobs by class with the mfwkadm utility.

• The state of the operational status monitoring job: active on-duty, active off-duty, or suspended. An active on-duty job is currently scheduled to run and is collecting data. An active off-duty job is running but not collecting data because the current time is out of its working schedule. A suspended job is not running nor collecting any data. Use the opstat-job suspend and opstat-job resume subcommands to change the running state of an operational status monitoring job.

• The granularity in seconds of the operational status monitoring job. This is the interval for data collection by this job.

• Whether the operational status monitoring job is reporting by event. This means the results of the operational status monitoring job are sent as notifications to a registered client.

• Whether the operational status monitoring job is reporting by file. This means the reports of the operational status monitoring job are written in local files and notifications containing the filenames are sent to registered clients.

• The report format of the operational status monitoring job, which is always XML.

• The schedule of the operational status monitoring job. The schedule specifies what days and times the job is active on-duty or active off-duty (collecting data or not, respectively).

• For a job by-object, the list of observed objects, ordered by name.

• For a job by-class, the list of observed classes, ordered by name.

Security: For users other than the one who launched the Common Agent Container, no information will be displayed.

opstat-job create jobName granularity=integerValue object=objectName [object=objectName ...]

Creates a new operational status monitoring job on one or more objects. The mfwkadm command cannot create jobs by class. When creating performance monitoring jobs, the following parameters can be set:

jobName

A string uniquely identifying the operational status monitoring job. The jobName cannot be already in use by any other operational status monitoring job.

granularity=integerValue

The time specified in seconds between the initiation of two successive collections of measurement data, while the job is active on-duty.

object=objectName [object=objectName ...]

One or more observable objects that the operational status monitoring job will collect data from and report on. The objectName must be one displayed by the opstat-job list or opstat-job observable-objects subcommands. Specifying multiple object=objectName parameters will create a single operational status job that monitors multiple objects.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

opstat-job delete jobName

Delete an operational status monitoring job named jobName. The jobName must be one displayed by the opstat-job list subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

opstat-job suspend jobName

Suspend an operational status monitoring job named jobName. A suspended job is not active and will no longer collect data, regardless of its schedule. However, the job remains defined and can be made active again with the opstat-job resume subcommand. The jobName must be one displayed by the opstat-job list subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

opstat-job resume jobName

Resume an operational status monitoring job named jobName. A resumed job will begin collecting data and sending reports according to its schedule. The jobName must be one displayed by the opstat-job list subcommand. This is the counterpart to the opstat-job suspend subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

Threshold Value Monitoring

thrsh-job observable-classes

Display the list of all currently observable classes of objects for which you can create threshold monitoring jobs.

thrsh-job observable-objects [class=objectClass] [domain=objectDomain]

Display the list of all currently observable objects for which you can create threshold monitoring jobs. By default all objects of all observable classes and in every domain will be listed. The list of objects is sorted by their class name.

class=objectClass

Specifying the optional objectClass will restrict the output to observable objects of that specific class. The objectClass must be one of the classes listed by the thrsh-job observable-classes subcommand.

domain=objectDomain

Specifying the optional objectDomain will restrict the output to observable objects in that domain. The domain of an object is the string preceding the colon (“:”) character in the object's name.

thrsh-job observable-attributes class=objectClass

Display the list of all observable attributes in the specified objectClass. Attributes are displayed with their name and type. The objectClass must be one of the classes listed by the thrsh-job observable-classes subcommand.

thrsh-job list

Displays the list of all currently defined threshold monitoring jobs. Jobs are listed for each object having a defined threshold job, and objects are sorted by their class name. The information displayed for each job is the same as displayed by the thrsh-job info subcommand.

Security: For other users than the one who launched the Common Agent Container, no jobs will be displayed.

thrsh-job info jobName

Display verbose information about a threshold monitoring job named jobName. The jobName must be one displayed by the thrsh-job list subcommand. This subcommand displays the following information:

• The name of the threshold monitoring job.

• The multiplicity of the threshold monitoring job. In this release, only simple threshold jobs that monitor one attribute on one object are possible.

• The state of the threshold monitoring job: active on-duty, active off-duty, or suspended. An active on-duty job is currently scheduled to run and is collecting data. An active off-duty job is running but not collecting data because the current time is out of its working schedule. A suspended job is not running nor collecting any data. Use the thrsh-job suspend and thrsh-job resume subcommands to change the running state of a threshold monitoring job.

• The granularity in seconds of the threshold monitoring job. This is the interval for data collection by this job.

• The schedule of the threshold monitoring job. The schedule specifies what days and times the job is active on-duty or active off-duty (collecting data or not, respectively).

• The alarm configuration of the threshold monitoring job. This is the alarm that will be triggered when the observed value of the monitored attribute crosses the defined threshold value. The display includes the alarm's type and severity.

• The observed object of the threshold monitoring job.

• The attribute name to which the threshold is applied.

• The value of the threshold that will trigger an alarm.

• The direction of the value's progress that will trigger an alarm at the threshold, either RISING or FALLING.

• The tolerance offset of the threshold. When the direction is RISING, an alarm will not be triggered again until the observed attribute is less than the thresholdValue-offsetValue. When the direction is FALLING, an alarm will not be triggered again until the observed attribute is more than the thresholdValue+offsetValue. This behavior holds true even when the offset is zero.

Security: For users other than the one who launched the Common Agent Container, no information will be displayed.

thrsh-job create jobName object=objectName granularity=integerValue attributeName=attributeName attributeType=attributeType thresholdValue=thresholdValue thresholdOffset=offsetValue thresholdDirection=[RISING|FALLING]

Creates a new threshold monitoring job that monitors one attribute on a single object. When creating threshold jobs, the following parameters can be set:

jobName

A string uniquely identifying the threshold monitoring job. The jobName cannot be already in use by any other threshold monitoring job.

object=objectName

The observable object on which the threshold monitoring job will collect the attribute values to compare against the threshold. The objectName must be one displayed by the thrsh-job list or thrsh-job observable-objects subcommands.

granularity=integerValue

The time specified in seconds between the initiation of two successive observations of the attribute value, while the job is active on-duty.

attributeName=attributeName

The name of the attribute for which the threshold monitoring job gathers values and compares compare them to the threshold. The attributeName must be listed by the thrsh-job info or thrsh-job observable-attributes subcommands.

attributeType=attributeType

The type of the observable attribute to be monitored. The attributeType must be listed by the thrsh-job info or thrsh-job observable-attributes subcommands.

thresholdValue=thresholdValue

The value of the monitored attribute that will cause this threshold job to trigger an alarm when crossed in the direction specified by thresholdDirection.

thresholdOffset=offsetValue

The offsetValue determines the tolerance of the threshold job in triggering successive alarms. The offsetValue must be zero or a positive value. After an alarm event is triggered, no new alarm event will be triggered until the value of the monitored attribute exceeds the range defined by the offsetValue and the thresholdDirection.

thresholdDirection=[RISING|FALLING]

When the direction is RISING, an alarm event will not be triggered again until the observed attribute value is less than thresholdValue-offsetValue. When the direction is FALLING, an alarm event will not be triggered again until the observed attribute value is more than thresholdValue+offsetValue. This behavior holds true even when the offsetValue is zero.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

thrsh-job delete jobName

Delete a threshold monitoring job named jobName. The jobName must be one displayed by the thrsh-job list subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

thrsh-job suspend jobName

Suspend a threshold monitoring job named jobName. A suspended job is not active and will no longer collect data, regardless of its schedule. However, the job remains defined and can be made active again with the thrsh-job resume subcommand. The jobName must be one displayed by the thrsh-job list subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

thrsh-job resume jobName

Resume a threshold monitoring job named jobName. A resumed job will begin collecting data and sending reports according to its schedule. The jobName must be one displayed by the thrsh-job list subcommand. This is the counterpart to the thrsh-job suspend subcommand.

Security: This subcommand can be run only by the user who launched the Common Agent Container.

Examples

The following fictional scenario demonstrates how to use the mfwkadm utility, along with its options and subcommands.

The list-modules subcommand shows the Java ES component instances on the current host and their corresponding modules in the Common Agent Container. The following example lists two installed components, Directory Server having no running instances and Web Server having one running instance.

$ mfwkadm list-modules

Installed products and their running instances:
==============================================

Instances for installed product: com.sun.cmm.ds:collectionID=/opt/SUNWdsee/ds6,
name=Sun Java(TM) System Directory Server,type=CMM_InstalledProduct
-------------------------------

No instance.

Instances for installed product: com.sun.cmm.ws:collectionID=/var/opt/SUNWwbsvr7,
name=WebServer,type=CMM_InstalledProduct
-------------------------------

/wsPrefix/com.sun.cmm.ws:name=https-hostname.example.com,type=CMM_ApplicationSystem

The following info subcommand displays observable objects in the Web Server instance, with their classes and attributes for each job type.

$ mfwkadm info /wsPrefix/com.sun.cmm.ws:name=https-hostname.example.com,\\
type=CMM_ApplicationSystem

Information about running instance: /wsPrefix/com.sun.cmm.ws:
name=https-hostname.example.com,type=CMM_ApplicationSystem
==================================

Observable objects for performance jobs:
---------------------------------------

+ Objects of class: com.sun.cmm.settings.CMM_ApplicationSystemSetting

        /wsPrefix/com.sun.cmm.ws:name=https-hostname.example.com-setting,
type=CMM_ApplicationSystemSetting

        Observable attributes:

        Caption [STRING]
        ConfigurationDirectory [STRING]
        CreationClassName [STRING]
        Description [STRING]
        DirectoryName [STRING]
        ElementName [STRING]
        InstanceID [STRING]
        Name [STRING]
        URL [STRING]

+ Objects of class: com.sun.cmm.settings.CMM_KeepAliveSetting

        /wsPrefix/com.sun.cmm.ws:name=process-1-keepalive-setting,
type=CMM_KeepAliveSetting

        Observable attributes:

        AllocationUnit [STRING]
        Caption [STRING]
        ConnectionsUpperBound [LONG]
        CreationClassName [STRING]
        Description [STRING]
        ElementName [STRING]
        InputUnit [STRING]
        InstanceID [STRING]
        LowerAllocationLimit [LONG]
        LowerInputLimit [LONG]
        LowerOutputLimit [LONG]
        Name [STRING]
        OtherAllocationUnit [STRING]
        OtherInputUnit [STRING]
        OtherLowerAllocationLimit [LONG]
        OtherLowerInputLimit [LONG]
        OtherLowerOutputLimit [LONG]
        OtherOutputUnit [STRING]
        OtherUpperAllocationLimit [LONG]
        OtherUpperInputLimit [LONG]
        OtherUpperOutputLimit [LONG]
        OutputUnit [STRING]
        QueuedUpperBound [LONG]
        SecondsTimeout [LONG]
        TimeoutUpperBound [LONG]
        UpperAllocationLimit [LONG]
        UpperInputLimit [LONG]
        UpperOutputLimit [LONG]
        ...

The following command shows the list of defined performance monitoring jobs. In this example, there is one performance job called myPerfJob that monitors one object:

$ mfwkadm pm-job list

BY_OBJECTS performance jobs:
===========================

Performance job information for: myPerfJob
-------------------------------

Type:                BY_OBJECTS
State:               ACTIVE_ON_DUTY
Granularity period:  30
Reporting period:    1
By event:            EVENT_SINGLE
By file:             EVENT_SINGLE
Report format:       XML
Schedule:           
        Global start time: Immediately
        Global stop time: Forever
        Weekly schedule: Everyday
        Daily schedule: All day
Observed objects:    
                /wsPrefix/com.sun.cmm.ws:name=virtualServer-hostname.example.com-
webApp-/-stats,type=CMM_VirtualServerWebModuleStats
Observed attributes: 
                All available

BY_CLASSES performance jobs:
===========================

No jobs found.

The following command creates an operational status monitoring job related to two observable objects obtained from the opstat-job info or opstat-job observable-objects subcommands:

$ mfwkadm opstat-job create myOpStatJob granularity=60 \\
object=/wsPrefix/com.sun.cmm.ws:name=process-1,type=CMM_UnixProcess \\
object=/wsPrefix/com.sun.cmm.ws:name=process-1-DNSCache1,type=CMM_DnsCache

The following command suspends the job created above:

$ mfwkadm opstat-job suspend myOpStatJob

The following command shows the observable classes for the potential threshold monitoring jobs:

$ mfwkadm thrsh-job observable-classes

Threshold jobs observable classes:
=================================

com.sun.cmm.cim.CIM_ScopedSettingData
com.sun.cmm.cim.CIM_SettingData
com.sun.cmm.cim.CIM_StatisticalData
com.sun.cmm.cim.statistics.CIM_EthernetPortStatistics
com.sun.cmm.cim.statistics.CIM_NetworkPortStatistics
com.sun.cmm.cim.statistics.j2ee.CIM_J2eeJVMStats
com.sun.cmm.cim.statistics.j2ee.CIM_J2eeStatistic
com.sun.cmm.settings.CMM_ApplicationSystemSetting
com.sun.cmm.settings.CMM_KeepAliveSetting
com.sun.cmm.settings.CMM_QueueTimeoutSetting
com.sun.cmm.settings.CMM_RFC2788ApplicationSystemSetting
com.sun.cmm.settings.CMM_ScopedSettingData
com.sun.cmm.settings.CMM_SoftwareResourceSetting
com.sun.cmm.settings.CMM_SWRBufferSetting
com.sun.cmm.settings.CMM_SWRLimitSetting
com.sun.cmm.settings.CMM_SWRQueueSetting
com.sun.cmm.settings.CMM_VirtualServerSetting
com.sun.cmm.statistics.CMM_ApplicationSystemStats
com.sun.cmm.statistics.CMM_ApplicationSystemWatchdogStats
com.sun.cmm.statistics.CMM_ConnectionQueueStats
com.sun.cmm.statistics.CMM_DnsCacheStats
com.sun.cmm.statistics.CMM_EthernetPortStats
com.sun.cmm.statistics.CMM_FileCacheStats
com.sun.cmm.statistics.CMM_HTTPResponsesStats
com.sun.cmm.statistics.CMM_JVMJSR174ExtStats
com.sun.cmm.statistics.CMM_JVMJSR174Stats
com.sun.cmm.statistics.CMM_JVMStats
com.sun.cmm.statistics.CMM_NetworkPortStats
com.sun.cmm.statistics.CMM_OperatingSystemStats
com.sun.cmm.statistics.CMM_ProcessorStats
com.sun.cmm.statistics.CMM_ProcessStats
com.sun.cmm.statistics.CMM_QueueTimeoutStats
com.sun.cmm.statistics.CMM_RFC2788ApplicationTableStats
com.sun.cmm.statistics.CMM_ServiceStats
com.sun.cmm.statistics.CMM_SoftwareResourceStats
com.sun.cmm.statistics.CMM_SolarisEthernetPortStats
com.sun.cmm.statistics.CMM_SolarisNetworkPortStats
com.sun.cmm.statistics.CMM_SolarisOperatingSystemStats
com.sun.cmm.statistics.CMM_SolarisProcessorStats
com.sun.cmm.statistics.CMM_SolarisProcessorSysinfoStats
com.sun.cmm.statistics.CMM_SolarisProcessorVmStats
com.sun.cmm.statistics.CMM_Statistic
com.sun.cmm.statistics.CMM_SWRBufferStats
com.sun.cmm.statistics.CMM_SWRCacheStats
com.sun.cmm.statistics.CMM_SWRLimitStats
com.sun.cmm.statistics.CMM_SWRQueueStats
com.sun.cmm.statistics.CMM_UnixOperatingSystemStats
com.sun.cmm.statistics.CMM_UnixProcessStats
com.sun.cmm.statistics.CMM_VirtualServerWebModuleStats
com.sun.cmm.statistics.CMM_WebModuleStats

The following command shows the observable attributes for threshold jobs that monitor objects of class com.sun.cmm.statistics.CMM_SWRQueueStats found in the previous example:

$ mfwkadm thrsh-job observable-attributes \\
class=com.sun.cmm.statistics.CMM_SWRQueueStats

Threshold jobs observable attributes:
====================================

Class: com.sun.cmm.statistics.CMM_SWRQueueStats

Attributes: 

BufferSize [LONG]
EntriesCount [LONG]
EntriesHighWaterMark [LONG]
EntriesLowWaterMark [LONG]
EntriesTotal [LONG]
ErrorCount [INTEGER]
FailedOperations [LONG]
LowerLimit [LONG]
OperationsCount [LONG]
OtherLowerLimit [LONG]
OtherUpperLimit [LONG]
OverflowsCount [LONG]
QueuedCount [LONG]
QueuedHighWater [LONG]
SampleInterval [LONG]
TotalQueuedCount [LONG]
UpperLimit [LONG]

The following command is another example of job creation, here with a threshold job:

$ mfwkadm thrsh-job create myThreshJob granularity=30 \\
object=/wsPrefix/com.sun.cmm.ws:name=process-1-threadPool-NativePool-stats,\\
type=CMM_SWRQueueStats attributeName=EntriesCount attributeType=LONG \\
thresholdValue=1000 thresholdOffset=10 thresholdDirection=RISING

The following example demonstrates the output of the thrsh-job info subcommand for the threshold monitoring job created in the previous example:

$ mfwkadm thrsh-job info myThreshJob

Threshold job information for: myThreshJob
-----------------------------

Type:                SIMPLE
State:               ACTIVE_ON_DUTY
Granularity period:  30
Schedule:           
        Global start time: Immediately
        Global stop time: Forever
        Weekly schedule: Everyday
        Daily schedule: All day
Alarm configuration:
                Type: QualityOfServiceAlarm
                Severity: INDETERMINATE
Threshold definition(s):
                Object: /wsPrefix/com.sun.cmm.ws:name=process-1-threadPool-
NativePool-stats,type=CMM_SWRQueueStats
                        Attribute: EntriesCount [LONG]
                        Value: 1000
                        Direction: RISING
                        Offset: 10

Exit Status

The following exit values are returned:

0

Successful completion

1

An error occurred

Attributes

See Also

cacao.5, cacaoadm.1m