Skip Headers
Oracle® Coherence Management Guide
Release 3.7.1

Part Number E22842-01
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
Go to next page
Next
View PDF

4 Using JMX Reporting

This chapter describes JMX reporting and provides instructions for enabling and configuring JMX reporting.

The following sections are included in this chapter:

4.1 Overview of JMX Reporting

JMX reports are used to view key management information over time. The reports are most often used to identify trends that are valuable for troubleshooting and planning. JMX reporting is disabled by default and must be explicitly enabled in an operational override file or by using system properties.

Viewing Reports

By default, ten reports are created each hour and refreshed every minute. The reports are written out to the directory where the cluster member was started. Each file is prefixed with the date and hour the report was executed in a YYYYMMDDHH format. This allows for easy location and purging of unwanted information. The files generated are described in Table 4-1 and detailed in Chapter 6, "Analyzing Reporter Content."

Table 4-1 Default JMX Reports

File Name Description

YYYYMMDDHH-cache-usage.txt

Contains cache utilization (put, get, and so on) statistic for each cache. This report is only created if a cache exists on the cluster.

YYYYMMDDHH-Management.txt

Contains information about the Coherence management framework.

YYYYMMDDHH-memory-status.txt

Contains memory and garbage collection information about each member.

YYYYMMDDHH-network-health-detail.txt

Contains the publisher success rates and receiver success rates for each member.

YYYYMMDDHH-network-health.txt

Contains the publisher success rates and receiver success rates for the entire grid.

YYYYMMDDHH-nodes.txt

Contains a list of members of the grid.

YYYYMMDDHH-report-proxy.txt

Contains utilization information about each proxy server in the grid.

YYYYMMDDHH-service.txt

Contains Request and Task information for each service.

YYYYMMDDHH-flashjournal.txt

Contains usage and performance information for flash-based storage.

YYYYMMDDHH-ramjournal.txt

Contains usage information for RAM-based storage.


Understanding JMX Reporting Configuration

JMX reports are defined within a report configuration file. The predefined report configuration files are located in the /reports directory of the coherence.jar library. Each report configuration file results in a JMX report being created. For example, the report-node.xml configuration file is used to create the YYYYMMDDHH-nodes.txt report. The report configuration files use Coherence MBeans to gather the data that is used in the report. See Appendix B, "Report File Configuration Reference," for details about the report file configuration elements.

Report group configuration files are used to control which reports are generated, how often the reports are refreshed, the directory where the reports are saved, and any parameters for a report. Three predefined report group configuration files are included out-of-box and are located in the /reports directory of the coherence.jar file:

See Appendix C, "Report Group Configuration Reference," for details about the report group configuration elements.

Customizing Reports

The predefined reporting configuring files can be customized and new configuration files can be created as required. Any MBeans that are registered in the Coherence MBean server (including custom MBeans) can have their data displayed within a report. Chapter 5, "Creating Custom Reports," for detailed instructions.

4.2 Enabling JMX Reporting On a Cluster Member

JMX reporting must be enabled before JMX reports are created. JMX reporting can only be enabled on a cluster member where JMX management has also been enabled. See "Configuring JMX Management" for details on enabling JMX management on a cluster member. The default reporting configuration creates a set of reports each hour and refreshes the reports every minute. The reports are written out to the directory where the cluster member was started.

Note:

Decide on a plan for archiving reports before enabling JMX reporting.

To enable JMX reporting, edit the operational override file and add an <autostart> element, within the <reporter> element, that is set to true. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <reporter>
         <autostart
            system-property="tangosol.coherence.management.report.autostart">true
         </autostart>
      </reporter>
   </management-config>
</coherence>

The tangosol.coherence.management.report.autostart system property is used to enable JMX reporting instead of using the operational override file. For example:

-Dtangosol.coherence.management.report.autostart=true

4.3 Switching the Default Report Group Configuration File

Report group configuration files are used to define which reports get generated. Three report group configuration files are included out-of-box and are used to generate predefined reports: report-group.xml (default- generates core reports), report-web.xml (generates Coherence*Web reports), and report-all.xml (generates all reports).

To change the report group configuration file, edit the operational override file and add a <configuration> element, within the <reporter> element, that is set to a report group configuration files. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <reporter>
         <configuration
            system-property="tangosol.coherence.management.report.configuration">
            reports/report-all.xml</configuration>
      </reporter>
   </management-config>
</coherence>

The tangosol.coherence.management.report.configuration system property is used to switch the default report group configuration file instead of using the operational override file. For example:

-Dtangosol.coherence.management.report.configuration=reports/report-all.xml

4.4 Changing the Report Timestamp Format

Timestamps that are displayed within a report use the local time zone and a default time and date format (EEE MMM dd HH:mm:ss zzz yyyy). The time zone and time and date format can be changed as required. The time zone is entered using either a zone ID (for example, US/Eastern) or a custom ID (for example, GMT-05:00). The time and date format must follow the patterns specified by the java.text.SimpleDateFormat class.

To change the report timestamp format, edit the operational override file and add the <timezone> and <timeformat> elements, within the <reporter> element, that are set to the time zone and time and date format, respectively. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <reporter>
         <timezone 
            system-property="tangosol.coherence.management.report.timezone">
            US/Eastern
         </timezone>
         <timeformat 
            system-property="tangosol.coherence.management.report.timeformat">
            MMM dd, yyyy  hh:mm:ss a
         </timeformat>
      </reporter>
   </management-config>
</coherence>

The tangosol.coherence.management.report.timezone and the tangosol.coherence.management.report.timeformat system properties are used to change the report timestamp format instead of using the operational override file. For example:

-Dtangosol.coherence.management.report.timezone=US/Eastern
-Dtangosol.coherence.management.report.timeformat=hh:mm:ss a

4.5 Administering JMX Reporting Using the Reporter MBean

JMX reporting is administered using the ReporterMBean MBean. The MBean contains attributes and operations that are used to view JMX statistics and administer JMX reporting in real time. See "Accessing Coherence MBeans" for instructions on how to access Coherence MBeans.

Note:

Attributes that are changed using the ReporterMBean MBean are not saved and revert back to their original settings when the cluster member is restarted.

Figure 4-1 shows the ReporterMBean MBean's attributes and operations within JConsole.

Figure 4-1 ReporterMBean MBean in JConsole

ReporterMBean in JConsole

The following tasks can be performed using the ReporterMBean MBean. See "ReporterMBean" for a complete reference of the ReporterMBean MBean's attributes and operations.

4.6 Running JMX Reporting in a Distributed Configuration

A distributed configuration is only recommended in situations where grid stability is an issue. In this configuration, the distributed reporters run independently and the execution times do not align. Therefore, grid level analysis is extremely difficult but member level analysis during periods when members may be leaving or joining the grid is still available.

When running in distributed mode, each member logs local JMX statistics while allowing for centralized management of the Reporters. To enable distributed configuration:

Start the managing member using the following system properties:

-Dtangosol.coherence.management.report.autostart=false
-Dtangosol.coherence.management.report.distributed=true
-Dtangosol.coherence.management=all
-Dcom.sun.management.jmxremote

Start the cluster member to be managed using the following system properties:

-Dtangosol.coherence.management.report.autostart=true
-Dtangosol.coherence.management.report.distributed=true
-Dtangosol.coherence.management=local-only
-Dtangosol.coherence.management.remote=true