4 Using Oracle Coherence Reporting

This chapter provides an overview of Oracle Coherence reporting and describes how to enable and configure reporting in a cluster.

This chapter includes the following sections:

• Overview of Oracle Coherence Reporting
  
• Enabling Oracle Coherence Reporting on a Cluster Member
  
• Switching the Default Report Group Configuration File
  
• Overriding the Report Group Output Directory
  
• Changing the Report Timestamp Format
  
• Administering Oracle Coherence Reporting Using the Reporter MBean
  
• Running Oracle Coherence Reporting in a Distributed Configuration
  

4.1 Overview of Oracle Coherence Reporting

Oracle Coherence reports show key management information over time. The reports often identify trends that are valuable for troubleshooting and planning. Reporting is disabled by default and must be explicitly enabled in an operational override file or by using system properties.

Viewing Reports

The default reporting behavior creates ten reports each hour and refreshes them every minute. The reports are saved to the directory from which the cluster member starts. Each file includes a prefix with a report timestamp in a YYYYMMDDHH format. The format allows for easy location and purging of unwanted information. Table 4-1 summarizes the reports. See Analyzing Report Contents, for complete report details.

Table 4-1 Default Oracle Coherence Reports

File Name	Description
YYYYMMDDHH-cache-usage.txt	Contains cache utilization (put, get, and so on) statistics for each cache. The cache report is created only if a cache exists in the cluster.
YYYYMMDDHH-Management.txt	Contains information about the Oracle 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 cluster
YYYYMMDDHH-nodes.txt	Contains a list of members of the cluster
YYYYMMDDHH-report-proxy.txt	Contains utilization information about each proxy server in the cluster
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 Reporting Configuration

A report configuration file defines a single report. For example, the report-node.xml configuration file creates the YYYYMMDDHH-nodes.txt report. The report configuration files use Oracle Coherence MBeans to gather the data that is used in the report. The coherence.jar/reports directory includes the predefined report configuration files. See Report File Configuration Elements, for details about the report file configuration elements.

Report group configuration files control which reports to generate, how often to refresh the reports, the directory in which to save the reports, and any parameters for a report. The coherence.jar/reports directory includes three predefined report group configuration files: report-group.xml, report-web.xml, and report-all.xml. See Report Group Configuration Elements, for details about the report group configuration elements.

Customizing Reports

You can customize reporting configuration files or create new configuration files as required. A report can include data from any MBeans (including custom MBeans). See Creating Custom Reports, for detailed instructions.

4.2 Enabling Oracle Coherence Reporting on a Cluster Member

Reporting is disabled by default and must be explicitly enabled. Ensure that JMX management is enabled on the cluster member before you enable reporting. 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 saved in the directory where the cluster member starts.

Note:

Decide on a plan for archiving reports before you enable reporting.

To enable reporting, edit the operational override file and within the <reporter> element, add an <autostart> 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="coherence.management.report.autostart">true
         </autostart>
      </reporter>
   </management-config>
</coherence>

The coherence.management.report.autostart system property also enables reporting. For example:

-Dcoherence.management.report.autostart=true

4.3 Switching the Default Report Group Configuration File

Report group configuration files define which reports are generated. Three predefined report group configuration files are included in the coherence.jar/reports directory:

• report-group.xml – Configures a set of core reports to generate. This is the report group configuration file for default configuration.

• report-web-group.xml – Configures a set of Oracle Coherence*Web reports. For reports specific to Oracle Coherence*Web, see Administering HTTP Session Management with Oracle Coherence*Web.

• report-all.xml – Configures all the predefined reports to generate

To change the report group configuration file, edit the operational override file and within the <reporter> element, add a <configuration> element that is set to a report group configuration file. 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="coherence.management.report.configuration">
            reports/report-all.xml</configuration>
      </reporter>
   </management-config>
</coherence>

The coherence.management.report.configuration system property also switches the default report group configuration file. For example:

-Dcoherence.management.report.configuration=reports/report-all.xml

4.4 Overriding the Report Group Output Directory

The predefined report groups are configured by default to save reports to the directory from which the cluster member starts. The output directory can be overridden using the coherence.reporter.output.directory system property. For example:

-Dcoherence.reporter.output.directory=/mydirectory

