Table of Contents

10g Release 5 (10.2.0.5)

E14631-02

Contents

Getting Started Guide for Oracle Coherence

- Supported Versions

- Understanding the Discovery Mechanism

- Configuring and Starting the Management Node Using Bulk Management MBeans

- Starting the Coherence Management Node with Security Credentials

- Discovering Oracle Coherence

- Enabling the Management Pack

- Troubleshooting

- Monitoring a Coherence Cluster

- Performance Page

- List of Coherence Metrics Being Monitored

- Metric Thresholds

- Documentation Accessibility

Oracle® Enterprise Manager

Getting Started Guide for Oracle Coherence

10g Release 5 (10.2.0.5)

E14631-02

April 2009

This document describes the procedure to discover and monitor a Coherence cluster using Enterprise Manager Grid Control 10g Release 5 (10.2.0.5). This document assumes that you have installed the Oracle Management Agent and the Enterprise Manager 10.2.0.5 patchset on your OMS.

The following sections are covered in this document:

- Supported Versions

- Understanding the Discovery Mechanism

- Enabling the Management Pack

- Troubleshooting

- Monitoring a Coherence Cluster

Supported Versions

The following table lists the versions of Coherence that can be managed with Enterprise Manager Grid Control.

Table 1 Supported Versions

Supported Version

Supported JDK Version

Supported Enterprise Manager and Management Agent Version

Coherence Grid Edition and Enterprise Edition 3.4.x

JDK 1.5 and 1.6

10.2.0.5.0

Coherence Grid Edition and Enterprise Edition 3.3.x

JDK 1.5 and 1.6

10.2.0.5.0

Note:

You can only use the Management Agent 10.2.0.5.0 or later to monitor a Coherence cluster.

Understanding the Discovery Mechanism

Coherence clusters usually have a large number of nodes that run on multiple hosts. There are several types of nodes such as storage nodes, proxy nodes and management nodes. Each node runs on a JVM process. The management node hosts a JMX server and this node is used by Enterprise Manager for discovering and monitoring the coherence cluster.

The Oracle Management Agent communicates with the management node to collect metrics and propagate runtime configuration changes.

Note:

The Management Agent can be present either on the same machine on which the coherence management node is running or on a remote machine.

You have to start the management node by setting the following system properties on the storage, proxy, and application nodes:

- -Dtangosol.coherence.management=all

- -Dtangosol.coherence.management.remote=true (If this property is not to set to true, the node cannot be monitored)

For more details on enabling JMX for a Coherence cluster, refer to the Oracle® Coherence Developer's Guide for Oracle Coherence.

Configuring and Starting the Management Node Using Bulk Management MBeans

Oracle recommends that you use the Bulk MBeans shipped with Enterprise Manager to start the management node.

Ensure that the Start Management Node is included with the coherenceEMIntg.jar and the bulkoperationsmbean_11.1.1.jar provided with Enterprise Manager. If your Management Agent is on a remote location, you must copy the following files to the machine from which the management node will be started.

$ORACLE_HOME/sysman/jlib/coherenceEMIntg.jar
$ORACLE_HOME/modules/bulkoperationsmbean_11.1.1.jar

A sample script used to start the management node using the Bulk MBeans is shown below.

CLASSPATH=$COHERENCE_HOME/coherence/lib/coherence.jar
CLASSPATH=$CLASSPATH:coherenceEMIntg.jar:bulkoperationsmbean_11.1.1.jar
$JAVA_HOME/bin/java -cp $CLASSPATH $JVM_OPT $SYS_OPT oracle.sysman.integration.coherence.EMIntegrationServer > $COHERENCE_HOME/mgmtnode.log >> $COHERENCE_HOME/mgmtnode.err &

Note:

In this example, it is assumed that you are using Coherence 3.4. If you are using Coherence 3.3, you must rename coherence.jar to tangosol.jar.

To enable the connection between the Management Agent and the JMX server, you must specify the JMX port by setting the com.sun.management.jmxremote.port=portNum system property while starting the management node of the Coherence cluster.

Starting the Coherence Management Node with Security Credentials

If you use the -Dcom.sun.management.jmxremote.authenticate=true option to start the management node, you must set the User Name and Password in the jmxremote.password file and the Role in the jmxremote.access file.

- Specify the User Name and Password in the $JDK_HOME/jre/lib/management/jmxremote.password file. For example:

Column 1

Column 2

username1

coherence1

username2

coherence2

where Column 1 indicates the User Name and the Column 2 indicates the Password.

- Specify the role for each user in the $JDK_HOME/jre/lib/management/jmxremote.access file. For example:

Column 1

Column 2

username1

readonly

username2

readwrite (You must specify this role for the Coherence Management Node)

where Column 1 indicates the User Name and Column 2 indicates the Role.

Note:

To disable password authentication and SSL, start the JVM with the following properties:
com.sun.management.jmxremote.authenticate=false

com.sun.management.jmxremote.ssl=false

Discovering Oracle Coherence

1. Login to Enterprise Manager as an administrator with Add Target privilege.

2. Click on the Targets tab and click Middleware. You will see a list of middleware targets.

Figure 1 Middleware Targets Page

3. Select Oracle Coherence in the Add drop down box and click Go. The Add Oracle Application Server Target: Specify Host page is displayed.

Figure 2 Add Oracle Application Server Target: Specify Host Page

4. Enter the Host Name on which the Oracle Management Agent is running. The Add Oracle Coherence page is displayed.

