12 Monitoring Instant Messaging Server

This chapter describes how to collect data and monitor Oracle Communications Instant Messaging Server activity.

Overview of Monitoring the Instant Messaging Server

You can collect data and monitor Instant Messaging Server activity. Examples of the types of data you can collect are:

Total number of users currently online.
Average number of message transfers, per second, in a fixed period of time.
Amount of memory consumed by the server process (XMPPd).
Transaction times for login, roster fetch, and sending an instant message.
Number of packets exchanged with each federated domain.

You can use the collected data for purposes such as:

Monitoring the health of the server and identifying quality of service issues.
Resource utilization and capacity planning.
Gathering per-domain usage data for billing purposes.

For more information on the statistics that can be collected, see "Available Metrics".

To monitor the Instant Messaging data collected you can use either of the following:

Oracle Enterprise Manager (see "Installing and Configuring the Oracle Enterprise Manager Plug-in").
A JMX client, such as JConsole. For information on the JMX metrics available for monitoring, see "Available Metrics". For information on accessing the collected metrics, see the Jconsole documentation at:

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

Configuring Instant Messaging Server Monitoring

To configure data collection and monitoring, you need to enable server monitoring and 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

Steps for Configuring Data Collection and Monitoring

All configuration in the following steps is carried out through the imconfutil command.

Log into the server as root.

Enable monitoring: set the iim_server.monitor.enabled property to true:

imconfutil set-prop iim_server.monitor.enable=true -c InstantMessaging_home/config/iim.conf.xml

Set the user name and password for the server to use in JAAS authentication:

imconfutil set-prop iim_server.admin.user=UserID -c InstantMessaging_home/config/iim.conf.xml

imconfutil set-prop iim_server.admin.password=Password -c InstantMessaging_home/config/iim.conf.xml

You must also assign the user name you enter readwrite permission in the JMX access-control file.

Configure JVM and JAAS properties for monitoring.

The Instant Messaging Server stores all JVM and JAAS properties in a single configuration parameter that is passed to the server process. Table 12-1 lists the properties you need to set.

Table 12-1 Property Settings for Configuring JMX and JAAS for Server Monitoring

Property	Description
-Dcom.sun.management.jmxremote	Enables remote monitoring.
-Dcom.sun.management.jmxremote. port=port_number	Sets the JMX remote access port for the client connection.
-Dcom.sun.management.jmxremote. local.only=false	Allows remote JMX access.
-Dcom.sun.management.jmxremote. ssl=true	true enables SSL for the JMX connection, false disables it.
-Dcom.sun.management.jmxremote. authenticate=true	Enables JAAS authentication.
-Djava.security.auth.login.config=InstantMessaging_home/config/jaas_login_config_file	Specifies the location of the JAAS login configuration file to use for authentication. For more information, see the JAAS documentation at: `http://docs.oracle.com/javase/7/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html`
-Dcom.sun.management.jmxremote. login.config=JAAS_Login	Specifies the name of JAAS login entry in the JAAS login configuration file The name of the entry must match the name you enter for -Dcom.sun.management.jmxremote.login.config with the imconfutil command.
-Dcom.sun.management.jmxremote. access.file=InstantMessaging_home/config/jmxaccess	Specifies the absolute path to the JMX access file. You can create a jmxaccess file based on the JMX-access template file located at: JDK_InstallDir/jre/lib/management/jmxremote.access. In configuring the jmxaccess file, the name of the user specified in controlRole must be same as the user name you entered for the server to use in JAAS authentication.
-Dcom.sun.management.jmxremote.ssl=true	true enables SSL for the JMX connection, false disables it. If you enable SSL, supply the keystore and password as well.
-Djavax.net.ssl.keyStore	Specifies the location of the keystore.
-Djavax.net.ssl.keyStorePassword	Specifies the location of the keystore password.
-Dcom.sun.management.jmxremote.ssl.need.client.auth=false	Disables mutual SSL authentication.

You must set all of the properties in a single imconfutil command. The imconfutil command in the following example sets the JVM and JAAS properties required for monitoring.

imconfutil set-prop iim_server.jvm.options="-Dcom.sun.management.jmxremote.access.file=/opt/sun/comms/im/config/jmxaccess -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9010 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.login.config=Login1 -Djava.security.auth.login.config=/opt/sun/comms/im/config/jaasconfig" -c /opt/sun/comms/im/config/iim.conf.xml

Add an entry to the JAAS login configuration file that contains the com.oracle.im.stat.AdminLoginModule implementation of LoginModule. For information, ese the topic on configuring JAAS login entries at:

http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixB

