11 Monitoring Convergence

This chapter describes how to collect data and monitor Oracle Communications Convergence activity.

Overview of Monitoring Convergence

Monitoring is the process of gathering, exposing, and computing run-time data to assess the performance of your Convergence deployment.

You use all the following tools to monitor Convergence:

You use a Java management extensions (JMX) client, such as Jconsole, to gather and view JMX metrics.

For more information about Jconsole, see the Jconsole documentation at:

http://docs.oracle.com/javase/7/docs/technotes/guides/management/jconsole.html
You use the iwcmetrics command-line utility to gather and view non-JMX metrics.

Note:

The iwcmetrics command cannot collect JMX-based metrics, and the JMX client cannot collect non-JMX metrics. You must use all methods to fully and properly monitor Convergence.

Before you can monitor Convergence, you must:

Enable monitoring in Convergence

See "Enabling Convergence Monitoring".
Set up JMX-based server monitoring

See "Configuring Convergence for JMX Monitoring".

See "Using Jconsole for Convergence Monitoring" for information about using Jconsole to monitor Convergence. See "About Convergence JMX Metrics" for information about the metrics collected by the JMX client.

See "Using the iwcmetrics Command for Convergence Monitoring" for information about using the iwcmetrics command to monitor Convergence. See "About Convergence Non-JMX Metrics" for information about the metrics collected by the iwcmetrics command.

Enabling Convergence Monitoring

Use the iwcadmin command-line utility to enable Convergence monitoring and data collection. Set the admin.enablemonitoring parameter to true and restart the GlassFish server:

iwcadmin -o admin.enablemonitoring -v true

Configuring Convergence for JMX Monitoring

To use a JMX-compliant GUI tool, such as or Jconsole, you must configure JMX-based server monitoring, the JVM, and the JAAS. For more information on JMX and JAAS settings and configuration files, see the JMX documentation at:

http://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html

Using Jconsole for Convergence Monitoring

Jconsole is a JMX client which you can use to collect and view Convergence JMX metrics. See "About Convergence JMX Metrics" for more information about the metrics you can collect and view with Jconsole.

To use Jconsole for Convergence monitoring:

Start Jconsole with the following command:
```
$JAVA_HOME/bin/jconsole
```
The Jconsole Connection Agent dialog box appears.
Click the Advanced tab.

In the JMX URL field enter

service:jmx:rmi://hostname:port/jndi/rmi://hostname:port/jmxrmi.

Tip:

You can obtain this URL from the iwc.log file. The JMX console URL is written to the log file when Convergence server starts the admin server. For example:

