Skip Headers
Oracle® Enterprise Manager Getting Started Guide for Oracle Coherence
11g Release 1 (11.1.0.1)

E18049-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
PDF · Mobi · ePub

Oracle® Enterprise Manager

Getting Started Guide for Oracle Coherence

11g Release 1 (11.1.0.1)

E18049-02

July 2010

This document describes the procedure to discover and monitor a Coherence cluster using Oracle Enterprise Manager Grid Control 11g Release 1 (11.1.0.1).

The following sections are covered in this document:

New Features in Oracle Enterprise Manager Grid Control 11g Release 1 (11.1.0.1)

This section lists the new features in Oracle Enterprise Manager Grid Control 11g Release 1 (11.1.0.1). The new features are:

Supported Versions

Table 1 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, 11.1.0.1.0

Coherence Grid Edition and Enterprise Edition 3.3.x

JDK 1.5 and 1.6

10.2.0.5.0, 11.1.0.1.0

Coherence Grid Edition and Enterprise Edition 3.5.x

JDK 1.5 and 1.6

10.2.0.5.0, 11.1.0.1.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 MBeanServer 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:

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

Configuring and Starting a Standalone Management Node

You can configure and start the standalone management node in two ways:

  • EMIntegration Server: To start the standalone management node, you must start. the oracle.sysman.integration.coherence.EMIntegrationServer. This creates a new management node with a MBeanServer and also registers our bulk operation MBean in this MBeanServer. You can use this approach if you want to dedicate a specific node as a management node and use this exclusively for management. Before you start the EMIntegrationServer, ensure that the coherenceIntg.jar and bulkoperationmbean_11.1.1.jar files are present in the classpath of the management node. You must also set the parameter tangosol.coherence.distributed.localstorage to false so that this management node will not be used for storage. 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/coherenceIntg.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.

  • Custom-MBeans.XML: If you do not want to dedicate a specific node for management, you can use the custom-mbeans.xml to define the mbeans that need to be registered in the Coherence MBeanServer. The custom-mbeans.xml, the coherenceEMIntg.jar and bulkoperationsmbean.jar must be present in the classpath of the management node. A sample xml file is shown here:

    <mbeans>
      <mbean id="100">
        <mbean-class>oracle.as.jmx.framework.bulkoperations.BulkOperationsMBeanImpl     </mbean-class>
        <mbean-name>type=BulkOperations</mbean-name>
        <enabled>true</enabled>
      </mbean>
    </mbeans>  
    

Configuring and Starting a Management Node in WebLogic Server

If you are using Coherence Web, Coherence nodes are started when the WebLogic Server is started. To configure and start a management node in WebLogic Server, you must ensure that the Coherence node start options are part of the WLS start script. The values you specify for tangosol.coherence.management and com.sun.management.jmxremote.port parameters are used to identify the location of the CoherenceMBeanServer and how these MBeans can be accessed. You must specify the following options in the WLS start script:

  • JAVA_OPTIONS="${JAVA_OPTIONS} -Dtangosol.coherence.management=all and JAVA_OPTIONS="${JAVA_OPTIONS} -Dcom.sun.management.jmxremote.port=9937

    If this option is specified, the Coherence MBeanServer will be started in this node with an explicit port 9937. A separate MBeanServer is then created at this port and all the MBeans will be registered.

  • JAVA_OPTIONS="${JAVA_OPTIONS} -Dtangosol.coherence.management=all and no explicit value specified for the com.sun.management.jmxremote.port parameter.

    In this case, if the WebLogic Server is a WLS Administration Server, all Coherence MBeans will be registered in the WLS Domain Runtime MBeanServer. If the WLS Server is a managed server, the Runtime MBeanServer of this server will be used to register all Coherence MBeans. While discovering this Coherence Cluster, you need to specify the correct host, port, or service URL for the MBeanServer.

  • JAVA_OPTIONS="${JAVA_OPTIONS} -Dtangosol.coherence.management=none

    If this option is specified, the MBeanServer will not be started in this node. You can start a standalone management node outside the WebLogic Server.

Note:

To ensure high availability, at least two management nodes must be enabled.

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

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

    Figure 2 Add Oracle Coherence Target: Specify Host Page

    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

    Monitoring Configuration 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.5.

    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.

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. You can monitor the entire cluster or drill down to the various entities of the cluster like nodes, caches, services, connection managers, and connections. You can view the detailed home page, performance page and administration page for each entity.

Cluster Level Pages

At the cluster level, you can view the Home page for the cluster, view the performance of all nodes, caches, and connections in the cluster, and perform administrative tasks (compare and change configuration) for the different entities in the cluster.