The name of the entry must match the name you enter for -Dcom.sun.management.jmxremote.login.config with the imconfutil command.
Set the interval, in seconds, at which you want monitored data to be refreshed. The default interval is 30 seconds. To configure an alternative interval:
- Set the iim_server.monitor.refreshtimeout property as in the following example:
```
imconfutil set-prop iim_server.monitor.refreshtimeout=60 -c InstantMessaging_home/config/iim.conf.xml
```
- If you are using a JMX client, you can use the refreshNow operation in the JMX Statistics MBean for an immediate refresh.

Installing and Configuring the Oracle Enterprise Manager Plug-in

The Oracle Enterprise Manager Plug-in for Instant Messaging Server extends the Enterprise Manager to provide access to Instant Messaging Server monitoring:

Usage and performance metrics by server and domain
Alerts and notifications based on thresholds that you set on monitored characteristics.

Product Version Requirements

The Enterprise Manager Plug-in for Oracle Communications Instant Messaging Server supports:

Enterprise Manager Cloud Control 12c Release 1 (12.1.0.3.0) or higher
Oracle Instant Messaging Server 9 Update 1 or higher

Installation Prerequisites

You need to install the following products before you can install the plug-in:

Enterprise Manager Cloud Control 12c Release 1 (12.1.0.3.0) or higher. For more information, see Oracle Enterprise Manager Cloud Control Basic Installation Guide.
Oracle Instant Messaging Server 9 Update 1 or higher

Downloading the Enterprise Manager Plug-in

Download the plug-in from the Enterprise Manager Store as follows:

Log into the Enterprise Manager Cloud Control administration console as a privileged user.
From the Setup menu, select Extensibility, then Self Update.
Select the Plug-in row and click Open.
Scroll down and select the Oracle Communications Instant Messaging Server plug-in.
Click Download.

The plug-in becomes deployable once the download completes. See "Deploying the Enterprise Manager Cloud Control Plug-in" for information on deploying the plug-in.

Configuring Instant Messaging Server Targets

You monitor Instant Messaging Server hosts and domains setup as managed targets in Enterprise Manager. Enterprise Manager also monitors other component non-host targets installed in your environment. Non-host targets consist of applications and their components and infrastructure, for example, Oracle Enterprise databases.

An Oracle Management Agent runs on each host with one or more targets. The Enterprise Manager Management Server communicates with the management agent performing monitoring of host and non-host targets. You need to install the management agent on any host you plan on using with Instant Messaging Server. For more information on managed targets, see the topic on discovering and monitoring targets in Oracle Enterprise Manager Cloud Control Administrator's Guide.

Adding Instant Messaging Server Host Targets and Installing the Management Agent

Add each Instant Messaging Server host you want to monitor to Enterprise Manager as a managed target and install a management agent manually on each host.

To add an individual host and install a management agent on it:

Log in to the Enterprise Manager administration console.
Expand the Setup menu, then select Add Target, then Add Targets Manually.
Select Add Host Targets.
Click Add Host.
Click Add in the Add Host Targets: Host and Platform wizard.
Enter the new target's host name in Host, then select the correct operating system platform from the Platform menu.
Click Next.
Enter an Installation Base Directory on the new target.
Enter an Instance Directory on the new target.
Select a Named Credential for Management Agent installation on the new target. See "Setting Up Preferred Credentials" for more information on setting up host credentials.
Confirm the Privileged Delegation Setting and Port, as well as any Optional Details needed in your installation.
Click Next.
Confirm the Host Information and click Deploy Agent.
Confirm that the Management Agent is properly installed and the new target is now visible in the administration console.

For detailed information on installing the Management Agent, see Oracle Enterprise Manager Cloud Control Basic Installation Guide.

Setting Up Preferred Credentials

Enterprise Manager Cloud Control uses preferred credentials for authentication between the management server and managed agents. You set either default credentials for particular target types or target-specific credentials that are stored in the Enterprise Manager Cloud Control repository.

For more information on setting up preferred credentials, see the discussion on preferred credentials in Oracle Enterprise Manager Cloud Control Administrator's Guide.

Access the Enterprise Manager Cloud Control Security credential store and configure preferred credentials using the following procedure:

Log in to the Enterprise Manager Cloud Control administration console.
Click Setup, then Security, then Preferred Credentials.
Click Manage Preferred Credentials.
To set default preferred credentials, click Set under Default Preferred Credentials. To use target preferred credentials, click Set under Target Preferred Credentials.

You can also set up target preferred credentials when adding a new managed host.

Deploying the Enterprise Manager Cloud Control Plug-in

You must deploy the plug-in on both the management server host and on all Instant Messaging Server hosts running a management agent.

