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 Chapter 6, "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 Appendix B, "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 Appendix C, "Report Group Configuration Elements," for details about the report group configuration elements.

Customizing Reports

Customize reporting configuration files or create new configuration files as required. A report can include data from any MBeans (including custom MBeans). See Chapter 5, "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="tangosol.coherence.management.report.autostart">true
         </autostart>
      </reporter>
   </management-config>
</coherence>

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

-Dtangosol.coherence.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.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="tangosol.coherence.management.report.configuration">
            reports/report-all.xml</configuration>
      </reporter>
   </management-config>
</coherence>

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

-Dtangosol.coherence.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 tangosol.coherence.reporter.output.directory system property. For example:

-Dtangosol.coherence.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="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 also change the report timestamp format. For example:

-Dtangosol.coherence.management.report.timezone=US/Eastern
-Dtangosol.coherence.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 either a report configuration file or a report group configuration file. In addition, 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 is an issue. 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:

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

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