Cluster Level Home Page

You can get a global view of the cluster from the Home page 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

    Home Page

This page contains the following sections:

  • General

  • Graphs

  • Cluster Management

  • Hosts

  • Services

  • Applications

  • Metric and Host Alerts

General

This section contains the following details:

  • Name and status of the cluster.

  • Availability %: The percentage of time that the management agent was able to communicate with the cluster.

  • License Mode: The license mode that this cluster is using. Possible values are Evaluation, Development or Production.

  • Product Edition: The product edition that this cluster is running on. Possible values are: Standard Edition (SE), Enterprise Edition (EE), Grid Edition (GE).

  • Cluster Size: This indicates the number of nodes in the cluster. A node becomes a managed node only if the Dtangosol.coherence.management.remote parameter is set to true. If nodes that do not have this parameter set are present in the cluster, the Cluster Size may not be equal to value that appears in the No. of Nodes field.

  • Number of Caches and Objects: The number of caches in the cluster and the number of objects stored in all caches in the cluster. Click on the Number of Caches link to drill down to the Cache Performance page.

  • Departed Nodes: The number of nodes that have dropped out of the cluster.

  • Publisher and Receiver Success Rates: The Publisher and Receiver success rate for this cluster node since the node statistics were last reset.

  • Number of Weak Nodes: The number of nodes that are weak and have communication and performance issues. Click on the link to drill -down to the Node Performance page.

  • Node with Max Queue Size: Indicates the node with the maximum queue size value in the cluster.

  • Node with Minimum Memory: Indicates the node with the minimum available memory in the cluster.

  • Storage Enabled Nodes: Indicates the number of nodes that are storage enabled.

  • MBean Server Node: This is the management node that is running on the MBean Server Host. Click on the link to drill down to the Node Home page.

  • Agent: The Oracle Management Agent monitoring the cluster.

  • MBean Server Host: The host on which the management node is running. If the node on the MBean Server Host is not accessible, the monitoring capability of the node will be affected. To avoid this, we recommend that at least two management nodes are running on the cluster. If a management node departs from the cluster, you must update the host and port target properties to point to the host with the running management node.

Graphs

Graphs indicating the health of the grid are displayed here. The following graphs are displayed:

  • Nodes Uptime: This graph displays groups of nodes according to their uptime. The Node Uptime is calculated as the difference between the Current Time and the Node Timestamp. Nodes that have an uptime of less than a minute are displayed in the seconds bar, nodes with an uptime of less than a hour are displayed in the minutes bar and so on.

  • Caches with Lowest Hits to Gets Ratio: This graph shows caches (up to a maximum of 5) that have lowest Hits to Gets ratio. Click on the cache name in the legend section to drill down in to the Cache Details page to further investigate the reasons for the low hits to gets ratio.

Cluster Management

In this section, you can start and stop one or more nodes, or stop a cluster. You can do the following:

  • Start New Nodes: You can start one or more nodes based on an existing node. The new node will have the same configuration as the existing node.

  • Stop Nodes: You can stop all the nodes on a specific host.

  • Stop Cluster: You can stop an entire cluster if all the hosts are managed by Enterprise Manager Grid Control.

Note:

You can set up a corrective action to start departed Coherence Nodes automatically. When a node departs, this corrective action is launched within 30 seconds and new node is automatically started on the same host if the following variables have been defined:
  • oracle.coherence.startscript: The absolute path to the start script needed to bring up a Coherence node. All customizations needed for starting this node should be in this script.

  • oracle.coherence.home: The absolute path to the location in which the coherence folder is present which is $INSTALL_DIR/coherence. This folder contains Coherence binaries and libraries.

Hosts

This section shows all the hosts on which nodes in this cluster are running. For each host, you can see the number of coherence nodes running on the host, and the percentage of CPU and Memory Used.

Services

This section shows all the services in the grid. You can view the type of service (Cluster Service, Distributed Cache Service, Invocation Service, and Replicated Cache Service), status of the service (Machine-Safe, Node-Safe, and Endangered), the number of nodes in the service, storage enabled nodes, and endangered nodes.

Applications

This section shows the applications that use this Coherence cluster to cache their HTTPSession Objects. You can view details of the Local Cache, Overflow Cache, and Servlet Context Cache.

Metric and Host Alerts

This section lists the alerts from all types of entities in the cluster; nodes, caches, services, connections and connection managers, along with their severity and the date on which the alert was triggered. The alerts are generated based on the thresholds defined in the Metrics Collection file. To configure these threshold values, click the Metrics and Policy Settings link in the Related Links section.Refer to the Online Help for detailed information on the parameters displayed in the screen.