Deploying the Enterprise Manager Cloud Control Plug-in on the Management Server
Deploying the Enterprise Manager Cloud Control Plug-in on Host Targets

Deploying the Enterprise Manager Cloud Control Plug-in on the Management Server

To deploy the plug-in on the management server:

Set up preferred credentials for the target host. See "Setting Up Preferred Credentials" for more information.
From the Setup menu, select Extensibility then select Plug-ins.
Select Oracle Instant Messaging Server from the Applications folder.
From the Deploy On menu, select Management Servers.
In the Deploy Plugin on Management Servers dialog, enter the password for the Sys user and click Continue.
Complete the remaining steps in the dialog box.
Click Deploy.
Monitor the status to ensure successful deployment.

Deploying the Enterprise Manager Cloud Control Plug-in on Host Targets

Deploy the Enterprise Manager Cloud Control Plug-in for Oracle Communications Instant Messaging Server to all host management agents you manage with Enterprise Manager Cloud Control using the following process:

Log in to the Enterprise Manager Cloud Control administration console.
Expand the Setup menu, then select Extensibility, then Plug-Ins.
Expand Applications.
Right-click Oracle Instant Messaging Server.
Select Deploy On, then Management Agent.
In the Deploy Plug-in on Management Agent screen, confirm the Target Type and click Continue.
Click Add under Select Management Agent in the pop-up window.
Select the target(s) on which to deploy the plug-in.
Click Select.
Click Continue.
Confirm there are no errors in the pre-requisite check.
Click Next.
Click Deploy.
Confirm that the Enterprise Manager Cloud Control Plug-in for Oracle Communications Instant Messaging Server deploys successfully.
Repeat these steps for all Instant Messaging Server hosts.

For additional information on deploying plug-ins, refer to the topic on Plug-in Manager in Oracle Enterprise Manager Cloud Control Administrator's Guide.

Using the Enterprise Manager to Monitor Instant Messaging Server

Instant Messaging Server metrics consist of JMX-collected data that provides information on the usage and status of your implementation. See "Available Metrics" for a list of the metrics available. The metrics have default thresholds for generating alerts and sending notifications. To change the thresholds, see "Setting Thresholds on Monitored Metrics". By default, no corrective actions are initiated when a threshold is crossed. To configure corrective actions, see "Adding Corrective Actions".

Viewing Metrics

You can monitor metrics from managed target instances of Instant Messaging Server through the Enterprise Manager Cloud Control administration console:

Log in to the Enterprise Manager Cloud Control administration console as a privileged user.
Click Targets, then All Targets.
In the list of targets, click the Instant Messaging Server in the Instant Messaging Server column you wish to monitor.

Instant Messaging Server targets have an Oracle Instant Messaging Server - Core Server target type. Enterprise Manager Cloud Control displays the target's overview page.
Expand the Oracle Instant Messaging Server - Core Server menu under the target_name.
Click Monitoring, then All Metrics.
In the left-hand tree control, expand the metric category and select the metric you wish to view.

Enabling and Using the Beacon Service

A beacon is a component within the Management Agent that executes tests at regular intervals. A service is considered available if the test executes successfully on at least one key beacon.

To enable the beacon service:

Log in to Oracle Enterprise Manager.
From the Targets menu, select Service and then click create Generic Service.
Enter the required information to define the service availability based on the execution of the service test by the key beacons.
Select the Service test and enter the information for the service test, test type as XMPP, and test parameters.
Add the EM Management Beacon for executing the tests.
Add the Performance Metric based on Service Test and set threshold values to get incidents.
Review the information and click Finish.

To use the beacon service:

Go the Home page of created service.
Select Administration.
Select service tests and beacons.

Available Metrics

Table 12-2 lists the available metrics and gives default thresholds for generating alerts and sending notifications. It also gives the interval at which each metric is refreshed. The table lists metrics based on their organization in the Oracle Enterprise Manager.

Table 12-2 Available Metrics