Figure 3 Add Oracle Coherence Page

5. Enter the details of the Coherence cluster as follows:

Parameter

Description

Name

The unique name used for the Coherence cluster.

Machine Name

The name of the machine on which the Coherence MBean Server is running. This is the machine on which the Coherence management node is running.

JMX Remote Port

The port used for the JMX RMI connection. If you are using:

- MBean connector for Coherence MBeans, use the tangosol.coherence.management.remote.connectionport property

- The platform MBean Server for registering Coherence Mbeans, use the com.sun.management.jmxremote.port property.

User Name and Password

The credentials required for the connection.
Note: The User Name and password specified in the first column must match the User Name specified in the first column of the jmxremote.password file.

Communication Protocol

The protocol used for the connection. The default is rmi.

Service Name

The service name used for the connection. The default is jmxrmi.

Service URL

The JMX Service URL that will be used for connection. If you enter the URL, the values specified in the Machine Name, Port, Communication Protocol, and ServiceName fields will be ignored.
Example: service:jmx:rmi://localhost:3000/jndi/rmi://localhost:9000/server For more details on the URL format, refer to http://java.sun.com/j2se/1.5.0/docs/api/javax/management/remote/JMXServiceURL.html

Usage Tip: You may need to specify the Service URL only in complex cases like when the RMI registry and the MBean Server ports are different. In most other cases, the Machine Name and Port are used for the connection.

SSL TrustStore

The store where the trusted certificates are stored. This is an optional field.

Custom Lookup Provider Class

The class that implements JMXLookUp. This is used for advanced cases when the above fields are dynamic and must programatically be looked up in some LDAP server or other places. If the other fields can be specified, then this field is not required.

Bulk Operations MBeans

The full Object Name for Bulk Operations MBean. E.g.: Coherence:type=BulkOperations. If the Bulk MBean has not been registered on the MBean Server, you must leave this field blank.
Usage Tip: The Bulk MBean improves the performance of the MBean server.

Coherence Version

The current version of Coherence. The default is 3.4.
Note: If you are using versions like 3.3.x or 3.4.x, you must specify 3.3 and 3.4 respectively.

Enabling the Management Pack

You must enable the Management Pack for Oracle Coherence if you want to access additional features beyond Coherence cluster monitoring. To enable the Management Pack, do the following:

1. Log in to Enterprise Manager Grid Control. The Enterprise Manager Grid Control Home page is displayed.

2. Click Setup in the top-right corner of the page. The Overview of Setup page is displayed.

3. Click the Management Pack Access link in the left panel. The Management Pack Access page is displayed.

4. Select Oracle Coherence in the Search drop down list and click Go.

5. All the Coherence targets being monitored are displayed. Check the Pack Access Agreed check box for the Coherence target and click Apply to enable the Management Pack.

Troubleshooting

If you cannot collect metric data for the Oracle Coherence target, check the following to ensure that the steps involved in discovering the target have been followed correctly.

- Make sure that the management node has been successfully started and the host on which the management node is running is accessible from the Agent host.

- Specify the appropriate User Name and Password if password authentication is enabled.

- If you are not using SSL to start the management node, make sure that you have started the JVM using the com.sun.management.jmxremote.ssl=false option.

- If you did not use the bulk operation MBean JAR to start the management node, you must leave the Bulk Operations Mbean field blank during discovery.

- Set the correct version number which can be 3.3 or 3.4.

Monitoring a Coherence Cluster

After you have discovered the Coherence target and enabled the Management Pack Access, you can start monitoring the health and performance of the cluster by following these steps:

1. Click the Targets tab and click Middleware. The list of Middleware targets is displayed.

2. Click the Coherence Cluster link to view the Home page.

Figure 4 Coherence Home Page

Performance Page

You can get a historical view of the metric data as it is stored in the repository. By default, you can see the performance metrics for the last 24 hours in all the Performance pages. If a target has been recently added, you can view real time charts since the 24 hour performance metrics will not be available. To view the real time charts, select one of the Real Time options in the View Data drop down list in any of Performance pages.

List of Coherence Metrics Being Monitored

To view all the metrics that have been collected, click the All Metrics link under the Related Links section in the Home page. You will see the All Metrics page in which all the metrics along with their collection frequency and last collection/upload timestamp are displayed. You can click on any of the metric to get the last collected value.

Figure 5 All Metrics Page

Metric Thresholds

Enterprise Manager allows you to proactively monitor Oracle Coherence targets using various alerts. You can set critical and warning threshold values for a metric and an alert will be generated to notify you of a potential problem in the system. You can view and change the threshold values using the Metric and Policy Settings link in the Related Links section. In the Metric Thresholds page select All Metrics to view all the metrics for which you can define warning and critical thresholds.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Deaf/Hard of Hearing Access to Oracle Support Services

To reach Oracle Support Services, use a telecommunications relay service (TRS) to call Oracle Support at 1.800.223.1711. An Oracle Support Services engineer will handle technical issues and provide customer support according to the Oracle service request process. Information about TRS is available at http://www.fcc.gov/cgb/consumerfacts/trs.html, and a list of phone numbers is available at http://www.fcc.gov/cgb/dro/trsphonebk.html.

Getting Started Guide for Oracle Coherence, 10g Release 5 (10.2.0.5)

E14631-02

Copyright © 2009, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Copyright © 2009, Oracle and/or its affiliates. All rights reserved.