Cluster Level Node Performance Page

You can get a historical view of the metric data as it is stored in the repository. This page displays the performance of all the nodes in the cluster over a specified period of time. You can see charts showing the top nodes with lowest available memory, maximum send queue size, maximum puts, and maximum gets. By default, you can see the average 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. Using the View Data options, you can also view the average performance metrics for the last 7 or 31 days.

The Node Performance page tab shows the performance of all nodes in this cluster. If you click on a link that shows multiple nodes like weak nodes, storage nodes, etc., the performance of the selected nodes will be displayed on this page. You can toggle between the two modes to see the performance of the selected nodes or all the nodes.

Figure 5 Node Performance Page

Surrounding text describes Figure 5 .

Cluster Level Cache Performance Page

This page displays the cache related performance over a specified period of time. You can view the performance of the top caches or all the caches. If you select the All Caches option, you can see the total and average metric values over the selected period of time. Figure 6 shows the performance of the top caches in the cluster.

Figure 6 Cache Performance Page

Surrounding text describes Figure 6 .

Select the All Caches option from the drop down list to view the performance of all the caches in the cluster.

Other Cluster Level Pages

You can also do the following:

  • Connection Performance: View the performance of the top connections and connection managers with Most Bytes Sent and Most Bytes Received in the Connection Performance page.

  • Administration: Perform administrative tasks like comparing two entities and changing the configuration of one or more entities.

Detailed Pages

From the cluster level pages, you can drill down to the pages for each entity in the cluster.

Home Pages

From cluster level pages, you can click on any hyperlink and drill down to the detailed home pages for the different entities such as node, cache, service, connection manager and connection. Hyperlinks from one entity allow you to go to another entity. For example, you can view all the nodes of a cache in the Cache Detailed page, identify the node that is not contributing well for this cache, click on the node hyperlink and drill down to the Node Detailed page for further investigation. You can compare that node configuration with other nodes and change its runtime configuration if required.

Figure 7 Node Detailed Home Page

Surrounding text describes Figure 7 .

Performance Pages

Entity level performance pages give detailed views of the performance of this particular entity. For nodes and caches, there are two views - Charts and Metrics. You can select the option from the View drop-down list.

Node Performance Details Page

'

This page displays the performance of a specific node over a specified period of time. You can view either the charts or the actual metrics by selecting the appropriate option from the View drop down list. If you select Charts option, you can see the average gets, puts, memory available, send queue size, and publisher and receiver success rates over the selected period of time. If you select the Metrics option, you can see the total and average metric values over the selected period of time. Figure 8 shows the graphs or charts for the selected node.

Figure 8 Node Performance Details Page (Charts View)

Surrounding text describes Figure 8 .

If you select the Metrics option, you will see the metric data as shown in Figure 9.

Figure 9 Node Performance Details Page (Metrics View)

Node Performance Details Page (Metrics View)
Cache Performance Details Page

This page displays the performance of a specific cache over a specific period of time. You can view charts showing the number of cache hits, misses, store reads, and store writes. You can also see the aggregated totals and average metric values over the selected period of time.

Figure 10 Cache Performance Details Page (Charts View)

Surrounding text describes Figure 10 .

Each chart in Figure 10 shows the aggregated value for the cache and the top nodes (up to a max of 5) that are worth observing for this metric. For example, Memory Consumed chart shows an aggregated value for the cache and the top 5 nodes that have maximum memory value across all its nodes. Using the chart legend, you can drill down in to the node detailed pages for further investigation.

Figure 11 Cache Performance Details Page (Metrics View)

Surrounding text describes Figure 11 .

In Figure 11, you can see the performance from all the nodes that are supporting this cache. You can sort the columns in these tables to identify the nodes that are not contributing well for a specific metric and drill down to the detailed pages for the node.

Apart from these pages, the detailed pages for the following entities are also available:

  • Service Performance Details Page: This page displays the performance of the selected service over a specific period of time. The Request Average Duration and the Request Max Duration charts are displayed. You can also see the average metric values over the selected period of time.

  • Connection Manager and Connection Performance Details Page: These pages displays the performance of the selected connection or connection manager.

Administration Pages

You can drill down to the Administration page for a specific node, cache, connection, or connection manager. You can change configuration for a specific entity, or compare configurations for two entities in the cluster. Figure 12 shows the Node Administration page.

Figure 12 Node Administration Page

Surrounding text describes Figure 12 .

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 13 All Metrics Page

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, 11g Release 1 (11.1.0.1)

E18049-02

Copyright © 2010 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.