This chapter provides instructions for creating custom report definition files and creating custom report group configuration files.
The following sections are included in this chapter:
Custom reports can be created based on any MBeans residing in the Coherence MBean server domain (including custom MBeans). This allows different management data to be combined in meaningful ways that are specific to a cluster implementation. Custom reports are typically created during testing to correlate data an monitor trends when troubleshooting and planning for production.
Before creating custom reports, extract the predefined reporting configuration files that are located in the /reports directory of the coherence.jar library. Refer to the files when learning to create custom reports. The files can also be used as a starting point and modified as required.
JMX reporting utilizes two types of configuration files: a report configuration file and a report group configuration file.
Report Configuration File – A report configuration file is used to construct a report at run time. It includes the name of the report, which MBean data should be extracted, and how the data is organized. 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 is used to configure which reports are generated at run time. It includes the name and location of each report configuration file, the output directory to which reports are saved, and how often the reports are refreshed. Report group configuration files can be created as required. 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.
The topics in this section detail how to construct a report configuration file based on the coherence-report-config.xsd file. See Appendix B, "Report File Configuration Reference," for details about the report file configuration elements.
The following topics are included in this section:
To correctly generate the report file, several elements must be configured. These elements are described in Table 5-1.
Table 5-1 Elements to Configure an Output File
| Element | Optional/ Requited |
Description |
|---|---|---|
|
<file-name> |
Required |
The file name to create or update when the report is executed. |
|
<delim> |
Optional |
The column delimiter for the report. Valid values are |
|
<hide-headers> |
Optional |
A boolean element to determine if the headers are to be included in the report. If |
There are pre-defined macros that you can use with the file-name element. These macros can add a member name, a batch number, or a date to the generated file name.
Table 5-2 Macros that can be Used with the file-name Element
| Macro | Description |
|---|---|
|
sequence |
Adds a sequence number into the filename of the report. |
|
date |
Includes the date (with the format |
|
node |
Includes the member ID into the file name string. 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 200901012_network_status.txt on January 1, 2009, during hour 12. The filename 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 00012_network_status.txt when the report is executed on member 12. Note that due to the volatile nature of the Node Id, long term storage in this manner is not recommended.
<file-name>{node}_network_status.txt</file-name>
The following example creates a file 0000000021_network_status.txt on the 21st execution of the report. Note that due to the volatile nature of the batch, long term storage in this manner is not recommended.
<file-name>{sequence}_network_status.txt</file-name>
Data columns can be sourced from JMX Attributes, ObjectName key part, JMX composite attributes, JMX joined attributes, Report macros, and Report Constants.
To include data from MBeans returned from the query-pattern, the report must have a column with an attribute source. This is the most common item that is included in the report.
Example 5-1 illustrates how to include the RoleName attribute from the query pattern Coherence:type=Node,*.
A value that is present in an ObjectName key can be obtained from the ObjectNames returned from the query-pattern. This value can subsequently be included in the report.
Example 5-2 illustrates how to include the nodeId key part from the query pattern Coherence:type=Node,*.
JMX composite values are used to include part of a composite data attribute in a report.
Example 5-9 illustrates how to include the startTime of the LastGCInfo attribute from the query pattern java.lang:type=GarbageCollector,*.
A JMX join attribute is required when a report requires information from multiple MBeans. The major considerations when creating a join is to determine both the primary query, the join query and the foreign key. The primary query should be 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 that 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 for 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 curly braces "{}". The reporter does not check for cyclical references and fails during execution if a cycle is configured.
You can draw information from multiple MBeans and include it in a report. This requires a join between the MBeans.
|
Note: The major limitation ofjoin 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 a join attribute must be used.
Since a greater number of MBeans come from the Cache MBean, Coherence:type=Cache,* is the primary query and the 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. The configuration for this scenario is illustrated in Example 5-4.
Example 5-4 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>
There are three report macros that can be included in a report:
Report Time (report-time)—is the time and date that the report was executed. This information is useful for time series analysis.
Report Batch/Count (report-count)—is a long identifier that is used to correlate information from different reports executed at the same time.
Reporting Member (report-node)—is used when integrating information from the same report executed on different members or excluding the executing member information from the report.
To include the execution time into the report:
Example 5-5 Including Execution Time in a Report
<column id ="ReportTime">
<type>global</type>
<name>{report-time}</name>
<header>Report Time</header>
</column>
To include the Report Batch/Count:
Example 5-6 Including the Report Batch/Count in a Report
<column id="ReportBatch">
<type>global</type>
<name>{report-count}</name>
<header>batch</header>
</column>
To include the execution member:
Report constants are used for either static values or report parameters. These constants can be either double or string values. Often, these are used in filters to limit the results to a particular data set or in calculations.
Example 5-8 illustrates how to include a constant double of 1.0 in a report:
Example 5-8 Including a Constant Numeric Value in a Report
<column id ="One"> <type>constant</type> <header>Constant1</header> <hidden>true</hidden> <data-type>double</data-type> <value>1.0</value> </column>
Example 5-9 illustrates how to include the constant string dist-Employee in a report:
The query is the foundation of the information included in a report. Each query includes a query pattern, column references, and an optional filter reference. The query pattern is a string that is a JMX ObjectName query string. This string can return one or more MBeans. The column references must be defined in the <columns> section of the report definition file. The filter reference must be defined in the <filters> section of the report section.
Example 5-10 illustrates how to include the list all the Node IDs and RoleNames in the cluster where the RoleName equals CoherenceServer.
Example 5-10 Including a List of the Cluster's NodeIDs and RoleNames 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>
Filters limit the data returned in the Report. Filters are either comparison filters or composite filters. Comparison Filters evaluate the results of two columns while composite filters evaluate the boolean results from one or two filters. Comparison filters are equals, greater, and less.
Composite Filter types are and, or, and not. Each composite filter evaluates the filter parameters first to last and apply standard boolean logic. Composite filter evaluation uses standard short circuit logic. Cyclic references checks are not performed during execution. If a cyclic reference occurs, it creates a run-time error.
Example 5-11 illustrates how to define an equals filter where RoleRef and StringRef are defined columns.
Example 5-11 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-12 illustrates how to define a filter where the number of PacketsResent are greater than PacketsSent (assuming PacketsResent and PacketsSent are valid column references).
Example 5-12 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-13 illustrates how to define an filter where the number of PacketsResent are less than PacketsSent (assuming PacketsResent and PacketsSent are valid column references).
Example 5-13 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-14 illustrates how to define an and filter (assuming all column-ref values are valid).
Example 5-14 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-15 illustrates how to define an or filter (assuming all column-ref values are valid).
Example 5-15 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-16 illustrates how to define a not equals filter, where RoleRef and StringRef are defined columns.
Example 5-16 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 then be included as parameters into other function columns.
Example 5-17 illustrates how to add columns (Attribute1 and Attribute2) and place the results into a third column (Addition).
Example 5-17 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-18 illustrates how to subtract one column value (Attribute2) from another (Attribute1) and place the results into a third column (Subtraction).
Example 5-18 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-19 illustrates how to multiply column values (Attribute1 and Attribute2) place the results into a third column (Multiplication).
Example 5-19 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-20 illustrates how to divide one column (Attribute1) by another (Attribute2) into a third column (Division). The result of all division is a Double data type.
Example 5-20 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 allow for multiple rows to be aggregated 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. |
Sum the values in the size column
Example 5-21 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>
Average the values in the size column
Example 5-22 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>
Find the maximum the value in the size column
Example 5-23 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>
Find the minimum the value in the size column
Many numeric attributes in the Coherence 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.
The prior values for a report are stored in a map on the Reporter client. This map is keyed by the "delta key". By default, the delta key is the MBean name for the attribute. However, when 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: Accuracy of Delta Functions: delta functions are only correct when the report is running as part of a report batch. |
Example 5-25 illustrates how to include a delta calculation of an attribute. (Assume PacketsSent is a defined column)
Example 5-25 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-26 illustrates how to include a delta calculation of an attribute with an alternate delta key. (Assume PacketsSent, NodeID and TimeStamp are defined columns)
Example 5-26 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>
The topics in this section detail how to create a report group configuration file based on the coherence-report-group-config.xsd file. This configuration file is used at run time to determine what reports get generated, how often the reports get refreshed, and where the reports are saved. If a single report can be used with different parameters, these parameters are also configured. See Appendix C, "Report Group Configuration Reference," for details about the report group configuration elements.
The following topics are included in this section:
The <frequency> element specifies how often the reports are refreshed. Selecting an appropriate frequency is critical. If the frequency is too short, the reporter can generate a large amount of data and consume significant disk space. If the frequency is too long, not enough information is generated. The value is entered 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 <ouput-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 username which the member is executing must have read/write access to this path. The path can be absolute or relative to directory where the cluster member was started (./). 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>/output</output-directory> ...
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>
To configure custom reports to generate, JMX reporting must be enabled and the reporter must be configured to use a custom report group configuration file. See "Enabling JMX Reporting On a Cluster Member" for details on enabling JMX reporting.
To configure the reporter to use a custom report group configuration file , edit the operational override file and add a <configuration> element, within the <reporter> element, that is set to the location of a custom report group configuration file. The following example enables JMX 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="tangosol.coherence.management.report.configuration">
my-report-group.xml</configuration>
<autostart
system-property="tangosol.coherence.management.report.autostart">true
</autostart>
</reporter>
</management-config>
</coherence>
The tangosol.coherence.management.report.autostart and tangosol.coherence.management.report.configuration system property are used to enable JMX reporting and configure a report group configuration file instead of using the operational override file. For example:
-Dtangosol.coherence.management.report.autostart=true -Dtangosol.coherence.management.report.configuration=my-report-group.xml