6 Creating Custom Reports
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:
- Overview of Creating Custom Reports
Custom reports are created using MBeans that are registered in the Oracle Coherence MBean server (including custom MBeans). - Constructing Report Configuration Files
To create a custom report, construct a report configuration file that is based on thecoherence-report-config.xsd
file. - Creating Custom Report Group Configuration Files
To specify which reports to generate, create a report group configuration file that is based on thecoherence-report-group-config.xsd
file. - Configuring Custom Reports to Generate
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.
Overview of Creating Custom Reports
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 thecoherence.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 thecoherence.jar
library.
Parent topic: Creating Custom Reports
Constructing Report Configuration Files
coherence-report-config.xsd
file. See Report File Configuration Elements.
This section includes the following topics:
- Specifying General Report Characteristics
- Querying MBeans in Reports
- Specifying Data Columns
- Using Filters in Reports
- Using Functions in Reports
- Using Aggregates in Reports
- Constructing Delta Functions
Parent topic: Creating Custom Reports
Specifying General Report Characteristics
Table 6-1 describes the elements that configure general report characteristics.
Table 6-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:
file-name Macros
Table 6-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 6-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. |
Parent topic: Specifying General Report Characteristics
file-name Macro Examples
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>
Parent topic: Specifying General Report Characteristics
Querying MBeans in Reports
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 6-1 returns all registered Service
MBeans. See query.
Example 6-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 6-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 6-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>
Parent topic: Constructing Report Configuration Files
Specifying Data Columns
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:
- How to Include an Attribute
- How to Include Part of the Key
- How to Include Information from Composite Attributes
- How to Include Information from Multiple MBeans
- Including Multiple MBean Information Example
- How to Use Report Macros
- How to Include Constant Values
Parent topic: Constructing Report Configuration Files
How to Include an Attribute
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 6-3 illustrates how to include the RoleName
attribute from the query pattern Coherence:type=Node,*
.
Example 6-3 Including an Attribute Obtained from a Query Pattern
<column id = "RoleName"> <type>attribute</type> <name>RoleName</name> <header>Role Name</header> </column>
Parent topic: Specifying Data Columns
How to Include Part of the Key
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 6-4 illustrates how to include the nodeId
key part from the query pattern Coherence:type=Node,*
.
Example 6-4 Including Part of an ObjectName Key in a Report
<column id ="NodeId"> <type>key</type> <name>nodeId</name> <header>Node Id</header> </column>
Parent topic: Specifying Data Columns
How to Include Information from Composite Attributes
Use JMX composite values to include part of a composite data attribute (such as a Map
attribute) in a report.
Example 6-5 illustrates how to include the startTime
of the LastGCInfo
attribute from the GarbageCollector
MBean.
Example 6-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>
Parent topic: Specifying Data Columns
How to Include Information from Multiple MBeans
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.
Parent topic: Specifying Data Columns
Including Multiple MBean Information Example
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 6-6 shows the configuration for this scenario.
Example 6-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>
Parent topic: Specifying Data Columns
How to Use Report Macros
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 6-7 illustrates how to include the execution time into the report.
Example 6-7 Including Execution Time in a Report
<column id ="ReportTime"> <type>global</type> <name>{report-time}</name> <header>Report Time</header> </column>
Example 6-8 illustrates how to include the Report Batch/Count.
Example 6-8 Including the Report Batch/Count in a Report
<column id="ReportBatch"> <type>global</type> <name>{report-count}</name> <header>batch</header> </column>
Example 6-9 illustrates how to include the execution member.
Example 6-9 Including the Execution Member
<column id="ReportNode"> <type>global</type> <name>{report-node}</name> <header>ExecNode</header> <hidden>false</hidden> </column>
Parent topic: Specifying Data Columns
How to Include Constant Values
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 6-10 illustrates how to include a constant double of 1.0 in a report.
Example 6-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 6-11 illustrates how to include the constant string dist-Employee
in a report.
Example 6-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>
Parent topic: Specifying Data Columns
Using Filters in Reports
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 6-12 illustrates how to define an equals
filter where RoleRef
and StringRef
are defined columns.
Example 6-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 6-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 6-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 6-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 6-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 6-15 illustrates how to define an and
filter (assuming that all column-ref
values are valid).
Example 6-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 6-16 illustrates how to define an or
filter (assuming that all column-ref
values are valid).
Example 6-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 6-17 illustrates how to define a not
equals
filter, where RoleRef
and StringRef
are defined columns.
Example 6-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>
Parent topic: Constructing Report Configuration Files
Using Functions in Reports
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:
Parent topic: Constructing Report Configuration Files
Function Examples
Example 6-18 illustrates how to add two column values (Attribute1
and Attribute2
) and place the results into a third column (Addition
).
Example 6-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 6-19 illustrates how to subtract one column value (Attribute2
) from another column value (Attribute1
) and place the results into a third column (Subtraction
).
Example 6-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 6-20 illustrates how to multiply two column values (Attribute1
and Attribute2
) and place the results into a third column (Multiplication
).
Example 6-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 6-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 6-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>
Parent topic: Using Functions in Reports
Using Aggregates in Reports
Reporter aggregates combine multiple rows into a single value or row. Table 6-3 describes the available aggregate types.
Table 6-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 6-22 illustrates how to sum the values in the size
column.
Example 6-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 6-23 illustrates how to average the values in the size
column.
Example 6-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 6-24 illustrates how to find the maximum value in the size
column.
Example 6-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 6-25 illustrates how to find the minimum value in the size
column.
Example 6-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>
Parent topic: Constructing Report Configuration Files
Constructing Delta Functions
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:
Delta Function Examples
Example 6-26 illustrates how to include a delta calculation of an attribute. (Assume that PacketsSent
is a defined column.)
Example 6-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 6-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 6-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>
Parent topic: Constructing Delta Functions
Creating Custom Report Group Configuration Files
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:
- Specifying the Report Refresh Frequency
- Specifying the Output Directory for Reports
- Specifying the Report List
Parent topic: Creating Custom Reports
Specifying the Report Refresh Frequency
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> ...
Parent topic: Creating Custom Report Group Configuration Files
Specifying the Output Directory for Reports
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
Parent topic: Creating Custom Report Group Configuration Files
Specifying the Report List
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>
Parent topic: Creating Custom Report Group Configuration Files
Configuring Custom Reports to Generate
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
Parent topic: Creating Custom Reports