Using Oracle Coherence Reporting

5 Using Oracle Coherence Reporting

Oracle Coherence provides a reporting feature that collects management data and generates a series of reports that are updated at regular intervals. Reporting supports many configuration options, such as controlling which reports get generated, where the reports are saved, and how often the report data is refreshed.

This chapter includes the following sections:

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.
Enabling Oracle Coherence Reporting on a Cluster Member
Reporting is disabled by default and must be explicitly enabled. You can edit the reporting configuration to enable reporting on a cluster member and generate management reports.
Switching the Default Report Group Configuration File
You can control which reports are generated by specifying a different report group configuration file.
Overriding the Report Group Output Directory
You can configure the output directory on a cluster member where reports are saved.
Changing the Report Timestamp Format
The report time zone and time and date format can be change as required.
Administering Oracle Coherence Reporting Using the Reporter MBean
The ReporterMBean MBean provides a convenient way to manage Coherence reporting and perform common reporting tasks.
Running Oracle Coherence Reporting in a Distributed Configuration
Distributed reporting configures each member to log only local JMX statistics while allowing for centralized management of the reporters.

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.

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 5-1 summarizes the reports.

Table 5-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.txt`	Contains the publisher success rates and receiver success rates for the entire cluster
`YYYYMMDDHH-network-health-detail.txt`	Contains the publisher success rates and receiver success rates for each member
`YYYYMMDDHH-nodes.txt`	Contains a list of members of the cluster
`YYYYMMDDHH-persistence.txt`	Contains cache persistence information for a particular service
`YYYYMMDDHH-persistence-detail.txt`	Contains cache persistence information for a particular service and node
`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

Parent topic: Using Oracle Coherence Reporting

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.

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-group.xml, and report-all.xml. See Report Group Configuration Elements.

Parent topic: Overview of Oracle Coherence Reporting

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.

Parent topic: Overview of Oracle Coherence Reporting

Enabling Oracle Coherence Reporting on a Cluster Member

Reporting is disabled by default and must be explicitly enabled. You can edit the reporting configuration to enable reporting on a cluster member and generate management reports. Ensure that JMX management is enabled on the cluster member before you enable reporting. See Configuring JMX Management.

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

Parent topic: Using Oracle Coherence Reporting

Switching the Default Report Group Configuration File

You can control which reports are generated by specifying a different report group configuration file.

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. See Running Performance Reports in 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

Parent topic: Using Oracle Coherence Reporting

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. You can configure the output directory on a cluster member where reports are saved.

The output directory is 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.

Parent topic: Using Oracle Coherence Reporting

Changing the Report Timestamp Format

The report time zone and time and date format can be change as required. Report timestamps display the local time zone and a default time and date format (EEE MMM dd HH:mm:ss zzz yyyy). 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

Parent topic: Using Oracle Coherence Reporting

Administering Oracle Coherence Reporting Using the Reporter MBean

The ReporterMBean MBean provides a convenient way to manage Coherence reporting and perform common reporting tasks.

The MBean contains many attributes and operations for administering reporting in real time. See Accessing 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.

The ReporterMBean MBean performs the following tasks:

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.

Figure 5-1 shows the ReporterMBean MBean attributes and operations within JConsole. See also Reporter MBean.

Figure 5-1 ReporterMBean MBean in JConsole

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

Parent topic: Using Oracle Coherence Reporting

Running Oracle Coherence Reporting in a Distributed Configuration

Distributed reporting configures each member to log only local JMX statistics while allowing for centralized management of the reporters. A distributed configuration is intended for situations where cluster stability has been observed. In this configuration, the execution times of the reports on each cluster member 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.

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

Parent topic: Using Oracle Coherence Reporting