Enterprise Manager Metric	JMX Parameter	Description
Active Users (in domain)	C2SCountPerDomain	The number of active Instant Messaging Server users in the domain. Warning Threshold: Greater than 80000 users Critical Threshold: Greater than 100,000 users Collection Schedule: Every 10 Minutes
Active Users (logged in)	C2STypeDistroMap	The number of active Instant Messaging Server logins. Separate values are given for MUX, XMPP, and HTTP, as follows: MUX: The number of clients connected through the Multiplexor. XMPPD: The number of clients connected directly to the server (this is not a recommended configuration). HTTP: The number of clients connected through HTTPBIND. The thresholds and collection schedule for this metric are: Warning Threshold: Greater than 80000 users Critical Threshold: Greater than 100,000 users Collection Schedule: Every 10 Minutes
Server Overall Status (up/down)	None	The status (up or down) of the Instant Messaging Server and of the Instant Messaging Multiplexor and Watchdog components, when they are running on the same machine as the Server: 0: The Instant Messaging Server, Multiplexor, and Watchdog are up. 1: The Server is down. 2: The Multiplexor is down. 3: The Watchdog is down. 6: There was an error while trying to get the status of the services. If a component is not on the same machine as the Instant Messaging Server, it is not included in the status. For example, if the Multiplexor is running on a separate machine from the Instant Messaging Server, the status can not be 0 or 2. The thresholds and collection schedule for this metric are: Warning Threshold: NA Critical Threshold: Down Collection Schedule: Every 5 Minutes
Number of Messages Sent to Federated Domain (S2S)	MessageXferPerS2S Domain	The number of messages sent to the Instant Messaging Server federated domain. Warning Threshold: NA Critical Threshold: NA Collection Schedule: Every 10 Minutes
Active Users (server)	ActiveC2SCount	The number of active Instant Messaging Server users. Warning Threshold: Greater than 80000 users Critical Threshold: Greater than 100,000 users Collection Schedule: Every 10 Minutes
Authenticated Users (server)	AuthenticatedUsers Count	The total number of authentications passed since the server started. Warning Threshold: Greater than NA Critical Threshold: Greater than NA Collection Schedule: Every 10 Minutes
Average Number of Users per Chat Room	UsersPerMuc	The average number of users per chat room. Warning Threshold: Greater than 50 users Critical Threshold: Greater than 70 users Collection Schedule: Every 10 Minutes
Average User Life	AverageC2SLifeInSec	Average life of an authenticated client session. Warning Threshold: NA Critical Threshold: NA Collection Schedule: Every 10 Minutes
CPU Usage	ProcessCPUUsage	The CPU percentage consumed by the Instant Messaging Server server process. Warning Threshold: Greater than 70% Critical Threshold: Greater than 90% Collection Schedule: Every 10 Minutes
Client Login Rate	C2SLoginRate	The average number of client logins per second during the last data refresh interval. Warning Threshold: Greater than 10 logins per second Critical Threshold: Greater than 15 logins per second Collection Schedule: Every 10 Minutes
Free Disk Space in Disk Partition of the Instance Directory	FreeDiskSpace	The amount of free disk space in megabytes in the instance partition. Warning Threshold: Less than 2048 MB Critical Threshold: Less than 1024 MB Collection Schedule: Every 10 Minutes
Memory Usage	ProcessMemoryUsage	The memory consumed in megabytes by the Instant Messaging Server server process. Warning Threshold: Greater than 10240 MB Critical Threshold: Greater than 14336 MB Collection Schedule: Every 10 Minutes
Message Transfer Rate	MessageXferPerSec	The message transfer rate, as measured by the average number of messages per second during the last data refresh interval. Warning Threshold: Greater than 300 messages Critical Threshold: Greater than 500 messages Collection Schedule: Every 10 Minutes
Number of Active Chat Rooms	NumOfActiveMUC	The number of active chat rooms. Warning Threshold: Greater than 1000 rooms Critical Threshold: Greater than 1200 rooms Collection Schedule: Every 10 Minutes
Number of File Transfers	FileXferCount	The number of file transfers. Warning Threshold: NA Critical Threshold: NA Collection Schedule: Every 10 Minutes
Transaction Times	None	The transaction times. Login Roster fetch Messages between two users

Customizing Monitoring

You can customize the following aspects of monitoring:

The thresholds for sending alerts and notifications (see "Setting Thresholds on Monitored Metrics")
The notifications sent when a threshold is crossed (see "Setting Notification Options")
The corrective actions taken when a threshold is crossed (see "Adding Corrective Actions")

Setting Thresholds on Monitored Metrics

To set thresholds for Instant Messaging Server data collection and metrics:

From the Enterprise Manager Cloud Control administration console, select a managed Instant Messaging Server target.
On the target's overview page, click the target name and from the Monitoring menu, select Metric and Collections Settings.
On the Metric and Collections Settings page, configure the monitoring thresholds as required for your environment by clicking the Edit icon adjacent to the metric in the Metrics table.
Click OK to save your changes.

Setting Notification Options

You can configure notification behavior by selecting Setup from the Enterprise Manager Cloud Control administration console and then choosing from the options available in the Notifications sub menu. For detailed information on configuring notifications, see Oracle Enterprise Manager Cloud Control Administrator's Guide.

Adding Corrective Actions

You can add automatically executed corrective actions for when warning and critical thresholds are triggered. For information on corrective actions, see Oracle Enterprise Manager Cloud Control Administrator's Guide.