This chapter describes JMX reporting and provides instructions for enabling and configuring JMX reporting.
The following sections are included in this chapter:
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.
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."
Contains cache utilization (put, get, and so on) statistic for each cache. This report is only created if a cache exists on the cluster.
Contains information about the Coherence management framework.
Contains memory and garbage collection information about each member.
Contains the publisher success rates and receiver success rates for each member.
Contains the publisher success rates and receiver success rates for the entire grid.
Contains a list of members of the grid.
Contains utilization information about each proxy server in the grid.
Contains Request and Task information for each service.
Contains usage and performance information for flash-based storage.
Contains usage information for RAM-based storage.
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
-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
report-group.xml – configures a set of core coherence reports to be generated. This is the report group configuration file that is used by the default configuration.
report-web.xml – configures a set of Coherence*Web reports. For reports specific to Coherence*Web, see Oracle Coherence User's Guide for Oracle Coherence*Web.
report-all.xml – configures all the out-of-box reports to be generated.
See Appendix C, "Report Group Configuration Reference," for details about the report group configuration elements.
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.
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>
tangosol.coherence.management.report.autostart system property is used to enable JMX reporting instead of using the operational override file. For example:
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>
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:
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
To change the report timestamp format, edit the operational override file and add the
<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>
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
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
ReporterMBeanMBean 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.
The following tasks can be performed using the
ReporterMBean MBean. See "ReporterMBean" for a complete reference of the
ReporterMBean MBean's attributes and operations.
Starting JMX Reporting – Use the
start operation to start JMX reporting if it is currently stopped.
Stopping JMX Reporting – Use the
stop operation to stop JMX reporting. JMX reporting is restarted when the cluster member is restarted if the cluster member is configured to automatically start JMX reporting.
Running JMX Reporting on Demand – Use the
runReport operation to run either a single report or a report group one time. A report configuration file or report group configuration file must be specified. In addition, JMX reporting must be started to run the report(s).
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 is incremented from the new batch number.
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