You can create your own reports in addition to using the predefined reports that are included with Coherence. Custom reports allow you to decide what management data to display and how the data is organized and processed.
This chapter includes the following sections:
coherence-report-config.xsd file.coherence-report-group-config.xsd file.Report Configuration Files
Tip:
Extract the predefined reporting configuration files from the coherence.jar/reports directory before creating custom reports. Use the files as a starting point for creating custom reports.
Oracle Coherence reporting utilizes two types of configuration files: a report configuration file and a report group configuration file.
Report configuration file – A report configuration file constructs a report at run time. The file includes the name of the report, the MBean data to extract, and the organization of the data. Each report has a corresponding report configuration file. Report configuration files are XML documents that are defined by the coherence-report-config.xsd schema file, which is packaged in the root directory of the coherence.jar library.
Report group configuration file – A report group configuration file configures which reports to generate at run time. The file includes the name and location of each report configuration file, the output directory where to save the reports, and how often to refresh the reports. Report group configuration files are XML documents that are defined by the coherence-report-group-config.xsd schema file, which is packaged in the root directory of the coherence.jar library.
coherence-report-config.xsd file. See Report File Configuration Elements.This section includes the following topics:
Table 5-1 describes the elements that configure general report characteristics.
Table 5-1 General Report Elements
| Element | Optional/ Required | Description |
|---|---|---|
|
|
Required |
The file name to create or update when the report is saved |
|
|
Optional |
The column delimiter for the report. Valid values are |
|
|
Optional |
A Boolean element to determine whether to hide headers in the report. If |
This section includes the following topics:
Table 5-2 describes the macros predefined for use with the file-name element. These macros add a member name, a batch number, or a date to the file name.
Table 5-2 Macros for file-name Element
| Macro | Description |
|---|---|
|
|
Adds a sequence number to the file name of the report |
|
|
Adds the date (in the |
|
|
Adds the member ID to the file name. The node setting is helpful when many members are executing the same report and the output files are integrated for analysis. |
The following example creates a file named 200901012_network_status.txt on January 1, 2009, during hour 12. The file name changes with the system time on the member executing the report.
<file-name>{date}_network_status.txt</file-name>
The following example creates a file named 00012_network_status.txt when the report is executed on member 12. Due to the volatile nature of the node ID, only use this macro during short-term analysis.
<file-name>{node}_network_status.txt</file-name>
The following example creates a file named 0000000021_network_status.txt on the 21st execution of the report. Due to the volatile nature of the batch, only use this macro during short-term analysis.
<file-name>{batch}_network_status.txt</file-name>
A query is the foundation of a report's information. The query pattern is a JMX ObjectName query string. The string can return one or more MBeans that are used to construct the report's data. Queries can be defined for the whole report or within specific columns in a report. A wild card (*) is often used to match multiple MBeans. Example 5-1 returns all registered Service MBeans. See query.
Example 5-1 Simple MBean Query String
<query> <pattern>Coherence:type=Service,*</pattern> </query>
Queries can use a filter definition and can also use column and filter references. See Using Filters in Reports. Example 5-2 demonstrates how to reference a filter in a query and illustrates how to list all the node IDs and role names in the cluster where RoleName equals CoherenceServer.
Example 5-2 Including a List of the Cluster's Node IDs and Role Names in a Report
<filters>
<filter id="equalsRef">
<type>equals</type>
<params>
<column-ref>RoleRef</column-ref>
<column-ref>StringRef</column-ref>
</params>
</filter>
</filters>
<query>
<pattern>Coherence:type=Node,*</pattern>
<filter-ref>equalsRef</filter-ref>
</query>
<row>
<column id ="NodeRef">
<type>key</type>
<name>nodeId</name>
<header>Node Id</header>
</column>
<column id ="RoleRef">
<name>RoleName</name>
<header>Role</header>
</column>
<column id = "StringRef">
<type>constant</type>
<name>ConstString</name>
<hidden>true</hidden>
<data-type>string</data-type>
<value>CoherenceServer</value>
</column>
</row>Data columns can use JMX attributes, ObjectName key part, JMX composite attributes, JMX joined attributes, report macros, and report constants.
This section includes the following topics:
To include data that is returned from a query-pattern, the report must have a column with an attribute source. This is the most common way to include data in a report.
Example 5-3 illustrates how to include the RoleName attribute from the query pattern Coherence:type=Node,*.
Example 5-3 Including an Attribute Obtained from a Query Pattern
<column id = "RoleName"> <type>attribute</type> <name>RoleName</name> <header>Role Name</header> </column>
A value that is present in an ObjectName key can be obtained from the ObjectName that is returned from the query-pattern. This value can subsequently be included in the report.
Example 5-4 illustrates how to include the nodeId key part from the query pattern Coherence:type=Node,*.
Example 5-4 Including Part of an ObjectName Key in a Report
<column id ="NodeId"> <type>key</type> <name>nodeId</name> <header>Node Id</header> </column>
Use JMX composite values to include part of a composite data attribute (such as a Map attribute) in a report.
Example 5-5 illustrates how to include the startTime of the LastGCInfo attribute from the GarbageCollector MBean.
Example 5-5 Including Information from a Composite Attribute in a Report
<query> <pattern>Coherence:type=Platform,Domain=java.lang,subType=GarbageCollector, name=ParNew,*</pattern> </query> <column id="LastGCStart"> <type>attribute</type> <name>LastGcInfo/startTime</name> <header>Last GC Start Time</header> </column>
Use a JMX join attribute when a report requires information from multiple MBeans. The major consideration when creating a join is to determine the primary query, the join query, and the foreign key. The primary query is the query that returns the appropriate number of rows for the report. The join query pattern must reference a single MBean and cannot contain a wildcard (*). The foreign key is determined by what attributes from the primary query are required to complete the join query string.
The reporter feature that enables joins between MBeans is a column substitution macro. The column substitution allows the resulting value from a column to be included as part of a string. A column substitution macro is a column ID attribute surrounded by braces ({}). The reporter does not check for cyclical references and fails during execution if a cycle is configured.
A report can use information from multiple MBeans. This requires a join between the MBeans.
Note:
The major limitation of join attributes is that the result of the join must have only one value.
For example, if a report requires the TotalGets from the Cache MBean (Coherence:type=cache,*) and RoleName from the Node MBean (Coherence:type=Node,*), then use a join attribute.
Because more MBeans come from the Cache MBean than other MBeans, Coherence:type=Cache,* is the primary query and RoleName is the join attribute. The foreign key for this join is the nodeId key part from the Cache MBean, and it must be included in the report. Example 5-6 shows the configuration for this scenario.
Example 5-6 Including Information from Multiple MBeans in a Report
<column id="RoleName">
<type>attribute</type>
<name>RoleName</name>
<header>Role Name</header>
<query>
<pattern>Coherence:type=Node,nodeId={NodeFK}</pattern>
</query>
</column>
<column id ="NodeFK">
<type>key</type>
<name>nodeId</name>
<header>Node Id</header>
</column>
A report includes three report macros:
Report Time (report-time) – The time and date for the report. This information is useful for time series analysis.
Report Batch/Count (report-count) – A long identifier to correlate information from different reports executed at the same time.
Reporting Member (report-node) – A member identifier to integrate information from the same report executed on different members or to exclude the executing member information from the report.
Example 5-7 illustrates how to include the execution time into the report.
Example 5-7 Including Execution Time in a Report
<column id ="ReportTime">
<type>global</type>
<name>{report-time}</name>
<header>Report Time</header>
</column>
Example 5-8 illustrates how to include the Report Batch/Count.
Example 5-8 Including the Report Batch/Count in a Report
<column id="ReportBatch">
<type>global</type>
<name>{report-count}</name>
<header>batch</header>
</column>
Example 5-9 illustrates how to include the execution member.
Example 5-9 Including the Execution Member
<column id="ReportNode">
<type>global</type>
<name>{report-node}</name>
<header>ExecNode</header>
<hidden>false</hidden>
</column>Static values or report parameters can use report constants. These constants are either double or string values. Often, filters use constant values to limit the results to a particular data set or in calculations.
Example 5-10 illustrates how to include a constant double of 1.0 in a report.
Example 5-10 Including a Constant Numeric Value in a Report
<column id ="One"> <type>constant</type> <header>Constant1</header> <hidden>false</hidden> <data-type>double</data-type> <value>1.0</value> </column>
Example 5-11 illustrates how to include the constant string dist-Employee in a report.
Example 5-11 Including a Constant String in a Report
<column id ="EmployeeCacheName"> <type>constant</type> <header>Employee Cache Name</header> <hidden>false</hidden> <data-type>string</data-type> <value>dist-Employee</value> </column>
Filters limit the data in reports. Filters are either comparison filters or composite filters. Comparison filters evaluate the results of two columns. Comparison filters are equals, greater, and less.
Composite filters evaluate the Boolean results from one or two filters. Composite filter types are and, or, and not. Each composite filter evaluates the filter parameters first to last and applies standard Boolean logic. Composite filter evaluation uses standard short-circuit logic. The use of cyclic references creates a run-time error.
Example 5-12 illustrates how to define an equals filter where RoleRef and StringRef are defined columns.
Example 5-12 Using an Equals Filter for a Report
<filters>
<filter id="equals">
<type>equals</type>
<params>
<column-ref>RoleRef</column-ref>
<column-ref>StringRef</column-ref>
</params>
</filter>
</filters>
Example 5-13 illustrates how to define a filter in which the value of PacketsResent is greater than the value of PacketsSent (assuming that PacketsResent and PacketsSent are valid column references).
Example 5-13 Defining a "Greater Than" Filter for a Report
<filters>
<filter id="greaterRef">
<type>greater</type>
<params>
<column-ref>PacketsResent</column-ref>
<column-ref>PacketsSent</column-ref>
</params>
</filter>
</filters>
Example 5-14 illustrates how to define a filter in which the value of PacketsResent is less than the value of PacketsSent (assuming that PacketsResent and PacketsSent are valid column references).
Example 5-14 Defining a "Less Than" Filter for a Report
<filters>
<filter id="greaterRef">
<type>less</type>
<params>
<column-ref>PacketsResent</column-ref>
<column-ref>PacketsSent</column-ref>
</params>
</filter>
</filters>
Example 5-15 illustrates how to define an and filter (assuming that all column-ref values are valid).
Example 5-15 Defining an "And" Filter for a Report
<filters>
<filter id="equalsRef">
<type>equals</type>
<params>
<column-ref>RoleRef</column-ref>
<column-ref>StringRef</column-ref>
</params>
</filter>
<filter id="greaterRef">
<type>greater</type>
<params>
<column-ref>PacketsResent</column-ref>
<column-ref>PacketsSent</column-ref>
</params>
</filter>
<filter>
<type>and</type>
<params>
<filter-ref>greaterRef</filter-ref>
<filter-ref>equalsRef</filter-ref>
</params>
</filter>
</filters>
Example 5-16 illustrates how to define an or filter (assuming that all column-ref values are valid).
Example 5-16 Defining an "Or" Filter for a Report
<filters>
<filter id="equalsRef">
<type>equals</type>
<params>
<column-ref>RoleRef</column-ref>
<column-ref>StringRef</column-ref>
</params>
</filter>
<filter id="greaterRef">
<type>greater</type>
<params>
<column-ref>PacketsResent</column-ref>
<column-ref>PacketsSent</column-ref>
</params>
</filter>
<filter>
<type>or</type>
<params>
<filter-ref>greaterRef</filter-ref>
<filter-ref>equalsRef</filter-ref>
</params>
</filter>
</filters>
Example 5-17 illustrates how to define a not equals filter, where RoleRef and StringRef are defined columns.
Example 5-17 Defining a "Not Equals" Filter for a Report
<filters>
<filter id="equals">
<type>equals</type>
<params>
<column-ref>RoleRef</column-ref>
<column-ref>StringRef</column-ref>
</params>
</filter>
<filter id = "Not">
<type>not</type>
<params>
<filter-ref>equals</filter-ref>
</params>
</filter>
</filters>
Reporter functions allow mathematical calculations to be performed on data elements within the same row of the report. The supported functions are Add, Subtract, Multiply, and Divide. Function columns can include (as parameters) other function columns.
This section includes the following topic:
Example 5-18 illustrates how to add two column values (Attribute1 and Attribute2) and place the results into a third column (Addition).
Example 5-18 Adding Column Values and Including Results in a Different Column
<column id="AttributeID1">
<name>Attribute1</name>
</column>
<column id="AttributeID2">
<name>Attribute2</name>
</column>
<column id="Addition">
<type>function</type>
<name>Add2Columns</name>
<header>Adding Columns</header>
<function-name>add</function-name>
<params>
<column-ref>AttributeID1</column-ref>
<column-ref>AttributeID2</column-ref>
</params>
</column>
Example 5-19 illustrates how to subtract one column value (Attribute2) from another column value (Attribute1) and place the results into a third column (Subtraction).
Example 5-19 Subtracting Column Values and Including Results in a Different Column
<column id="AttributeID1">
<name>Attribute1</name>
</column>
<column id="AttributeID2">
<name>Attribute2</name>
</column>
<column id="Subtraction">
<type>function</type>
<name>Subtract2Columns</name>
<header>Difference</header>
<function-name>subtract</function-name>
<params>
<column-ref>AttributeID1</column-ref>
<column-ref>AttributeID2</column-ref>
</params>
</column>
Example 5-20 illustrates how to multiply two column values (Attribute1 and Attribute2) and place the results into a third column (Multiplication).
Example 5-20 Multiplying Column Values and Including Results in a Different Column
<column id="AttributeID1">
<name>Attribute1</name>
</column>
<column id="AttributeID2">
<name>Attribute2</name>
</column>
<column id="Multiplication">
<type>function</type>
<name>Multiply2Columns</name>
<header>Multiply Columns</header>
<function-name>multiply</function-name>
<params>
<column-ref>AttributeID1</column-ref>
<column-ref>AttributeID2</column-ref>
</params>
</column>
Example 5-21 illustrates how to divide one column value (Attribute1) by another (Attribute2) and place the results into a third column (Division). The result of all division is a Double data type.
Example 5-21 Dividing Column Values and Including Results in a Different Column
<column id="AttributeID1">
<name>Attribute1</name>
</column>
<column id="AttributeID2">
<name>Attribute2</name>
</column>
<column id="Division">
<type>function</type>
<name>Dividing2Columns</name>
<header>Division</header>
<function-name>divide</function-name>
<params>
<column-ref>AttributeID1</column-ref>
<column-ref>AttributeID2</column-ref>
</params>
</column>
Reporter aggregates combine multiple rows into a single value or row. Table 5-3 describes the available aggregate types.
Table 5-3 Reporter Aggregate Types
| Type | Description |
|---|---|
|
avg |
Calculate the mean value for all values in the column. |
|
max |
Return the maximum value for all values in the column. |
|
min |
Return the minimum value for all values in the column. |
|
sum |
Add all the values from a column. |
Example 5-22 illustrates how to sum the values in the size column.
Example 5-22 Adding the Values in a Column
<column id ="SumRef"> <type>function</type> <column-ref>size</column-ref>> <function-name>sum</function-name> <header>Sum</header> </column>
Example 5-23 illustrates how to average the values in the size column.
Example 5-23 Calculating the Average of Values in a Column
<column id ="AverageRef"> <type>function</type> <header>Average</header> <column-ref>size</column-ref> <function-name>avg</function-name> </column>
Example 5-24 illustrates how to find the maximum value in the size column.
Example 5-24 Finding the Maximum Value in a Column
<column id ="MaximumRef"> <type>function</type> <header>Maximum</header> <column-ref>size</column-ref> <function-name>max</function-name> </column>
Example 5-25 illustrates how to find the minimum value in the size column.
Example 5-25 Finding the Minimum Value in a Column
<column id ="MinimumRef"> <type>function</type> <header>Minimum</header> <column-ref>size</column-ref> <function-name>min</function-name> </column>
Many numeric attributes in a report are cumulative. These values are reset only when the resetStatistics operation is executed on the MBean. To determine the state of the system without resetting the statistics, the reporter uses a delta function. The delta function subtracts the prior value of a column from the current value of a column and returns the difference.
A map on the reporter client stores the prior values for a report. This map is keyed by the delta key. By default, the delta key is the MBean name for the attribute. However, when a one-to-one relationship does not exist between the MBean and the rows in the report, or the MBean name is subject to change between executions of the report, the delta key is calculated using the columns provided in the <params> section.
Note:
Delta functions are only correct when the report is running as part of a report batch.
This section includes the following topic:
Example 5-26 illustrates how to include a delta calculation of an attribute. (Assume that PacketsSent is a defined column.)
Example 5-26 Delta Calculation for an Attribute
<column id="DeltaPacketsSent"> <type>function</type> <name>PacketsSent</name> <header>Delta Sent</header> <column-ref>PacketsSent</column-ref> <function-name>delta</function-name> </column>
Example 5-27 illustrates how to include a delta calculation of an attribute with an alternate delta key. (Assume that PacketsSent, NodeID, and TimeStamp are defined columns.)
Example 5-27 Delta Calculation for an Attribute with an Alternate Delta Key
<column id="DeltaPacketsSent">
<type>function</type>
<name>PacketsSent</name>
<header>Delta Sent</header>
<column-ref>PacketsSent</column-ref>
<function-name>delta</function-name>
<params>
<column-ref>NodeID</column-ref>
<column-ref>TimeStamp</column-ref>
</params>
</column>
coherence-report-group-config.xsd file. See Report Group Configuration Elements. This configuration file is used at run time to determine what reports to generate, how often to refresh the reports, and where to save the reports. The report group configuration file also configures report parameters if required.This section includes the following topics:
The <frequency> element specifies how often to refresh reports. Selecting an appropriate frequency is important: if the frequency is too short, the report contains too much data and consumes significant disk space; if the frequency is too long, the report does not contain enough information. Enter the value in either seconds (s) or minutes (m). For example:
<?xml version="1.0"?> <report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-group-config coherence-report-group-config.xsd"> <frequency>5m</frequency> ...
The <output-directory> element specifies the directory path to which reports are saved. The directory path is prepended to the output file name that is defined in the report configuration file. See Specifying General Report Characteristics. The user name that the member is executing must have read/write access to this path. The path can be absolute or relative to the directory where the cluster member starts (./). The following example saves the reports to the /output directory.
<?xml version="1.0"?>
<report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-group-config
coherence-report-group-config.xsd">
<frequency>5m</frequency>
<output-directory system-property=
"coherence.reporter.output.directory">/output</output-directory>
...
The <output-directory> element supports the use of a system-property attribute. The system-property attribute value is used at runtime to override the configured output directory. If a system property is not used to override the output directory, then the default output directory (./) is used. Any user-defined name can be used as the attribute value. The following example shows the default system property definition used by the predefined report group files:
<?xml version="1.0"?>
<report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-group-config
coherence-report-group-config.xsd">
<frequency>1m</frequency>
<output-directory system-property=
"coherence.reporter.output.directory">./</output-directory>
...
At runtime, specify the system property and include a path for the value. For example:
-Dcoherence.reporter.output.directory=/mydirectory
The <report-list> element specifies the name and location of any number of report configuration files. The path can be either a file or a URL. To enter a report configuration file, add a <location> element within a <report-config> element . For example:
<?xml version="1.0"?>
<report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-group-config
coherence-report-group-config.xsd">
<frequency>5m</frequency>
<output-directory>/output</output-directory>
<report-list>
<report-config>
<location>/config/myReport.xml</location>
</report-config>
<report-config>
<location>config/aSecondReport.xml</location>
</report-config>
</report-list>
</report-group>
The reporter configuration includes the option to select a custom report group configuration file. All the reports that are listed in the report group configuration file are generated at run time.
To configure the reporter to use a custom report group configuration file, edit the operational override file and within the <reporter> element, add a <configuration> element that is set to the location of a custom report group configuration file. The following example enables reporting and sets a custom report group configuration file:
<?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">
my-report-group.xml</configuration>
<autostart
system-property="coherence.management.report.autostart">true
</autostart>
</reporter>
</management-config>
</coherence>
The coherence.management.report.autostart and coherence.management.report.configuration system properties also enable reporting and configure a report group configuration file. For example:
-Dcoherence.management.report.autostart=true -Dcoherence.management.report.configuration=my-report-group.xml