The path can be absolute or relative to the directory where the cluster member starts (./). The user name that the member is executing must have read/write access to the path.

4.5 Changing the Report Timestamp Format

Report timestamps display the local time zone and a default time and date format (EEE MMM dd HH:mm:ss zzz yyyy). Change the time zone and time and date format as required. Enter the time zone using either a zone ID (for example, US/Eastern) or a custom ID (for example, GMT-05:00). The time and date format follow the patterns defined by the java.text.SimpleDateFormat class.

To change the report timestamp format, edit the operational override file and within the <reporter> element, add the <timezone> and <timeformat> elements 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="coherence.management.report.timezone">
            US/Eastern
         </timezone>
         <timeformat 
            system-property="coherence.management.report.timeformat">
            MMM dd, yyyy  hh:mm:ss a
         </timeformat>
      </reporter>
   </management-config>
</coherence>

The coherence.management.report.timezone and the coherence.management.report.timeformat system properties also change the report timestamp format. For example:

-Dcoherence.management.report.timezone=US/Eastern
-Dcoherence.management.report.timeformat=MMM dd, yyyy hh:mm:ss a

4.6 Administering Oracle Coherence Reporting Using the Reporter MBean

The ReporterMBean MBean administers Oracle Coherence reporting. The MBean contains attributes and operations to view JMX statistics and administer reporting in real time. See "Accessing Oracle Coherence MBeans" for instructions on how to access Oracle Coherence MBeans.

Note:

Changes that are made with the ReporterMBean MBean are not persistent. Settings revert to their original values when the cluster member restarts.

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

Figure 4-1 ReporterMBean MBean in JConsole

Description of "Figure 4-1 ReporterMBean MBean in JConsole"

The ReporterMBean MBean performs the following tasks. See "ReporterMBean" for a complete reference of the ReporterMBean MBean's attributes and operations.

• Starting reporting – Use the start operation to start reporting if it is currently stopped.

• Stopping reporting – Use the stop operation to stop reporting. Reporting restarts when the cluster member restarts if the cluster member is configured to automatically start reporting.

• Running on-demand reports – Use the runReport operation to run either a single report or a report group one time. Specify the full or relative path of a report configuration file or a report group configuration file that is located on the classpath. Ensure that reporting is enabled before you run the report. For example, enter reports/report-memory-summary.xml to run the memory summary report that is located in the coherence.jar file.

• Running on-demand tabular reports – Use the runTabularReport operation to run either a single report or a report group one time. The results are returned in a table format and display in a separate window. Ensure that reporting is enabled before you run the report.

  Specify the full or relative path of a report configuration file or a report group configuration file that is located on the classpath. For example, enter reports/report-memory-summary.xml to run the memory summary report that is located in the coherence.jar file.

  The runTabularReport operation also supports entering the XML syntax of a report or report group configuration file. Entering the XML syntax allows you to run a reports that are not on the classpath, which saves the steps of having to deploy the report or report group to all cache servers and performing a rolling restart. If you enter the XML of a report group, the individual reports must still be found on the classpath.

• Running on-demand tabular group reports – Use the runTabularGroupReport operation to run a report group one time and pass in the reports' XML syntax. The results are returned in a table format and display in a separate window. Ensure that reporting is enabled before you run the report.

• Changing the output path – Use the OutputPath attribute to change the location where reports are saved.

• Changing the refresh interval – Use the IntervalSeconds attribute to change how often the report data is refreshed.

• Changing the report configuration file – Use the ConfigFile attribute to change which report group configuration file to use.

• Changing the batch number – Use the CurrentBatch attribute to change the current batch number. The next refresh of the reports increments from the new batch number.

4.7 Running Oracle Coherence Reporting in a Distributed Configuration

A distributed configuration is for situations where cluster stability has been observed. In this configuration, the distributed reporters run independently and the execution times do not align. Therefore, cluster-level analysis is extremely difficult, but member-level analysis during periods when members may be leaving or joining the cluster is still available.

When running reporting 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:

-Dcoherence.management.report.autostart=false
-Dcoherence.management.report.distributed=true
-Dcoherence.management=all

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

-Dcoherence.management.report.autostart=true
-Dcoherence.management.report.distributed=true
-Dcoherence.management=local-only
-Dcoherence.management.remote=true