CONFIG: INFO from com.sun.comms.client.admin.web.JMXAgent  Thread pool-1-thread-7 \\
at 2009-02-23 21:55:31,981 - RMI connector server in non-SSL mode started successfully.
CONFIG: INFO from com.sun.comms.client.admin.web.JMXAgent  Thread pool-1-thread-7 \\
at 2009-02-23 21:55:31,983 - Service URL is: \\
[ service:jmx:rmi://siroe.com:50005/jndi/rmi://siroe.com:50005/jmxrmi ]

Enter the administrator user name and password.
Click Connect.
Expand the Monitoring node.

On the right hand side of the screen you will see the various components of JVM available in tabs. The leaves under the Monitoring node on the left hand side shows the various Instruments that can be used to monitor the JVM.

See "About Convergence JMX Metrics" for a list of the metrics available.

About Convergence JMX Metrics

A JMX client can collect and view the following Convergence metrics:

Authentication LDAP
- Host name of the directory server from which the connections are being served
- Number of free connections in the pool
- Number of used connections in the pool
Calendar Service Connection
- Total number of active sessions
- Details of each active session. Including user ID, IP address, domain name, and the duration of this connection
- Number of sessions since the start of the server
Mail Service Connection
- Total number of active sessions
- Details of each active session. Including user ID, IP address, domain name, and the duration of this connection
- Number of sessions since the start of the server
Instant Messaging Service Connection
- Number of sessions since the start of the server
Session
- Total number of active sessions
- Details of each active session
- Number of sessions since the start of the server
- Number of failed attempts
User and Group LDAP
- Host name of the directory server from which the connections are being served
- Number of free connections in the pool
- Number of used connections in the pool
Server
- Active server duration

Note:

The JMX client cannot collect non-JMX metrics. See "Overview of Monitoring Convergence" for information about collecting non-JMX metrics.

Using the iwcmetrics Command for Convergence Monitoring

The iwcmetrics command-line utility is a script in the Convergence_Home/sbin directory which you can use to collect and view Convergence non-JMX metrics. See "About Convergence Non-JMX Metrics" for information about Convergence non-JMX metrics.

The following example shows the syntax of the iwcmetrics command:

iwcmetrics -U Convergence_URL -u user_name [-W password_file] -m Metric1,Metric2,MetricN

Table 11-1 describes the valid parameters for the iwcmetrics command.

Table 11-1 Parameters for iwcmetrics Command

Parameter	Description
-U	Specifies the complete Convergence URL: http(s)://hostname.domain:port/URI. For example: `https://Convergence.MyDomain.com:8181/iwc`
-u	Specifies the user name. The iwcmetrics command can only collect metrics for the services which the user is privileged to use. To collect metrics for all services, specify a user name that has access to all Convergence services.
-W	Specifies the location of the encrypted password file. If you omit the `-W` parameter, the command-line utility asks you to provide your password. For this reason, the `-W` parameter is omitted from all examples in this guide.
-m	Specifies the metrics to collect. This parameter can specify a single metric, a comma-separated list of metrics, or one or more entire groups of metrics. Metrics are grouped together by service. The `-m` parameter supports the following groups: iwc (Convergence), mail (email), caldav (calendar), im (instant messaging), nab (Contacts Server address book), iss (indexing and search service). For example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m metric1,metric2,group1,group2` Omit the `-m` parameter to collect all metrics. For example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` See "About Convergence Non-JMX Metrics" for more information about Convergence non-JMX metrics and the groups to which they belong.
-l	Lists all available metrics. You do not need to specify a user name or the Convergence URL. For example: `iwcmetrics -l`
-h	Displays information and help for the iwcmetrics command. You do not need to specify a user name or the Convergence URL. For example: `iwcmetrics -h`

The following list gives examples of using the iwcmetrics command:

To display a list of all available metrics:
```
iwcmetrics -l
```
To display the help for the iwcmetrics command:
```
iwcmetrics -h
```

To collect all metrics:

iwcmetrics -U Convergence_URL -u user_name

To collect all metrics pertaining to the mail and address book services:
```
iwcmetrics -U Convergence_URL -u user_name -m mail,nab
```

To collect two metrics from different groups:

iwcmetrics -U Convergence_URL -u user_name -m im.responsetime,caldav.status

About Convergence Non-JMX Metrics

Table 11-2 lists the Convergence metrics that can be collected and viewed using the iwcmetrics command.

Table 11-2 Parameters for iwcmetrics Command

Parameter Name	Description
iwc.loginresponsetime	A measure of the time taken to log into Convergence. This metric is part of the iwc group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m iwc.loginresponsetime`
mail.status	Indicates the status of Oracle Communications Messaging Server. A value of 0 indicates that it is working. This metric is part of the mail group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m mail.status`
mail.responsetime	A measure of the response time between Convergence and Messaging Server. This metric is part of the mail group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m mail.responsetime`
nab.status	Indicates the status of Oracle Communications Contacts Server. A value of 0 indicates that it is working. This metric is part of the nab group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m nab.status`
nab.responsetime	A measure of the response time between Convergence and Contacts Server. This metric is part of the nab group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m nab.responsetime`
caldav.status	Indicates the status of Oracle Communications Calendar Server. A value of 0 indicates that it is working. This metric is part of the caldav group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m caldav.status`
caldav.responsetime	A measure of the response time between Convergence and Calendar Server. This metric is part of the caldav group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m caldav.responsetime`
im.status	Indicates the status of Oracle Communications Instant Messaging Server. A value of 0 indicates that it is working. This metric is part of the im group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m im.status`
im.responsetime	A measure of the response time between Convergence and Instant Messaging Server. This metric is part of the im group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m im.responsetime`
iss.status	Indicates the status of Oracle Communications Indexing and Search Service. A value of 0 indicates that it is working. This metric is part of the iss group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m iss.status`
iss.responsetime	A measure of the response time between Convergence and Indexing and Search Service. This metric is part of the iss group. Example: `iwcmetrics -U` `Convergence_URL` `-u` `user_name` `-m iss.responsetime`

Note:

The iwcmetrics command cannot collect JMX metrics. See "Overview of Monitoring Convergence" for information about collecting JMX metrics.